الطريقة: corpora.documents.create
لإنشاء Document
فارغ
نقطة نهاية
منشور
https://generativelanguage.googleapis.com/v1beta/{parent=corpora/*}/documents
مَعلمات المسار
parent
string
مطلوب. اسم Corpus
الذي سيتم إنشاء Document
فيه مثال: corpora/my-corpus-123
تأخذ الشكل corpora/{corpora}
.
نص الطلب
يحتوي نص الطلب على مثال Document
.
name
string
غير قابل للتغيير. المُعرّف. اسم المورد Document
يمكن أن يحتوي رقم التعريف (الاسم باستثناء البادئة "corpora/*/documents/") على 40 حرفًا أبجديًا رقميًا صغيرًا أو شرطات (-). لا يمكن أن يبدأ المعرّف أو ينتهي بشرطة. إذا كان الاسم فارغًا عند الإنشاء، سيتم إنشاء اسم فريد من displayName
مع إضافة لاحقة عشوائية من 12 حرفًا. مثلاً: corpora/{corpus_id}/documents/my-awesome-doc-123a456b789c
displayName
string
اختياريّ. الاسم المعروض السهل القراءة لـ Document
. يجب ألا يزيد طول الاسم المعروض عن 512 حرفًا، بما في ذلك المسافات. مثال: "مستندات Semantic Retriever"
customMetadata[]
object (CustomMetadata
)
اختياريّ. البيانات الوصفية المخصّصة التي قدّمها المستخدم والمخزّنة كأزواج المفتاح/القيمة تُستخدَم لطلب البحث يمكن أن يتضمّن Document
20 CustomMetadata
كحدّ أقصى.
نص الاستجابة
في حال نجاح الإجراء، يحتوي نص الاستجابة على مثيل Document
تم إنشاؤه حديثًا.
الطريقة: corpora.documents.query
تُجري عملية بحث دلالي على Document
.
نقطة نهاية
منشور
https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}:query
مَعلمات المسار
name
string
مطلوب. اسم Document
المطلوب طلبه. مثال: corpora/my-corpus-123/documents/the-doc-abc
يكون على الشكل corpora/{corpora}/documents/{document}
.
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
query
string
مطلوب. سلسلة طلب البحث لإجراء البحث الدلالي
resultsCount
integer
اختياريّ. الحد الأقصى لعدد Chunk
s المطلوب عرضها. قد تعرض الخدمة عددًا أقل من Chunk
.
إذا لم يتم تحديد عدد، سيتم عرض 10 Chunk
كحد أقصى. الحد الأقصى لعدد النتائج المحددة هو 100.
metadataFilters[]
object (MetadataFilter
)
اختياريّ. فلتِر البيانات حسب البيانات الوصفية Chunk
. يجب أن يكون كل عنصر MetadataFilter
متوافقًا مع مفتاح فريد. يتمّ دمج عناصر MetadataFilter
متعدّدة باستخدام عوامل التشغيل المنطقية "و".
ملاحظة: لا يمكن إجراء فلترة على مستوى Document
لهذا الطلب لأنّه سبق أن تم تحديد اسم Document
.
مثال على طلب البحث: (year >= 2020 OR year < 2010) AND (genre = تأكّد OR genre = action)
MetadataFilter
object list: metadataFilters = [ {key = "chunk.custom_metadata.year" الشروط = [{int_value = 2020, العملية = 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" الشروط = [{int_value = 2015, العملية = GREATER}]}, {key = "chunk.custom_metadata.year" الشروط = [{int_value = 2020, العملية = LESS_EQUAL}]}]
ملاحظة: تتوفر أحرف "و" للمفتاح نفسه للقيم الرقمية فقط. لا تتيح قيم السلاسل استخدام "أو" إلا للمفتاح نفسه.
نص الاستجابة
ردّ من documents.query
يحتوي على قائمة بالأجزاء ذات الصلة
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
relevantChunks[]
object (RelevantChunk
)
الأجزاء ذات الصلة التي تم إرجاعها.
تمثيل JSON |
---|
{
"relevantChunks": [
{
object ( |
الطريقة: corpora.documents.list
يتم إدراج جميع Document
في Corpus
.
نقطة نهاية
الحصول على
https://generativelanguage.googleapis.com/v1beta/{parent=corpora/*}/documents
مَعلمات المسار
parent
string
مطلوب. اسم Corpus
الذي يحتوي على Document
مثال: corpora/my-corpus-123
تأخذ الشكل corpora/{corpora}
.
معامِلات طلب البحث
pageSize
integer
اختياريّ. الحد الأقصى لعدد Document
التي سيتم عرضها (لكل صفحة). قد تعرض الخدمة عددًا أقل من 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 ( |
الطريقة: corpora.documents.get
يتيح هذا الخيار الحصول على معلومات عن Document
محدّد.
نقطة نهاية
get
https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}
مَعلمات المسار
name
string
مطلوب. اسم Document
المطلوب استرجاعه مثال: corpora/my-corpus-123/documents/the-doc-abc
تأخذ الشكل corpora/{corpora}/documents/{document}
.
نص الطلب
يجب أن يكون نص الطلب فارغًا.
نص الاستجابة
إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال Document
.
الطريقة: corpora.documents.patch
يعدِّل Document
.
نقطة نهاية
تصحيح
https://generativelanguage.googleapis.com/v1beta/{document.name=corpora/*/documents/*}
PATCH https://generativelanguage.googleapis.com/v1beta/{document.name=corpora/*/documents/*}
مَعلمات المسار
document.name
string
غير قابل للتغيير المعرّف اسم المورد "Document
". يمكن أن يحتوي المعرّف (الاسم باستثناء البادئة "corpora/*/documents/") على ما يصل إلى 40 حرفًا أبجديًا رقميًا صغيرًا أو شرطات (-). ولا يمكن أن يبدأ المعرّف بشرطة أو ينتهي بها. إذا كان الاسم فارغًا عند الإنشاء، سيتم اشتقاق اسم فريد من displayName
مع لاحقة عشوائية مكوّنة من 12 حرفًا. مثال: corpora/{corpus_id}/documents/my-awesome-doc-123a456b789c
تأخذ الشكل corpora/{corpora}/documents/{document}
.
معامِلات طلب البحث
updateMask
string (FieldMask
format)
مطلوب. قائمة الحقول المطلوب تعديلها. في الوقت الحالي، يتيح هذا التحديث تحديث displayName
وcustomMetadata
فقط.
هذه قائمة مفصولة بفواصل تتضمّن أسماء حقول مؤهَّلة بالكامل. مثال: "user.displayName,photo"
نص الطلب
يحتوي نص الطلب على مثال Document
.
displayName
string
اختياريّ. تمثّل هذه السمة الاسم المعروض لـ Document
الذي يمكن للمستخدمين قراءته. يجب ألا يزيد طول الاسم المعروض عن 512 حرفًا، بما في ذلك المسافات. مثال: "مستندات أداة البحث الدلالي"
customMetadata[]
object (CustomMetadata
)
اختياريّ. البيانات الوصفية المخصّصة التي قدّمها المستخدم والمخزّنة كأزواج المفتاح/القيمة تُستخدَم لطلب البحث يمكن أن يتضمّن Document
20 CustomMetadata
كحدّ أقصى.
نص الاستجابة
إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال Document
.
الطريقة: corpora.documents.delete
يؤدي هذا الإجراء إلى حذف Document
.
نقطة نهاية
حذف
https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}
مَعلمات المسار
name
string
مطلوب. اسم المورد للDocument
المطلوب حذفه. مثال: corpora/my-corpus-123/documents/the-doc-abc
تأخذ الشكل corpora/{corpora}/documents/{document}
.
معامِلات طلب البحث
force
boolean
اختياريّ. في حال ضبطها على "صحيح"، سيتم أيضًا حذف أي Chunk
وعناصر مرتبطة بهذا Document
.
وفي حال كانت القيمة "خطأ" (الخيار التلقائي)، سيتم عرض خطأ FAILED_PRECONDITION
إذا كانت السمة Document
تحتوي على أي قيم Chunk
.
نص الطلب
يجب أن يكون نص الطلب فارغًا.
نص الاستجابة
إذا كانت الاستجابة ناجحة، يكون نص الاستجابة فارغًا.
مورد REST: corpora.documents
المرجع: مستند
السمة Document
هي مجموعة من Chunk
. يمكن أن يتضمّن Corpus
10,000 Document
كحد أقصى.
name
string
غير قابل للتغيير. المعرّف اسم المورد Document
يمكن أن يحتوي المعرّف (الاسم باستثناء البادئة "corpora/*/documents/") على ما يصل إلى 40 حرفًا أبجديًا رقميًا صغيرًا أو شرطات (-). ولا يمكن أن يبدأ المعرّف بشرطة أو ينتهي بها. إذا كان الاسم فارغًا عند الإنشاء، سيتم اشتقاق اسم فريد من displayName
مع لاحقة عشوائية مكوّنة من 12 حرفًا. مثلاً: corpora/{corpus_id}/documents/my-awesome-doc-123a456b789c
displayName
string
اختياريّ. الاسم المعروض السهل القراءة لـ Document
. يجب ألا يزيد طول الاسم المعروض عن 512 حرفًا، بما في ذلك المسافات. مثال: "مستندات Semantic Retriever"
customMetadata[]
object (CustomMetadata
)
اختياريّ. البيانات الوصفية المخصّصة التي قدّمها المستخدم والمخزّنة كأزواج المفتاح/القيمة تُستخدَم لطلب البحث ويمكن أن تتضمّن Document
20 CustomMetadata
بحدٍ أقصى.
updateTime
string (Timestamp
format)
النتائج فقط. الطابع الزمني لآخر تعديل لـ "Document
"
طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z"
و"2014-10-02T15:01:23.045123456Z"
createTime
string (Timestamp
format)
النتائج فقط. الطابع الزمني لوقت إنشاء Document
طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z"
و"2014-10-02T15:01:23.045123456Z"
تمثيل JSON |
---|
{
"name": string,
"displayName": string,
"customMetadata": [
{
object ( |
CustomMetadata
البيانات الوصفية المقدَّمة من المستخدِم والمخزَّنة في صورة أزواج مفتاح/قيمة
key
string
مطلوب. مفتاح بيانات التعريف المطلوب تخزينها.
حقل الربط value
يمكن أن يكون value
واحدًا فقط مما يلي:
stringValue
string
قيمة السلسلة للبيانات الوصفية المطلوب تخزينها
stringListValue
object (StringList
)
قيمة StringList للبيانات الوصفية المطلوب تخزينها.
numericValue
number
القيمة الرقمية لبيانات التعريف المطلوب تخزينها.
تمثيل JSON |
---|
{ "key": string, // Union field |
StringList
قيم سلاسل مقدَّمة من المستخدِم تمّ إسنادها إلى مفتاح بيانات وصفية واحد.
values[]
string
قيم السلسلة للبيانات الوصفية المطلوب تخزينها.
تمثيل JSON |
---|
{ "values": [ string ] } |