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

يقدّم هذا الدليل أمثلة على كيفية استخدام وظائف Developer Knowledge API: البحث عن المستندات واسترداد مستند واحد واسترداد مستندات متعددة في دفعة واحدة.

قبل البدء، تأكَّد من تفعيل واجهة برمجة التطبيقات وإنشاء مفتاح 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"

يمكنك تحسين نتائج البحث باستخدام مَعلمات مثل pageSize للحدّ من عدد النتائج لكل صفحة وpageToken لاسترداد الصفحات اللاحقة.

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

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

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

  • data_source (STRING): مصدر المستند، مثلاً docs.cloud.google.com
  • update_time (TIMESTAMP): الطابع الزمني لآخر مرة تم فيها تعديل المستند
  • uri (STRING): معرّف URI للمستند، مثلاً https://docs.cloud.google.com/bigquery/docs/tables

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

  • تتضمّن حقول `STRING` عوامل التشغيل = (يساوي) و!= (لا يساوي) للمطابقات التامة على السلسلة بأكملها.
  • تتضمّن حقول `TIMESTAMP` عوامل التشغيل = و< و<= و> و>=. يجب أن تكون الطوابع الزمنية بتنسيق RFC-3339 (مثلاً "2025-01-01T00:00:00Z").

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

يبحث المثال التالي عن المستندات التي تطابق "BigQuery" ويحصر النتائج في تلك الواردة من docs.cloud.google.com:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&filter=data_source%3D%22docs.cloud.google.com%22&key=$DEVELOPERKNOWLEDGE_API_KEY"

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

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

يسترد المثال التالي مستندًا باسم documents/DOCUMENT_ID:

curl "https://developerknowledge.googleapis.com/v1/documents:get?name=documents/DOCUMENT_ID&key=$DEVELOPERKNOWLEDGE_API_KEY"

الردّ هو المورد الكامل Document ، بما في ذلك الحقل content.

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

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

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

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/DOCUMENT_ID_1&names=documents/DOCUMENT_ID_2&key=$DEVELOPERKNOWLEDGE_API_KEY"

يحتوي الردّ على قائمة بالموارد المطلوبة Document.