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

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

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

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

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

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

gcloud

ثبِّت gcloud CLI واضبط إعداداته، وفعِّل 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 (gcloud CLI) أو pageSize (عدد صحيح): يحدّد الحد الأقصى لعدد النتائج التي سيتم عرضها في كل صفحة. في حال عدم تحديد هذا الحقل، ستعرض واجهة برمجة التطبيقات تلقائيًا خمس نتائج. الحدّ الأقصى المسموح به هو 100، ويتم فرض القيمة 100 على القيم الأكبر من 100.
--limit (gcloud CLI) أو pageToken (سلسلة): في gcloud CLI، استخدِم --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 في gcloud CLI أو المَعلمة 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 (أو -).

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

توضّح الأمثلة التالية كيفية إنشاء عبارات الفلتر. عند استخدام gcloud CLI، مرِّر التعبير إلى العلامة --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 أو طريقة documents.get REST لاسترداد المحتوى الكامل لمستند واحد.

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

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): عنوان 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 كبيرًا. إذا كان تطبيقك يحتاج فقط إلى بيانات وصفية (مثل عناوين الصفحات أو معرّفات الموارد المنتظمة أو الطوابع الزمنية) أو حقول معيّنة، يمكنك تحسين أحجام الحمولة لتقليل معدل نقل البيانات ووقت الاستجابة.

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

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

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

‫--view=basic (gcloud CLI) أو DOCUMENT_VIEW_BASIC: تعرضان حقول البيانات الوصفية الأساسية فقط (name وuri وdataSource وtitle وdescription وupdateTime وview)، ويتم حذف الحقل content.
--view=content (gcloud CLI) أو DOCUMENT_VIEW_CONTENT: تعرض حقول البيانات الوصفية مع الحقل content بتنسيق Markdown. هذا هو الإعداد التلقائي لكل من gcloud developer-knowledge documents describe وGetDocument وBatchGetDocuments.
--view=full (gcloud CLI) أو 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 العادية في Google APIs (قناع الحقل).

فلترة الحقول في `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 رموز حالة HTTP العادية. في ما يلي أمثلة عملية توضّح رموز حالة HTTP وأسبابها في Developer Knowledge API:

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

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

يُرجى الرجوع إلى مقالة إنشاء إجابات من المستندات.
اتّصِل بخادم Developer Knowledge MCP وثبِّت مهارة retrieving-developer-knowledge للمساعدة في بحث وقراءة مساعد الترميز المستند إلى الذكاء الاصطناعي للمستندات الرسمية.
يمكنك استكشاف كيفية استخدام مكتبات العملاء في Python أو Node.js أو Go أو Java.
تعرَّف على كيفية استخدام gcloud CLI.
تصفَّح مرجع المجموعة للاطّلاع على جميع مصادر المستندات المتوافقة.
راجِع مرجع 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`