File Search Stores

توفّر واجهة برمجة التطبيقات File Search API خدمة مستضافة للإجابة عن الأسئلة من أجل إنشاء أنظمة التوليد المعزّز بالاسترجاع باستخدام البنية الأساسية من Google.

الطريقة: media.uploadToFileSearchStore

تحميل البيانات إلى FileSearchStore، ومعالجتها مسبقًا وتقسيمها إلى أجزاء قبل تخزينها في مستند FileSearchStore

نقطة نهاية

  • معرّف الموارد المنتظم (URI) للتحميل، لطلبات تحميل الوسائط:
 post https://generativelanguage.googleapis.com/upload/v1beta/{fileSearchStoreName=fileSearchStores/*}:uploadToFileSearchStore
  • معرّف الموارد المنتظم للبيانات الوصفية، للطلبات التي تتضمّن البيانات الوصفية فقط:
 post https://generativelanguage.googleapis.com/v1beta/{fileSearchStoreName=fileSearchStores/*}:uploadToFileSearchStore

مَعلمات المسار

fileSearchStoreName string

الحقل مطلوب. غير قابل للتغيير اسم FileSearchStore الذي سيتم تحميل الملف إليه. مثال: fileSearchStores/my-file-search-store-123 ويكون بالتنسيق التالي: fileSearchStores/{filesearchstore}.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

الحقول
displayName string

اختيارية: الاسم المعروض للمستند الذي تم إنشاؤه

customMetadata[] object (CustomMetadata)

بيانات التعريف المخصّصة التي سيتم ربطها بالبيانات

chunkingConfig object (ChunkingConfig)

اختيارية: إعدادات لتحديد كيفية تقسيم البيانات إلى أجزاء. في حال عدم توفيرها، ستستخدم الخدمة المَعلمات التلقائية.

mimeType string

اختيارية: نوع MIME للبيانات في حال عدم توفيرها، سيتم استنتاجها من المحتوى الذي تم تحميله.

نص الاستجابة

هذه نسخة من google.longrunning.Operation. علينا نسخها لأنّه للتفاعل مع Scotty، يجب إضافة حقل خاص بـ Scotty لا يمكن إضافته في Operation proto ذي المستوى الأعلى.

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

الحقول
name string

هو الاسم الذي يُعيّنه الخادم، ويكون فريدًا فقط ضمن الخدمة نفسها التي أرسلت الاسم في الاستجابة. إذا كنت تستخدم أسلوب ربط HTTP التلقائي، يجب أن يكون حقل name اسم مورد ينتهي بالشكل التالي: operations/{unique_id}.

metadata object

يشير الحقل إلى بيانات وصفية خاصة بالخدمة ومرتبطة بالعملية. يتضمّن عادةً معلومات حول مستوى تقدّم العملية وبيانات وصفية شائعة مثل وقت الإنشاء. يُرجى الِعلم أنّ بعض الخدمات قد لا توفّر هذه البيانات. إذا أدّى إجراء ما إلى بدء عملية طويلة، يجب أن يوثّق نوع البيانات الوصفية، إن وُجدِت.

هو كائن يحتوي على حقول من أي نوع، بالإضافة إلى حقل "@type" الذي يتضمّن معرف موارد منتظم (URI) يحدّد نوع الكائن، مثل { "id": 1234, "@type": "types.example.com/standard/id" }.

done boolean

إذا كانت القيمة false، هذا يعني أنّ العملية ما زالت قيد التنفيذ. أما إذا كانت true، فهذا يعني أنّ العملية اكتملت، ويمكن عندها الوصول إلى error أو response.

result Union type
تمثّل نتيجة العملية، والتي يمكن أن تكون إما error أو response صالحة. إذا كان false ‏ == done، هذا يعني أنّه لم يتم ضبط أي من error أو response. إذا كان true ‏ == done، هذا يعني أنّه يمكن ضبط إما error أو response فقط. بعض الخدمات قد لا توفّر النتيجة. يمكن أن تكون result إحدى القيم التالية فقط:
error object (Status)

يمثّل نتيجة الخطأ للعملية في حال فشلها أو إلغائها.

response object

يشير هذا الحقل إلى الاستجابة المعتادة إذا كانت العملية ناجحة. إذا كان الإجراء الأصلي لا يعرض أي بيانات عند نجاحه، مثل Delete، تكون الاستجابة google.protobuf.Empty. وإذا كان الإجراء الأصلي أحد العمليات الشائعة مثل Get أو Create أو Update، يجب أن تكون الاستجابة هي المورد نفسه. أما بالنسبة إلى الإجراءات الأخرى، فيجب أن يكون نوع الاستجابة بصيغة XxxResponse، حيث يمثّل Xxx اسم الإجراء الأصلي. على سبيل المثال، إذا كان اسم الإجراء الأصلي TakeSnapshot()، سيكون نوع الاستجابة المستنتَج TakeSnapshotResponse.

هو كائن يحتوي على حقول من أي نوع، بالإضافة إلى حقل "@type" الذي يتضمّن معرف موارد منتظم (URI) يحدّد نوع الكائن، مثل { "id": 1234, "@type": "types.example.com/standard/id" }.

تمثيل JSON 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}

الطريقة: fileSearchStores.create

تنشئ هذه الدالة FileSearchStore فارغًا.

نقطة نهاية

post https://generativelanguage.googleapis.com/v1beta/fileSearchStores

نص الطلب

يحتوي نص الطلب على مثال FileSearchStore.

الحقول
displayName string

اختيارية: تمثّل هذه السمة الاسم المعروض FileSearchStore الذي يمكن للمستخدم قراءته. يجب ألا يزيد طول الاسم المعروض عن 512 حرفًا، بما في ذلك المسافات. مثال: "مستندات حول Semantic Retriever"

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيحتوي نصها على مثال تم إنشاؤه حديثًا FileSearchStore.

الطريقة: fileSearchStores.delete

يحذف FileSearchStore.

نقطة نهاية

delete https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*}

مَعلمات المسار

name string

الحقل مطلوب. اسم المورّد الخاص بـ FileSearchStore. مثال: fileSearchStores/my-file-search-store-123 ويكون بالتنسيق التالي: fileSearchStores/{filesearchstore}.

مَعلمات طلب البحث

force boolean

اختيارية: في حال ضبطها على "صحيح"، سيتم أيضًا حذف أي Document وعناصر ذات صلة بهذا FileSearchStore.

إذا كانت القيمة خطأ (القيمة التلقائية)، سيتم عرض الخطأ FAILED_PRECONDITION إذا كان FileSearchStore يحتوي على أي Document.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيكون نص الاستجابة عبارة عن كائن JSON فارغ.

الطريقة: fileSearchStores.get

تعرض هذه السمة معلومات حول FileSearchStore معيّن.

نقطة نهاية

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*}

مَعلمات المسار

name string

الحقل مطلوب. تمثّل هذه السمة اسم FileSearchStore. مثال: fileSearchStores/my-file-search-store-123 ويكون بالتنسيق التالي: fileSearchStores/{filesearchstore}.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال FileSearchStore.

الطريقة: fileSearchStores.list

تعرض هذه السمة جميع FileSearchStores التي يملكها المستخدم.

نقطة نهاية

get https://generativelanguage.googleapis.com/v1beta/fileSearchStores

مَعلمات طلب البحث

pageSize integer

اختيارية: الحدّ الأقصى لعدد FileSearchStores المطلوب عرضه (في كل صفحة) قد تعرض الخدمة عددًا أقل من FileSearchStores.

إذا لم يتم تحديد عدد، سيتم عرض 10 FileSearchStores على الأكثر. الحدّ الأقصى للحجم هو 20 FileSearchStores لكل صفحة.

pageToken string

اختيارية: رمز مميز للصفحة تم تلقّيه من طلب fileSearchStores.list سابق.

قدِّم nextPageToken الذي تم عرضه في الرد كمعلَمة للطلب التالي لاسترداد الصفحة التالية.

عند تقسيم النتائج إلى صفحات، يجب أن تتطابق جميع المَعلمات الأخرى المقدَّمة إلى fileSearchStores.list مع الطلب الذي قدّم رمز الصفحة المميز.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

استجابة من fileSearchStores.list تحتوي على قائمة مقسّمة إلى صفحات من FileSearchStores يتم ترتيب النتائج حسب fileSearchStore.create_time تصاعديًا.

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

الحقول
fileSearchStores[] object (FileSearchStore)

تم إرجاع ragStores.

nextPageToken string

رمز مميز يمكن إرساله كـ pageToken لاسترداد الصفحة التالية إذا تم حذف هذا الحقل، لن يكون هناك المزيد من الصفحات.

تمثيل JSON 
{
  "fileSearchStores": [
    {
      object (FileSearchStore)
    }
  ],
  "nextPageToken": string
}

الطريقة: fileSearchStores.importFile

يستورد هذا الإجراء ملف File من "خدمة الملفات" إلى FileSearchStore.

نقطة نهاية

post https://generativelanguage.googleapis.com/v1beta/{fileSearchStoreName=fileSearchStores/*}:importFile

مَعلمات المسار

fileSearchStoreName string

الحقل مطلوب. غير قابل للتغيير اسم FileSearchStore الذي سيتم استيراد الملف إليه. مثال: fileSearchStores/my-file-search-store-123 ويكون بالتنسيق التالي: fileSearchStores/{filesearchstore}.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

الحقول
fileName string

الحقل مطلوب. اسم File المطلوب استيراده. مثال: files/abc-123

customMetadata[] object (CustomMetadata)

بيانات وصفية مخصّصة سيتم ربطها بالملف

chunkingConfig object (ChunkingConfig)

اختيارية: إعدادات لتحديد كيفية تقسيم الملف إلى أجزاء. في حال عدم توفيرها، ستستخدم الخدمة المَعلمات التلقائية.

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال Operation.

مورد REST: ‏ fileSearchStores.operations

المورد: العملية

يمثّل هذا المورد عملية طويلة ناتجة عن طلب بيانات من واجهة برمجة التطبيقات من الشبكة.

الحقول
name string

هو الاسم الذي يُعيّنه الخادم، ويكون فريدًا فقط ضمن الخدمة نفسها التي أرسلت الاسم في الاستجابة. إذا كنت تستخدم أسلوب ربط HTTP التلقائي، يجب أن يكون حقل name اسم مورد ينتهي بالشكل التالي: operations/{unique_id}.

metadata object

يشير الحقل إلى بيانات وصفية خاصة بالخدمة ومرتبطة بالعملية. يتضمّن عادةً معلومات حول مستوى تقدّم العملية وبيانات وصفية شائعة مثل وقت الإنشاء. يُرجى الِعلم أنّ بعض الخدمات قد لا توفّر هذه البيانات. إذا أدّى إجراء ما إلى بدء عملية طويلة، يجب أن يوثّق نوع البيانات الوصفية، إن وُجدِت.

هو كائن يحتوي على حقول من أي نوع، بالإضافة إلى حقل "@type" الذي يتضمّن معرف موارد منتظم (URI) يحدّد نوع الكائن، مثل { "id": 1234, "@type": "types.example.com/standard/id" }.

done boolean

إذا كانت القيمة false، هذا يعني أنّ العملية ما زالت قيد التنفيذ. أما إذا كانت true، فهذا يعني أنّ العملية اكتملت، ويمكن عندها الوصول إلى error أو response.

result Union type
تمثّل نتيجة العملية، والتي يمكن أن تكون إما error أو response صالحة. إذا كان false ‏ == done، هذا يعني أنّه لم يتم ضبط أي من error أو response. إذا كان true ‏ == done، هذا يعني أنّه يمكن ضبط إما error أو response فقط. بعض الخدمات قد لا توفّر النتيجة. يمكن أن تكون result إحدى القيم التالية فقط:
error object (Status)

يمثّل نتيجة الخطأ للعملية في حال فشلها أو إلغائها.

response object

يشير هذا الحقل إلى الاستجابة المعتادة إذا كانت العملية ناجحة. إذا كان الإجراء الأصلي لا يعرض أي بيانات عند نجاحه، مثل Delete، تكون الاستجابة google.protobuf.Empty. وإذا كان الإجراء الأصلي أحد العمليات الشائعة مثل Get أو Create أو Update، يجب أن تكون الاستجابة هي المورد نفسه. أما بالنسبة إلى الإجراءات الأخرى، فيجب أن يكون نوع الاستجابة بصيغة XxxResponse، حيث يمثّل Xxx اسم الإجراء الأصلي. على سبيل المثال، إذا كان اسم الإجراء الأصلي TakeSnapshot()، سيكون نوع الاستجابة المستنتَج TakeSnapshotResponse.

هو كائن يحتوي على حقول من أي نوع، بالإضافة إلى حقل "@type" الذي يتضمّن معرف موارد منتظم (URI) يحدّد نوع الكائن، مثل { "id": 1234, "@type": "types.example.com/standard/id" }.

تمثيل JSON 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}

الطريقة: fileSearchStores.operations.get

تتيح هذه الطريقة الاطّلاع على أحدث حالة لعملية طويلة، ويمكن للعملاء استخدامها للتحقّق من نتيجة العملية على فترات زمنية منتظمة تنصح بها خدمة واجهة برمجة التطبيقات.

نقطة نهاية

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*/operations/*}

مَعلمات المسار

name string

يمثّل اسم مورد العملية. ويكون بالتنسيق التالي: fileSearchStores/{filesearchstore}/operations/{operation}.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال Operation.

مورد REST: ‏ fileSearchStores.upload.operations

المورد: العملية

يمثّل هذا المورد عملية طويلة ناتجة عن طلب بيانات من واجهة برمجة التطبيقات من الشبكة.

الحقول
name string

هو الاسم الذي يُعيّنه الخادم، ويكون فريدًا فقط ضمن الخدمة نفسها التي أرسلت الاسم في الاستجابة. إذا كنت تستخدم أسلوب ربط HTTP التلقائي، يجب أن يكون حقل name اسم مورد ينتهي بالشكل التالي: operations/{unique_id}.

metadata object

يشير الحقل إلى بيانات وصفية خاصة بالخدمة ومرتبطة بالعملية. يتضمّن عادةً معلومات حول مستوى تقدّم العملية وبيانات وصفية شائعة مثل وقت الإنشاء. يُرجى الِعلم أنّ بعض الخدمات قد لا توفّر هذه البيانات. إذا أدّى إجراء ما إلى بدء عملية طويلة، يجب أن يوثّق نوع البيانات الوصفية، إن وُجدِت.

هو كائن يحتوي على حقول من أي نوع، بالإضافة إلى حقل "@type" الذي يتضمّن معرف موارد منتظم (URI) يحدّد نوع الكائن، مثل { "id": 1234, "@type": "types.example.com/standard/id" }.

done boolean

إذا كانت القيمة false، هذا يعني أنّ العملية ما زالت قيد التنفيذ. أما إذا كانت true، فهذا يعني أنّ العملية اكتملت، ويمكن عندها الوصول إلى error أو response.

result Union type
تمثّل نتيجة العملية، والتي يمكن أن تكون إما error أو response صالحة. إذا كان false ‏ == done، هذا يعني أنّه لم يتم ضبط أي من error أو response. إذا كان true ‏ == done، هذا يعني أنّه يمكن ضبط إما error أو response فقط. بعض الخدمات قد لا توفّر النتيجة. يمكن أن تكون result إحدى القيم التالية فقط:
error object (Status)

يمثّل نتيجة الخطأ للعملية في حال فشلها أو إلغائها.

response object

يشير هذا الحقل إلى الاستجابة المعتادة إذا كانت العملية ناجحة. إذا كان الإجراء الأصلي لا يعرض أي بيانات عند نجاحه، مثل Delete، تكون الاستجابة google.protobuf.Empty. وإذا كان الإجراء الأصلي أحد العمليات الشائعة مثل Get أو Create أو Update، يجب أن تكون الاستجابة هي المورد نفسه. أما بالنسبة إلى الإجراءات الأخرى، فيجب أن يكون نوع الاستجابة بصيغة XxxResponse، حيث يمثّل Xxx اسم الإجراء الأصلي. على سبيل المثال، إذا كان اسم الإجراء الأصلي TakeSnapshot()، سيكون نوع الاستجابة المستنتَج TakeSnapshotResponse.

هو كائن يحتوي على حقول من أي نوع، بالإضافة إلى حقل "@type" الذي يتضمّن معرف موارد منتظم (URI) يحدّد نوع الكائن، مثل { "id": 1234, "@type": "types.example.com/standard/id" }.

تمثيل JSON 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}

الطريقة: fileSearchStores.upload.operations.get

تتيح هذه الطريقة الاطّلاع على أحدث حالة لعملية طويلة، ويمكن للعملاء استخدامها للتحقّق من نتيجة العملية على فترات زمنية منتظمة تنصح بها خدمة واجهة برمجة التطبيقات.

نقطة نهاية

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*/upload/operations/*}

مَعلمات المسار

name string

يمثّل اسم مورد العملية. ويكون بالتنسيق التالي: fileSearchStores/{filesearchstore}/upload/operations/{operation}.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال Operation.

مورد REST: ‏ fileSearchStores

المورد: FileSearchStore

FileSearchStore هي مجموعة من Document.

الحقول
name string

النتائج فقط. غير قابل للتغيير المعرّف اسم مورد FileSearchStore وهو معرّف (اسم باستثناء البادئة "fileSearchStores/") يمكن أن يحتوي على ما يصل إلى 40 حرفًا أبجديًا رقميًا صغيرًا أو شُرطًا (-). وهو قيمة للناتج فقط. سيتم اشتقاق الاسم الفريد من displayName بالإضافة إلى لاحقة عشوائية مكوّنة من 12 حرفًا. مثال: fileSearchStores/my-awesome-file-search-store-123a456b789c في حال عدم توفير displayName، سيتم إنشاء الاسم بشكل عشوائي.

displayName string

اختيارية: تمثّل هذه السمة الاسم المعروض FileSearchStore الذي يمكن للمستخدم قراءته. يجب ألا يزيد طول الاسم المعروض عن 512 حرفًا، بما في ذلك المسافات. مثال: "مستندات حول Semantic Retriever"

createTime string (Timestamp format)

النتائج فقط. الطابع الزمني لوقت إنشاء FileSearchStore

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

النتائج فقط. الطابع الزمني لآخر مرة تم فيها تعديل FileSearchStore

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

activeDocumentsCount string (int64 format)

النتائج فقط. عدد المستندات في FileSearchStore النشطة والجاهزة للاسترداد

pendingDocumentsCount string (int64 format)

النتائج فقط. عدد المستندات في FileSearchStore التي تتم معالجتها.

failedDocumentsCount string (int64 format)

النتائج فقط. عدد المستندات في FileSearchStore التي تعذّرت معالجتها

sizeBytes string (int64 format)

النتائج فقط. حجم البايتات الأولية التي تمّ استيعابها في FileSearchStore هذا هو الحجم الإجمالي لجميع المستندات في FileSearchStore.

تمثيل JSON 
{
  "name": string,
  "displayName": string,
  "createTime": string,
  "updateTime": string,
  "activeDocumentsCount": string,
  "pendingDocumentsCount": string,
  "failedDocumentsCount": string,
  "sizeBytes": string
}