الطريقة: corpora.documents.create
لإنشاء Document
فارغ
نقطة نهاية
posthttps: / /generativelanguage.googleapis.com /v1beta /{parent=corpora /*} /documents
يستخدِم عنوان URL بنية تحويل ترميز gRPC.
مَعلمات المسار
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 حرفًا، بما في ذلك المسافات. مثال: "مستندات أداة البحث الدلالي"
customMetadata[]
object (CustomMetadata
)
اختياريّ. بيانات وصفية مخصّصة قدّمها المستخدِم ويتم تخزينها كأزواج مفتاح/قيمة تُستخدَم لإجراء طلبات بحث. يمكن أن يتضمّن Document
20 CustomMetadata
كحدّ أقصى.
نص الاستجابة
إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثيل تم إنشاؤه حديثًا من Document
.
الطريقة: corpora.documents.query
تُجري عملية بحث دلالي على Document
.
نقطة نهاية
posthttps: / /generativelanguage.googleapis.com /v1beta /{name=corpora /* /documents /*}:query
يستخدِم عنوان URL بنية تحويل ترميز gRPC.
مَعلمات المسار
name
string
مطلوب. اسم Document
المطلوب إجراء طلب بحث عنه مثال: corpora/my-corpus-123/documents/the-doc-abc
يكون على الشكل corpora/{corpora}/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
قائمة العناصر: 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
قائمة العناصر: metadataFilters = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2015, operation = GREATER}]}, {key = "chunk.custom_metadata.year" conditions = [{int_value = 2020, operation = LESS_EQUAL}]}]
ملاحظة: لا يمكن استخدام "و" للمفتاح نفسه إلا مع القيم الرقمية. لا تتيح قيم السلاسل استخدام "أو" إلا للمفتاح نفسه.
نص الاستجابة
استجابة من documents.query
تحتوي على قائمة بالمقاطع ذات الصلة
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
relevantChunks[]
object (RelevantChunk
)
الأجزاء ذات الصلة التي تم عرضها
تمثيل JSON |
---|
{
"relevantChunks": [
{
object ( |
الطريقة: corpora.documents.list
يتم إدراج جميع Document
في Corpus
.
نقطة نهاية
الحصول علىhttps: / /generativelanguage.googleapis.com /v1beta /{parent=corpora /*} /documents
يستخدِم عنوان URL بنية تحويل ترميز gRPC.
مَعلمات المسار
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
معيّن
نقطة نهاية
الحصول علىhttps: / /generativelanguage.googleapis.com /v1beta /{name=corpora /* /documents /*}
يستخدِم عنوان URL بنية تحويل ترميز gRPC.
مَعلمات المسار
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/*}
يستخدِم عنوان URL بنية تحويل ترميز gRPC.
مَعلمات المسار
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 /*}
يستخدِم عنوان URL بنية تحويل ترميز gRPC.
مَعلمات المسار
name
string
مطلوب. اسم المورد للDocument
المطلوب حذفه. مثال: corpora/my-corpus-123/documents/the-doc-abc
يكون بالشكل corpora/{corpora}/documents/{document}
.
مَعلمات طلب البحث
force
boolean
اختياريّ. في حال ضبطها على "صحيح"، سيتم أيضًا حذف أي Chunk
وعناصر مرتبطة بهذا Document
.
إذا كانت القيمة خطأ (القيمة التلقائية)، سيتم عرض خطأ FAILED_PRECONDITION
إذا كانت Document
تحتوي على أي Chunk
.
نص الطلب
يجب أن يكون نص الطلب فارغًا.
نص الاستجابة
إذا كانت الاستجابة ناجحة، يكون نص الاستجابة هو عنصر JSON فارغ.
مورد 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 حرفًا، بما في ذلك المسافات. مثال: "مستندات أداة البحث الدلالي"
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"
تمثيل JSON |
---|
{
"name": string,
"displayName": string,
"customMetadata": [
{
object ( |
CustomMetadata
البيانات الوصفية المقدَّمة من المستخدِم والمخزَّنة في صورة أزواج مفتاح/قيمة
key
string
مطلوب. مفتاح البيانات الوصفية المطلوب تخزينها.
value
Union type
value
واحدًا مما يلي فقط:stringValue
string
قيمة السلسلة للبيانات الوصفية المطلوب تخزينها
stringListValue
object (StringList
)
قيمة StringList للبيانات الوصفية المطلوب تخزينها.
numericValue
number
القيمة الرقمية للبيانات الوصفية التي سيتم تخزينها
تمثيل JSON |
---|
{
"key": string,
// value
"stringValue": string,
"stringListValue": {
object ( |
StringList
قيم سلاسل مقدَّمة من المستخدِم تمّ تعيينها لمفتاح بيانات وصفية واحد.
values[]
string
قيم سلاسل البيانات الوصفية المطلوب تخزينها
تمثيل JSON |
---|
{ "values": [ string ] } |