تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

البحث عن المستندات واستردادها

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

في هذا المستند، ستجد أمثلة على المهام التالية:

البحث في مجموعة المستندات
عرض نتائج البحث على صفحات
تطبيق فلاتر معقّدة على بحثك
استرداد محتوى المستند بالكامل
تحسين حمولات الاستجابة لتقليل وقت الاستجابة

قبل البدء، عليك إعداد بيئتك للأداة المفضّلة لديك:

gcloud

ثبِّت واجهة سطر الأوامر (CLI) في gcloud وأعِد ضبطها، وفعِّل Developer Knowledge API.

REST

فعِّل واجهة برمجة التطبيقات وأنشئ مفتاح Developer Knowledge API. بعد ذلك، احفظ مفتاحك في متغيّر بيئة:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

استبدِل YOUR_API_KEY بمفتاح Developer Knowledge API.

البحث عن مستندات

استخدِم gcloud developer-knowledge documents search-chunks الأمر أو documents.searchDocumentChunks طريقة REST للعثور على أجزاء من المستندات تطابق سلسلة طلب بحث. تتضمّن النتائج أجزاء من محتوى المستندات المطابقة، بالإضافة إلى مرجع parent يمكنك استخدامه لاسترداد المحتوى الكامل لهذه المستندات.

يبحث المثال التالي عن مستندات تطابق "BigQuery":

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery"

REST

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&key=$DEVELOPERKNOWLEDGE_API_KEY"

يكون الناتج مشابهًا لما يلي:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "BigQuery overview",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z"
      },
      "relevanceScore": 0.92
    }
  ]
}

تتضمّن كل نتيجة في قائمة results ما يلي:

parent: اسم مورد المستند (على سبيل المثال، documents/docs.cloud.google.com/bigquery/docs/introduction)
id: معرّف الجزء ضمن المستند (على سبيل المثال، chunk_0)
content: المقتطف النصي المطابق من المستند
document: بيانات وصفية حول المستند المصدر، مثل title وuri وdataSource وupdateTime
relevanceScore: درجة الصلة بين الجزء وطلب البحث، في النطاق [0.0, 1.0]

لمزيد من المعلومات حول مخطط الاستجابة وجميع حقول البيانات الوصفية المتاحة، اطّلِع على مرجع واجهة برمجة التطبيقات documents.searchDocumentChunks.

عرض نتائج البحث على صفحات

عندما يعرض طلب البحث عدة نتائج مطابقة، يمكنك التنقّل في مجموعة النتائج باستخدام مَعلمات عرض النتائج على صفحات:

--page-size (واجهة سطر الأوامر (CLI) في gcloud) أو pageSize (عدد صحيح): تحدّد هذه المَعلمة الحد الأقصى لعدد النتائج التي يتم عرضها في كل صفحة. إذا لم يتم تحديدها، تستخدم واجهة برمجة التطبيقات خمس نتائج كحد أقصى. الحد الأقصى للقيمة المسموح بها هو 100، ويتم تحويل القيم الأكبر من 100 إلى 100.
--limit (واجهة سطر الأوامر (CLI) في gcloud) أو pageToken (سلسلة): في واجهة سطر الأوامر (CLI) في gcloud، استخدِم `‎--limit` للتحكّم في إجمالي عدد النتائج المعروضة على الصفحات.--limit في طلبات REST، مرِّر قيمة pageToken التي تم تلقّيها في استجابة سابقة لجلب الصفحة التالية من النتائج.

gcloud

مرِّر علامتَي --page-size و--limit للتحكّم في عدد النتائج لكل صفحة وإجمالي عدد النتائج المعروضة:

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --page-size=5 \
  --limit=10

REST

لطلب الصفحة الأولى، مرِّر المَعلمة pageSize في طلبك:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&key=$DEVELOPERKNOWLEDGE_API_KEY"

إذا كانت هناك نتائج إضافية متاحة، ستتضمّن الاستجابة nextPageToken:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "What is BigQuery?",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z",
        "view": "DOCUMENT_VIEW_BASIC"
      },
      "relevanceScore": 0.88
    }
  ],
  "nextPageToken": "CAUQABgB"
}

لاسترداد الصفحات اللاحقة، مرِّر قيمة nextPageToken إلى المَعلمة pageToken في طلبك التالي:
```
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"
```
عند الوصول إلى آخر صفحة من النتائج، يتم حذف nextPageToken من الاستجابة.

فلترة نتائج البحث

استخدِم العلامة --query-filter في واجهة سطر الأوامر (CLI) في gcloud أو المَعلمة filter في طلبات REST لتطبيق فلتر صارم على نتائج البحث. يتم تطبيق تعبير الفلتر على البيانات الوصفية للمستند الرئيسي لكل جزء.

يبلغ عدد الأحرف المسموح به لتعبير الفلتر 500 حرف.

الحقول المسموح بها

يمكنك فلترة نتائج البحث باستخدام حقول المستند الرئيسي التالية:

content_length_bytes (عدد صحيح): طول حقل content في المستند بالبايت
data_source (سلسلة): نطاق مصدر المستند، مثل docs.cloud.google.com أو firebase.google.com اطّلِع على مرجع مجموعة المستندات للاطّلاع على جميع مصادر البيانات المسموح بها.
update_time (طابع زمني): الطابع الزمني لآخر مرة تم فيها تعديل المستند يجب أن تستخدم القيم تنسيق RFC 3339 (على سبيل المثال، "2025-01-01T00:00:00Z").
uri (سلسلة): معرّف الموارد المنتظم (URI) الكامل للمستند (على سبيل المثال، https://docs.cloud.google.com/bigquery/docs/tables)

عوامل التشغيل المسموح بها

يتيح محلّل تعبيرات الفلتر عوامل تشغيل مختلفة استنادًا إلى نوع بيانات الحقل:

حقول السلسلة (data_source، uri): تتيح عوامل التشغيل = (يساوي) و!= (لا يساوي) للمطابقة التامة للسلسلة. لا تتوافق المطابقات الجزئية والمطابقات التي تبدأ ببادئة والمطابقات التي تستخدم تعبيرات عادية.
حقول الطابع الزمني (update_time): تتيح عوامل التشغيل = و< و<= و> و>=.
حقول العدد الصحيح (content_length_bytes): تتيح عوامل التشغيل = و!= و< و<= و > و>=.
عوامل التشغيل المنطقية: ادمِج الشروط باستخدام AND وOR وNOT (أو -).

أمثلة الفلاتر

توضّح الأمثلة التالية كيفية إنشاء تعبيرات الفلتر. عند استخدام واجهة سطر الأوامر (CLI) في gcloud، مرِّر التعبير إلى العلامة --query-filter. عند استدعاء REST API باستخدام curl، تأكَّد من ترميز المَعلمة filter باستخدام عناوين URL أو استخدِم --data-urlencode.

مطابقة مصدر بيانات واحد

لحصر نتائج البحث على نطاق مستندات واحد:

data_source = "docs.cloud.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Functions deployment" \
  --query-filter='data_source = "docs.cloud.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Functions deployment" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

مطابقة مصادر بيانات متعددة

استخدِم OR لتضمين مستندات من مصادر متعددة:

data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="database" \
  --query-filter='data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=database" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

الفلترة حسب الطابع الزمني

استخدِم عوامل تشغيل المقارنة مع الطوابع الزمنية بتنسيق RFC 3339 للعثور على المحتوى الذي تم تعديله بعد تاريخ معيّن:

update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --query-filter='update_time >= "2025-01-01T00:00:00Z"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=BigQuery" \
  --data-urlencode 'filter=update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

الفلترة حسب طول المحتوى

استخدِم عوامل تشغيل المقارنة مع content_length_bytes للعثور على المستندات استنادًا إلى حجمها بالبايت:

content_length_bytes < 5000

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Storage" \
  --query-filter='content_length_bytes < 5000'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Storage" \
  --data-urlencode 'filter=content_length_bytes < 5000' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

الجمع بين مصدر البيانات والطابع الزمني والتجميع

اجمع بين AND وOR والأقواس (...) لحصر النتائج على مصادر معيّنة تم تعديلها بعد تاريخ معيّن:

(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="service worker" \
  --query-filter='(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=service worker" \
  --data-urlencode 'filter=(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

استبعاد مصادر البيانات

استخدِم NOT أو != لاستبعاد النتائج من مصدر معيّن:

data_source != "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="authentication" \
  --query-filter='data_source != "firebase.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=authentication" \
  --data-urlencode 'filter=data_source != "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

استرداد مستند

استخدِم gcloud developer-knowledge documents describeالأمر أو طريقة REST‏ documents.get لاسترداد المحتوى الكامل لمستند واحد.

يسترد المثال التالي مستندًا حسب اسم المورد:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"

الاستجابة هي مورد Document يحتوي على بيانات وصفية ومحتوى Markdown الكامل في حقل content.

أسماء الموارد مقابل معرّفات الموارد المنتظمة (URI)

عند الإشارة إلى المستندات في Developer Knowledge API، لاحظ الفرق بين أسماء الموارد ومعرّفات الموارد المنتظمة (URI) على الويب:

اسم المورد (parent وname): يتم تنسيقه على النحو documents/{uri_without_scheme} (على سبيل المثال، documents/docs.cloud.google.com/storage/docs/creating-buckets). مرِّر هذه القيمة كحجة موضعية في gcloud developer-knowledge documents describe أو مَعلمة المسار في GetDocument أو في المَعلمة names في BatchGetDocuments.
معرّف الموارد المنتظم (URI) على الويب (uri): عنوان URL كامل على الويب يتضمّن المخطط (على سبيل المثال، https://docs.cloud.google.com/storage/docs/creating-buckets). استخدِم هذا التنسيق لحقل uri عند إنشاء --query-filter أو filter تعبيرات (على سبيل المثال، uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

استرداد مستندات متعددة باستخدام `BatchGetDocuments`

استخدِم طريقة documents.batchGet لاسترداد ما يصل إلى 20 مستندًا بالاسم في طلب بيانات من واجهة برمجة التطبيقات واحد. هذه الطريقة أكثر فعالية من إجراء طلبات GetDocument متعددة.

يسترد المثال التالي مستندَين بالاسم:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&key=$DEVELOPERKNOWLEDGE_API_KEY"

تحتوي الاستجابة على قائمة بالموارد المطلوبة Document بالترتيب الذي طلبته.

تحسين حمولات الاستجابة

يمكن أن يكون محتوى المستند بتنسيق Markdown كبيرًا. إذا كان تطبيقك يحتاج فقط إلى البيانات الوصفية (مثل عناوين الصفحات أو معرّفات الموارد المنتظمة (URI) أو الطوابع الزمنية) أو حقول معيّنة، يمكنك تحسين أحجام الحمولة لتقليل النطاق الترددي ووقت الاستجابة.

استخدام طرق عرض المستندات

تتحكّم العلامة --view في واجهة سطر الأوامر (CLI) في gcloud أو المَعلمة view في طلبات REST في الحقول التي تتم تعبئتها في Document رسائل.

تتيح العلامة --view وتعداد DocumentView القيم التالية:

--view=basic (واجهة سطر الأوامر (CLI) في gcloud) أو DOCUMENT_VIEW_BASIC: لا تعرض هذه القيمة سوى حقول البيانات الوصفية الأساسية (name وuri وdataSource وtitle و description وupdateTime وview). يتم حذف حقل content.
--view=content (واجهة سطر الأوامر (CLI) في gcloud) أو DOCUMENT_VIEW_CONTENT: تعرض هذه القيمة حقول البيانات الوصفية بالإضافة إلى حقل content بتنسيق Markdown. هذه هي القيمة التلقائية لـ gcloud developer-knowledge documents describe وGetDocument وBatchGetDocuments.
--view=full (واجهة سطر الأوامر (CLI) في gcloud) أو DOCUMENT_VIEW_FULL: تعرض هذه القيمة جميع حقول المستند.

لاسترداد البيانات الوصفية للمستند فقط بدون تنزيل محتوى Markdown كبير، حدِّد طريقة عرض المستند الأساسية:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets \
  --view=basic

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

يمكنك أيضًا استخدام view=DOCUMENT_VIEW_BASIC مع BatchGetDocuments:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

استخدام أقنعة الحقول

لتقليل حمولات الاستجابة بشكل أكبر إلى حقول معيّنة، استخدِم مَعلمة طلب البحث fields query parameter (قناع الحقل) في واجهات برمجة تطبيقات Google العادية.

فلترة الحقول في `GetDocument`

لاسترداد حقول title وuri وupdateTime فقط في مستند:

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?fields=title,uri,updateTime&key=$DEVELOPERKNOWLEDGE_API_KEY"

فلترة الحقول في `BatchGetDocuments`

لاسترداد حقول معيّنة فقط لكل مستند في مجموعة:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&fields=documents(name,title,uri)&key=$DEVELOPERKNOWLEDGE_API_KEY"

فلترة الحقول في `SearchDocumentChunks`

لعرض id وcontent فقط للجزء، وtitle وuri للمستند الرئيسي، وnextPageToken من عملية بحث:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&fields=results(id,content,document(title,uri)),nextPageToken&key=$DEVELOPERKNOWLEDGE_API_KEY"

التعامل مع الأخطاء

تعرض Developer Knowledge API رموز حالة HTTP العادية. توضّح الأمثلة الوظيفية التالية رموز حالة HTTP وأسبابها في Developer Knowledge API:

400 INVALID_ARGUMENT:
- تتجاوز سلسلة تعبير filter 500 حرف.
- الطابع الزمني update_time غير صالح (يجب استخدام تنسيق RFC 3339).
- تم تقديم أكثر من 20 اسم مستند في طلب BatchGetDocuments.
401 UNAUTHENTICATED: يفتقر الطلب إلى مفتاح واجهة برمجة التطبيقات أو رمز مميّز من نوع Bearer، أو يستخدم بيانات اعتماد غير صالحة. اطّلِع على المصادقة.
404 NOT_FOUND: اسم المستند المطلوب غير موجود أو ينتمي إلى نطاق غير مضمّن في مجموعة المستندات.
429 RESOURCE_EXHAUSTED: تجاوز المشروع الحصة المخصّصة له. اطّلِع على الحصة والحدود.

الخطوات التالية

اطّلِع على مقالة إنشاء إجابات من المستندات.
اتصل بخادم Developer Knowledge MCP وثبّت retrieving-developer-knowledge مهارة الوكيل لمساعدة مساعدك في كتابة التعليمات البرمجية بالذكاء الاصطناعي في البحث عن المستندات الرسمية وقراءتها.
تعرَّف على كيفية استخدام مكتبات العملاء في Python، Node.js أو Go أو Java.
تعرَّف على كيفية استخدام واجهة سطر الأوامر (CLI) في gcloud.
تصفَّح مرجع مجموعة المستندات للاطّلاع على جميع مصادر المستندات المسموح بها.
راجِع مرجع REST API للاطّلاع على المواصفات الكاملة للطريقة.
تحقَّق من الحصة والحدود للاطّلاع على الحصص والحدود القصوى لعدد الطلبات في واجهة برمجة التطبيقات.

البحث عن المستندات واستردادها تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

gcloud

REST

البحث عن مستندات

gcloud

REST

عرض نتائج البحث على صفحات

gcloud

REST

فلترة نتائج البحث

الحقول المسموح بها

عوامل التشغيل المسموح بها

أمثلة الفلاتر

مطابقة مصدر بيانات واحد

gcloud

REST

مطابقة مصادر بيانات متعددة

gcloud

REST

الفلترة حسب الطابع الزمني

gcloud

REST

الفلترة حسب طول المحتوى

gcloud

REST

الجمع بين مصدر البيانات والطابع الزمني والتجميع

gcloud

REST

استبعاد مصادر البيانات

gcloud

REST

استرداد مستند

gcloud

REST

أسماء الموارد مقابل معرّفات الموارد المنتظمة (URI)

استرداد مستندات متعددة باستخدام BatchGetDocuments

تحسين حمولات الاستجابة

استخدام طرق عرض المستندات

gcloud

REST

استخدام أقنعة الحقول

فلترة الحقول في GetDocument

فلترة الحقول في BatchGetDocuments

فلترة الحقول في SearchDocumentChunks

التعامل مع الأخطاء

الخطوات التالية

البحث عن المستندات واستردادها

استرداد مستندات متعددة باستخدام `BatchGetDocuments`

فلترة الحقول في `GetDocument`

فلترة الحقول في `BatchGetDocuments`

فلترة الحقول في `SearchDocumentChunks`