Documents

تشير File Search API إلى ملفات المصدر الأولية أو المستندات كعناصر File مؤقتة.

الطريقة: fileSearchStores.documents.delete

يحذف Document.

نقطة نهاية

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

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

name string

الحقل مطلوب. اسم مورد Document المطلوب حذفه. مثال: fileSearchStores/my-file-search-store-123/documents/the-doc-abc ويكون بالتنسيق التالي: fileSearchStores/{filesearchstore}/documents/{document}.

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

force boolean

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

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

نص الطلب

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

نص الاستجابة

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

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

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

نقطة نهاية

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

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

name string

الحقل مطلوب. تمثّل هذه السمة اسم Document المطلوب استرداده. مثال: fileSearchStores/my-file-search-store-123/documents/the-doc-abc ويكون بالتنسيق التالي: fileSearchStores/{filesearchstore}/documents/{document}.

نص الطلب

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

نص الاستجابة

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

الطريقة: fileSearchStores.documents.list

تعرض هذه السمة جميع Document في Corpus.

نقطة نهاية

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

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

parent string

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

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

pageSize integer

اختيارية: الحد الأقصى لعدد Documents التي سيتم عرضها (في كل صفحة) قد تعرض الخدمة عددًا أقل من Document.

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

pageToken string

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

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

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

نص الطلب

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

نص الاستجابة

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

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

الحقول
documents[] object (Document)

تم إرجاع Document.

nextPageToken string

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

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

الطريقة: fileSearchStores.documents.query

تُجري هذه الدالة بحثًا دلاليًا في Document.

نقطة نهاية

post https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*/documents/*}:query

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

name string

الحقل مطلوب. تمثّل هذه السمة اسم Document المطلوب البحث عنه. مثال: fileSearchStores/my-file-search-store-123/documents/the-doc-abc ويكون بالتنسيق التالي: fileSearchStores/{filesearchstore}/documents/{document}.

نص الطلب

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

الحقول
query string

الحقل مطلوب. سلسلة طلب البحث لإجراء البحث الدلالي

resultsCount integer

اختيارية: الحد الأقصى لعدد Chunk المطلوب عرضه. قد تعرض الخدمة عددًا أقل من Chunk.

إذا لم يتم تحديد عدد، سيتم عرض 10 Chunk على الأكثر. الحد الأقصى لعدد النتائج المحدّد هو 100.

metadataFilters[] object (MetadataFilter)

اختيارية: فلترة البيانات الوصفية حسب Chunk يجب أن يتوافق كل عنصر MetadataFilter مع مفتاح فريد. يتم ربط عناصر MetadataFilter المتعددة باستخدام عوامل التشغيل المنطقية "و".

ملاحظة: لا تتوفّر فلترة على مستوى Document لهذا الطلب لأنّه تم تحديد اسم Document من قبل.

مثال على طلب البحث: (year >= 2020 OR year < 2010) AND (genre = drama OR genre = action)

MetadataFilter object list: metadataFilters = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2020, operation = GREATER_EQUAL}, {int_value = 2010, operation = LESS}}, {key = "chunk.custom_metadata.genre" conditions = [{stringValue = "drama", operation = EQUAL}, {stringValue = "action", operation = EQUAL}}]

مثال على طلب بحث عن نطاق رقمي من القيم: (year > 2015 AND year <= 2020)

MetadataFilter object list: metadataFilters = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2015, operation = GREATER}]}, {key = "chunk.custom_metadata.year" conditions = [{int_value = 2020, operation = LESS_EQUAL}]}]

ملاحظة: لا يمكن استخدام "AND" للمفتاح نفسه إلا مع القيم الرقمية. لا تتوافق قيم السلسلة إلا مع "أو" للمفتاح نفسه.

نص الاستجابة

استجابة من documents.query تحتوي على قائمة بالفقرات ذات الصلة.

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

الحقول
relevantChunks[] object (RelevantChunk)

الفقرات ذات الصلة التي تم إرجاعها

تمثيل JSON 
{
  "relevantChunks": [
    {
      object (RelevantChunk)
    }
  ]
}

مورد REST: ‏ fileSearchStores.documents

المورد: مستند

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

الحقول
name string

غير قابل للتغيير المعرّف اسم مورد Document يمكن أن يحتوي المعرّف (الاسم باستثناء البادئة "fileSearchStores/*/documents/") على ما يصل إلى 40 حرفًا أبجديًا رقميًا صغيرًا أو شرطات (-)، ولا يمكن أن يبدأ المعرّف أو ينتهي بشرطة. إذا كان الاسم فارغًا عند الإنشاء، سيتم استخلاص اسم فريد من displayName مع لاحقة عشوائية مكوّنة من 12 حرفًا. مثال: fileSearchStores/{file_search_store_id}/documents/my-awesome-doc-123a456b789c

displayName string

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

customMetadata[] object (CustomMetadata)

اختيارية: البيانات الوصفية المخصّصة المقدَّمة من المستخدِم والمخزَّنة كأزواج من المفاتيح والقيم تُستخدَم في طلبات البحث. يمكن أن يتضمّن Document ما يصل إلى 20 CustomMetadata.

updateTime string (Timestamp format)

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

يستخدم المعيار 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".

createTime string (Timestamp format)

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

يستخدم المعيار 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".

state enum (State)

النتائج فقط. الحالة الحالية Document

sizeBytes string (int64 format)

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

mimeType string

النتائج فقط. نوع MIME الخاص بالمستند.

تمثيل JSON 
{
  "name": string,
  "displayName": string,
  "customMetadata": [
    {
      object (CustomMetadata)
    }
  ],
  "updateTime": string,
  "createTime": string,
  "state": enum (State),
  "sizeBytes": string,
  "mimeType": string
}

ولاية

حالات مراحل النشاط في Document

عمليات التعداد
STATE_UNSPECIFIED القيمة التلقائية يتم استخدام هذه القيمة في حال عدم تحديد الولاية.
STATE_PENDING تتم حاليًا معالجة بعض Chunks من Document (التضمين وتخزين المتجهات).
STATE_ACTIVE تتم معالجة كل Chunks من Document وتصبح متاحة للاستعلام.
STATE_FAILED تعذّر معالجة بعض Chunks من Document.