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

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

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

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

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

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

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

البحث عن مستندات باستخدام `SearchDocumentChunks`

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

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

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.

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

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

pageSize (عدد صحيح): يحدّد الحد الأقصى لعدد النتائج التي يتم عرضها في كل صفحة. إذا لم يتم تحديد هذه المَعلمة، تستخدم واجهة برمجة التطبيقات خمس نتائج كقيمة تلقائية. الحد الأقصى المسموح به هو 100، ويتم تحويل القيم الأكبر من 100 إلى 100.
pageToken (سلسلة): يحدّد الرمز المميّز الذي تم تلقّيه في استجابة سابقة لجلب الصفحة التالية من النتائج.

طلب الصفحة الأولى

لضبط حجم الصفحة، مرِّر المَعلمة 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 من الاستجابة.

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

استخدِم المَعلمة filter لتطبيق فلتر صارم على نتائج البحث. يتم تطبيق تعبير الفلتر على البيانات الوصفية للمستند الرئيسي لكل جزء.

يبلغ الحد الأقصى لطول تعبير filter 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 (أو -).

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

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

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

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

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

طلب curl:

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"

طلب curl:

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

طلب curl:

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"

طلب curl:

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"

طلب curl:

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"

استرداد مستند باستخدام `GetDocument`

استخدِم طريقة documents.get لاسترداد المحتوى الكامل لمستند واحد.

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

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

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

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

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

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

استرداد مستندات متعددة باستخدام `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 في الحقول التي تتم تعبئتها في Document رسائل.

يتيح تعداد DocumentView استخدام القيم التالية:

DOCUMENT_VIEW_BASIC: يعرض حقول البيانات الوصفية الأساسية فقط (name وuri وdata_source وtitle وdescription وupdate_time وview). يتم حذف حقل content.
DOCUMENT_VIEW_CONTENT: يعرض حقول البيانات الوصفية بالإضافة إلى حقل content بتنسيق Markdown. هذا هو الإعداد التلقائي لـ GetDocument و BatchGetDocuments.
DOCUMENT_VIEW_FULL: يعرض جميع حقول المستند.

لاسترداد البيانات الوصفية للمستند فقط بدون تنزيل محتوى Markdown كبير، اضبط view=DOCUMENT_VIEW_BASIC:

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

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

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

اطّلِع على مقالة الإجابة عن طلبات البحث باستخدام ميزة "الإنشاء المستنِد إلى مصادر خارجية" .
تعرَّف على كيفية استخدام مكتبات العملاء في Python، Node.js أو Go أو Java.
تصفَّح مرجع مجموعة المستندات لعرض جميع مصادر المستندات المتوافقة.
راجِع المستندات المرجعية لواجهة برمجة تطبيقات REST للاطّلاع على المواصفات الكاملة للطريقة.
اطّلِع على الحصة والحدود لمعرفة الحصص والحدود القصوى لعدد الطلبات في واجهة برمجة التطبيقات.

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

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

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

طلب الصفحة الأولى

استرداد الصفحات اللاحقة

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

الحقول المتاحة

عوامل التشغيل المتوافقة

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

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

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

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

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

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

استرداد مستند باستخدام GetDocument

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

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

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

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

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

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

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

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

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

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

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

البحث عن مستندات باستخدام `SearchDocumentChunks`

استرداد مستند باستخدام `GetDocument`

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

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

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

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