Package google.developers.knowledge.v1alpha

الفهرس

DeveloperKnowledge

توفّر واجهة Developer Knowledge API إمكانية الوصول الآلي إلى مستندات المطوّرين المتاحة للجميع من Google، ما يتيح لك دمج قاعدة المعلومات هذه في تطبيقاتك وسير عملك.

تم تصميم واجهة برمجة التطبيقات لتكون المصدر الأساسي للوصول إلى مستندات المطوّرين من Google بطريقة يمكن معالجتها آليًا.

من حالات الاستخدام الشائعة استخدام DeveloperKnowledge.SearchDocumentChunks أولاً للعثور على أجزاء المستندات ذات الصلة استنادًا إلى طلب بحث، ثم استخدام DeveloperKnowledge.GetDocument أو DeveloperKnowledge.BatchGetDocuments مع أسماء مراجع المستندات (مثل DocumentChunk.parent أو documents/{uri_without_scheme}) لجلب المحتوى الكامل لأهم النتائج.

يتم تقديم كل محتوى المستند بتنسيق Markdown.

AnswerQuery

rpc AnswerQuery(AnswerQueryRequest) returns (AnswerQueryResponse)

تُجيب عن طلب بحث باستخدام ميزة "الإنشاء المستند إلى المصادر".

نطاقات الأذونات

يتطلب أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/developerprofiles.readonly
  • https://www.googleapis.com/auth/cloud-platform

لمزيد من المعلومات، يُرجى الاطّلاع على OAuth 2.0 Overview.
BatchGetDocuments

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

يستردّ مستندات متعددة، يتضمّن كل منها محتوى Markdown الكامل.

نطاقات الأذونات

يتطلب أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/developerprofiles.readonly
  • https://www.googleapis.com/auth/cloud-platform

لمزيد من المعلومات، يُرجى الاطّلاع على OAuth 2.0 Overview.
GetDocument

rpc GetDocument(GetDocumentRequest) returns (Document)

يستردّ مستندًا واحدًا مع محتوى Markdown الكامل.

نطاقات الأذونات

يتطلب أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/developerprofiles.readonly
  • https://www.googleapis.com/auth/cloud-platform

لمزيد من المعلومات، يُرجى الاطّلاع على OAuth 2.0 Overview.
SearchDocumentChunks

rpc SearchDocumentChunks(SearchDocumentChunksRequest) returns (SearchDocumentChunksResponse)

يبحث عن معلومات للمطوّرين في مستندات المطوّرين من Google. تعرض هذه الأداة DocumentChunks استنادًا إلى طلب المستخدم. قد تكون هناك أجزاء متعددة من Document نفسه. لاسترداد المستندات الكاملة، استخدِم DeveloperKnowledge.GetDocument أو DeveloperKnowledge.BatchGetDocuments مع DocumentChunk.parent الذي تم عرضه في SearchDocumentChunksResponse.results.

نطاقات الأذونات

يتطلب أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/developerprofiles.readonly
  • https://www.googleapis.com/auth/cloud-platform

لمزيد من المعلومات، يُرجى الاطّلاع على OAuth 2.0 Overview.

الإجابة

إجابة عن طلب بحث

الحقول
answer_text

string

يحتوي على نص الإجابة.
citations[]

AnswerCitation

للعرض فقط. تحتوي على اقتباسات للإجابة.
references[]

AnswerReference

للعرض فقط. تحتوي على مراجع للإجابة.

AnswerCitation

معلومات الاقتباس لشريحة معيّنة

الحقول
start_index

int32

للعرض فقط. يشير إلى بداية الجزء، ويتم قياسه بالبايت (يونيكود UTF-8)، شاملاً. إذا كانت هناك أحرف متعدّدة البايت، مثل الأحرف غير اللاتينية، يكون قياس الفهرس أطول من طول السلسلة.
end_index

int32

للعرض فقط. يشير إلى نهاية الجزء، ويتم قياسه بالبايت (يونيكود UTF-8)، حصريًا. إذا كانت هناك أحرف متعدّدة البايت، مثل الأحرف غير اللاتينية، يكون قياس الفهرس أطول من طول السلسلة.
sources[]

CitationSource

للعرض فقط. يحتوي على مصادر الاقتباسات للفقرة المنسوبة.

AnswerReference

تمثّل مرجعًا لمصدر.

الحقول
حقل الربط content يحتوي على محتوى المرجع. يمكن أن يكون التعليق content إحدى القيم التالية فقط:
document_reference

DocumentReference

للعرض فقط. المستند المرجعي

CitationSource

مصدر الاقتباس

الحقول
reference_index

int32

للعرض فقط. يحتوي على فهرس Answer.AnswerReference في الحقل المتكرّر references.

DocumentReference

تمثّل مرجعًا لمستند.

الحقول
document_chunk

DocumentChunk

للعرض فقط. يحتوي على جزء المستند. لم يتم ضبط حقل "document_chunk.id" وسيكون فارغًا.

AnswerQueryRequest

رسالة طلب لـ "DeveloperKnowledge.AnswerQuery"

الحقول
query

string

الحقل مطلوب. طلب البحث الذي يجب الإجابة عنه
filter

string

اختيارية: يتم تطبيق فلتر صارم على نتائج البحث المستخدَمة لتحديد مصدر الإجابة. يتوافق التعبير مع مجموعة فرعية من البنية الموضّحة على الرابط https://google.aip.dev/160.

الحقول المتوافقة مع الفلترة:

  • ‫content_length_bytes (عدد صحيح): طول الحقل Document.content بالبايت
  • ‫data_source (سلسلة): مصدر المستند، مثل docs.cloud.google.com. يمكنك الاطّلاع على https://developers.google.com/knowledge/reference/corpus-reference للحصول على القائمة الكاملة لمصادر البيانات في المجموعة.
  • ‫update_time (TIMESTAMP): الطابع الزمني لآخر تعديل مهم تم إجراؤه على المستند. التعديل المهم هو الذي يغيّر محتوى Markdown أو البيانات الوصفية للمستند.
  • ‫uri (STRING): معرّف الموارد المنتظم (URI) للمستند، مثل https://docs.cloud.google.com/bigquery/docs/tables

تتيح حقول INTEGER استخدام عوامل التشغيل = و< و<= و> و>=.

تتيح حقول STRING استخدام عاملَي التشغيل = (يساوي) و!= (لا يساوي) من أجل المطابقة التامة في السلسلة بأكملها. لا تتوفّر المطابقة الجزئية ومطابقة البادئة ومطابقة التعبير العادي.

تتيح حقول TIMESTAMP استخدام عوامل التشغيل = و< و<= و> و>=. يجب أن تكون الطوابع الزمنية بتنسيق RFC-3339، مثل "2025-01-01T00:00:00Z".

يمكنك دمج التعبيرات باستخدام عوامل التشغيل المنطقية AND وOR وNOT (أو -). ‫OR له أولوية أعلى من AND. استخدِم الأقواس لتجميع الأسبقية الصريحة.

أمثلة:

  • الفلترة حسب Document.content_length_bytes: content_length_bytes < 50000
  • data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"
  • data_source != "firebase.google.com"
  • update_time < "2024-01-01T00:00:00Z"
  • update_time >= "2025-01-22T00:00:00Z" AND (data_source = "developer.chrome.com" OR data_source = "web.dev")
  • uri = "https://docs.cloud.google.com/release-notes"

يجب ألا تتجاوز سلسلة filter 500 حرف، وستؤدي القيم التي تزيد عن 500 حرف إلى ظهور خطأ INVALID_ARGUMENT.

AnswerQueryResponse

رسالة الردّ على DeveloperKnowledge.AnswerQuery

الحقول
answer

Answer

الإجابة عن طلب البحث

BatchGetDocumentsRequest

رسالة طلب لـ "DeveloperKnowledge.BatchGetDocuments"

الحقول
names[]

string

الحقل مطلوب. يحدّد أسماء المستندات المطلوب استردادها. يمكن استرداد 20 مستندًا كحدّ أقصى في كل دفعة. يتم عرض المستندات بالترتيب نفسه الذي تظهر به names في الطلب.

التنسيق: documents/{uri_without_scheme} مثال: documents/docs.cloud.google.com/storage/docs/creating-buckets

يجب ألا يتجاوز كل اسم 500 حرف، وإلا سيظهر الخطأ INVALID_ARGUMENT.
view

DocumentView

اختيارية: تحدّد DocumentView المستند. في حال عدم تحديد قيمة، يتم ضبط السمة DeveloperKnowledge.BatchGetDocuments تلقائيًا على DOCUMENT_VIEW_CONTENT.

BatchGetDocumentsResponse

رسالة الردّ على DeveloperKnowledge.BatchGetDocuments

الحقول
documents[]

Document

يحتوي على المستندات المطلوبة.

مستند

يمثّل المستند صفحة من المستندات في مجموعة "معلومات المطوّر"، مثل الصفحة على الرابط https://docs.cloud.google.com/storage/docs/creating-buckets.

الحقول
name

string

المعرّف. يحتوي على اسم المورد للمستند. التنسيق: documents/{uri_without_scheme} مثال: documents/docs.cloud.google.com/storage/docs/creating-buckets
uri

string

للعرض فقط. يوفّر معرّف الموارد المنتظم (URI) للمحتوى، مثل https://docs.cloud.google.com/storage/docs/creating-buckets.
content

string

للعرض فقط. يحتوي على المحتوى الكامل للمستند بتنسيق Markdown.
description

string

للعرض فقط. يقدّم وصفًا للمستند.
data_source

string

للعرض فقط. تحدّد مصدر بيانات المستند. مثال على مصدر البيانات: firebase.google.com
title

string

للعرض فقط. يوفّر عنوان المستند.
update_time

Timestamp

للعرض فقط. يمثّل الطابع الزمني لآخر تعديل تم إجراؤه على محتوى المستند أو بياناته الوصفية.
view

DocumentView

للعرض فقط. تحدّد DocumentView المستند.
content_length_bytes

int32

للعرض فقط. طول الحقل content بالبايت

DocumentChunk

يمثّل DocumentChunk جزءًا من المحتوى من Document في مجموعة بيانات DeveloperKnowledge. لجلب محتوى المستند بالكامل، مرِّر parent إلى DeveloperKnowledge.GetDocument أو DeveloperKnowledge.BatchGetDocuments.

الحقول
parent

string

للعرض فقط. يحتوي على اسم المورد للمستند الذي تم الحصول على هذا الجزء منه. التنسيق: documents/{uri_without_scheme} مثال: documents/docs.cloud.google.com/storage/docs/creating-buckets
id

string

للعرض فقط. يحدّد معرّف هذا الجزء ضمن المستند. يكون معرّف الجزء فريدًا داخل المستند، ولكنّه ليس فريدًا على مستوى المستندات بشكل عام. معرّف الجزء غير ثابت وقد يتغيّر بمرور الوقت.
content

string

للعرض فقط. يحتوي على محتوى جزء المستند.
document

Document

للعرض فقط. تمثّل هذه السمة البيانات الوصفية حول Document الذي تم استخراج هذا الجزء منه. سيتم ضبط DocumentView رسالة Document هذه على DOCUMENT_VIEW_BASIC. ويتم تضمينه هنا لتسهيل الأمر على العملاء حتى لا يحتاجوا إلى استدعاء DeveloperKnowledge.GetDocument أو DeveloperKnowledge.BatchGetDocuments إذا كانوا يحتاجون فقط إلى حقول البيانات الوصفية. بخلاف ذلك، على العملاء استخدام DeveloperKnowledge.GetDocument أو DeveloperKnowledge.BatchGetDocuments لجلب محتوى المستند بالكامل.
relevance_score

double

للعرض فقط. تمثّل نتيجة مدى صلة الجزء بطلب البحث. تشير النتيجة الأعلى إلى مدى صلة أكبر بالموضوع. تتراوح النتيجة بين [0.0 و1.0].

DocumentView

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

عمليات التعداد
DOCUMENT_VIEW_UNSPECIFIED القيمة التلقائية / غير المحدّدة اطّلِع على كل طريقة من طرق واجهة برمجة التطبيقات لمعرفة قيمتها التلقائية في حال عدم تحديد DocumentView.
DOCUMENT_VIEW_BASIC

يتضمّن حقول البيانات الوصفية الأساسية فقط:

  • name
  • uri
  • data_source
  • title
  • description
  • update_time
  • view
  • content_length_bytes

هذه هي طريقة العرض التلقائية لـ "DeveloperKnowledge.SearchDocumentChunks".
DOCUMENT_VIEW_FULL تتضمّن جميع حقول "Document".
DOCUMENT_VIEW_CONTENT

يتضمّن حقول DOCUMENT_VIEW_BASIC وحقل content.

هذه هي طريقة العرض التلقائية لـ "DeveloperKnowledge.GetDocument" و"DeveloperKnowledge.BatchGetDocuments".

GetDocumentRequest

رسالة طلب لـ "DeveloperKnowledge.GetDocument"

الحقول
name

string

الحقل مطلوب. يحدّد اسم المستند المطلوب استرداده. التنسيق: documents/{uri_without_scheme} مثال: documents/docs.cloud.google.com/storage/docs/creating-buckets

يجب ألا يتجاوز الاسم 500 حرف، وإلا سيؤدي ذلك إلى ظهور الخطأ INVALID_ARGUMENT.
view

DocumentView

اختيارية: تحدّد DocumentView المستند. في حال عدم تحديد قيمة، يتم ضبط السمة DeveloperKnowledge.GetDocument تلقائيًا على DOCUMENT_VIEW_CONTENT.

SearchDocumentChunksRequest

رسالة طلب لـ "DeveloperKnowledge.SearchDocumentChunks"

الحقول
query

string

الحقل مطلوب. توفّر هذه السمة سلسلة طلب البحث الأوّلية التي قدّمها المستخدم، مثل "كيف يمكن إنشاء حزمة Cloud Storage؟". يجب ألا يتجاوز طلب البحث 500 حرف، وإلا سيؤدي إلى ظهور الخطأ INVALID_ARGUMENT.
page_size

int32

اختيارية: تحدّد هذه المَعلمة أكبر عدد ممكن من النتائج. قد تعرض الخدمة عددًا أقل من هذه القيمة.

إذا لم يتم تحديدها، سيتم عرض 5 نتائج كحد أقصى.

الحد الأقصى للقيمة هو 100، وسيتم فرض القيم التي تزيد عن 100 على 100.
page_token

string

اختيارية: يحتوي على رمز مميّز للصفحة، تم تلقّيه من طلب SearchDocumentChunks سابق. يجب تقديم هذه القيمة لاسترداد الصفحة التالية.
filter

string

اختيارية: يتم تطبيق فلتر صارم على نتائج البحث. يتوافق التعبير مع مجموعة فرعية من البنية الموضّحة على الرابط https://google.aip.dev/160.

بينما تعرض الدالة SearchDocumentChunks قيم DocumentChunk، يتم تطبيق الفلتر على حقول DocumentChunk.document.

الحقول المتوافقة مع الفلترة:

  • ‫content_length_bytes (عدد صحيح): طول الحقل Document.content بالبايت
  • ‫data_source (سلسلة): مصدر المستند، مثل docs.cloud.google.com. يمكنك الاطّلاع على https://developers.google.com/knowledge/reference/corpus-reference للحصول على القائمة الكاملة لمصادر البيانات في المجموعة.
  • ‫update_time (TIMESTAMP): الطابع الزمني لآخر تعديل مهم تم إجراؤه على المستند. التعديل المهم هو الذي يغيّر محتوى Markdown أو البيانات الوصفية للمستند.
  • ‫uri (STRING): معرّف الموارد المنتظم (URI) للمستند، مثل https://docs.cloud.google.com/bigquery/docs/tables

تتيح حقول INTEGER استخدام عوامل التشغيل = و< و<= و> و>=.

تتيح حقول STRING استخدام عاملَي التشغيل = (يساوي) و!= (لا يساوي) من أجل المطابقة التامة في السلسلة بأكملها. لا تتوفّر المطابقة الجزئية ومطابقة البادئة ومطابقة التعبير العادي.

تتيح حقول TIMESTAMP استخدام عوامل التشغيل = و< و<= و> و>=. يجب أن تكون الطوابع الزمنية بتنسيق RFC-3339، مثل "2025-01-01T00:00:00Z".

ملاحظة: يجب أن تكون أسماء الحقول باللغة snake_case (مثل data_source). ويجب أن تكون القيم على الجانب الأيمن من تعبيرات الفلترة سلاسل نصية محاطة بعلامتَي اقتباس مزدوجتَين (مثل "docs.cloud.google.com").

يمكنك دمج التعبيرات باستخدام عوامل التشغيل المنطقية AND وOR وNOT (أو -). ‫OR له أولوية أعلى من AND. استخدِم الأقواس لتجميع الأسبقية الصريحة.

أمثلة:

  • الفلترة حسب Document.content_length_bytes: content_length_bytes < 50000
  • data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"
  • data_source != "firebase.google.com"
  • update_time < "2024-01-01T00:00:00Z"
  • update_time >= "2025-01-22T00:00:00Z" AND (data_source = "developer.chrome.com" OR data_source = "web.dev")
  • uri = "https://docs.cloud.google.com/release-notes"

يجب ألا تتجاوز سلسلة filter 500 حرف، وستؤدي القيم التي تزيد عن 500 حرف إلى ظهور خطأ INVALID_ARGUMENT.

SearchDocumentChunksResponse

رسالة الردّ على DeveloperKnowledge.SearchDocumentChunks

الحقول
results[]

DocumentChunk

يحتوي على نتائج البحث لطلب البحث المحدّد. يحتوي كل DocumentChunk في هذه القائمة على مقتطف من المحتوى ذي الصلة بطلب البحث. استخدِم حقل DocumentChunk.parent لكل نتيجة مع DeveloperKnowledge.GetDocument أو DeveloperKnowledge.BatchGetDocuments لاسترداد محتوى المستند بالكامل.
next_page_token

string

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