جستجو و بازیابی اسناد

این راهنما به شما نشان می‌دهد که چگونه از API دانش توسعه‌دهندگان برای جستجو و بازیابی اسناد عمومی توسعه‌دهندگان گوگل به صورت برنامه‌نویسی استفاده کنید. به جای استخراج دستی صفحات وب، این API به برنامه‌های شما کمک می‌کند تا قطعه کدهای متنی مرتبط را پیدا کنند یا اسناد کامل Markdown را دریافت کنند.

در این سند، نمونه‌هایی برای وظایف زیر خواهید یافت:

  • جستجو در مجموعه اسناد.
  • صفحه بندی نتایج جستجو.
  • اعمال فیلترهای پیچیده در جستجوی شما
  • بازیابی محتوای کامل سند.
  • بهینه‌سازی بارهای پاسخ برای کاهش تأخیر.

قبل از شروع، مطمئن شوید که API را فعال کرده‌اید و یک کلید 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] .

برای اطلاعات بیشتر در مورد طرحواره پاسخ و تمام فیلدهای فراداده موجود، به مرجع API مربوط به documents.searchDocumentChunks مراجعه کنید.

صفحه بندی نتایج جستجو

وقتی یک عبارت جستجو چندین نتیجه‌ی منطبق را برمی‌گرداند، می‌توانید با استفاده از پارامترهای صفحه‌بندی، در مجموعه نتایج پیمایش کنید:

  • pageSize (عدد صحیح): حداکثر تعداد نتایجی که در هر صفحه برگردانده می‌شود را مشخص می‌کند. اگر مشخص نشود، API به طور پیش‌فرض پنج نتیجه را در نظر می‌گیرد. حداکثر مقدار مجاز ۱۰۰ است؛ مقادیر بزرگتر از ۱۰۰ به ۱۰۰ محدود می‌شوند.
  • 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 محدودیت ۵۰۰ کاراکتری دارد.

فیلدهای پشتیبانی شده

شما می‌توانید نتایج جستجوی خود را با استفاده از فیلدهای سند والد زیر فیلتر کنید:

  • content_length_bytes (عدد صحیح): طول فیلد content سند بر حسب بایت.
  • data_source (رشته): دامنه منبع سند، مانند docs.cloud.google.com یا firebase.google.com . برای مشاهده همه منابع داده پشتیبانی شده، به مرجع مجموعه مراجعه کنید.
  • update_time (timestamp): آخرین باری که سند به‌روزرسانی شده است. مقادیر باید از قالب RFC 3339 استفاده کنند (برای مثال، "2025-01-01T00:00:00Z" ).
  • uri (رشته): آدرس کامل سند (برای مثال، https://docs.cloud.google.com/bigquery/docs/tables ).

اپراتورهای پشتیبانی‌شده

تجزیه‌گر عبارت فیلتر، بسته به نوع داده‌ی فیلد، از عملگرهای مختلفی پشتیبانی می‌کند:

  • فیلدهای رشته‌ای ( data_source ، uri ): از = (برابر) و != (نه برابر) برای تطبیق دقیق رشته پشتیبانی می‌کنند. تطبیق‌های جزئی، پیشوندی و عبارات منظم پشتیبانی نمی‌شوند.
  • فیلدهای مهر زمان ( update_time ): = ، < ، <= ، > و >= پشتیبانی می‌کنند.
  • فیلدهای عدد صحیح ( content_length_bytes ): = ، != ، < ، <= ، > و >= پشتیبانی می‌کنند.
  • عملگرهای منطقی : شرط‌ها را با استفاده از AND ، OR و NOT (یا - ) ترکیب می‌کنند.

مثال‌های فیلتر

مثال‌های زیر نحوه ساخت عبارات فیلتر را نشان می‌دهند. هنگام فراخوانی REST API با curl ، مطمئن شوید که پارامتر فیلتر را URL-encode کرده‌اید یا --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ها

هنگام ارجاع به اسناد در رابط برنامه‌نویسی کاربردی دانش توسعه‌دهندگان، به تفاوت بین نام منابع و آدرس‌های وب توجه کنید:

  • نام منبع ( parent ، name ): با فرمت documents/{uri_without_scheme} (برای مثال، documents/docs.cloud.google.com/storage/docs/creating-buckets ). این مقدار را به عنوان پارامتر مسیر در GetDocument یا در پارامتر names از BatchGetDocuments ارسال کنید.
  • آدرس اینترنتی وب ( uri ): آدرس کامل وب شامل طرح (برای مثال، https://docs.cloud.google.com/storage/docs/creating-buckets ). هنگام ساخت عبارات filter ، از این قالب برای فیلد uri استفاده کنید (برای مثال، 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 resource) است که شامل فراداده (metadata) و محتوای کامل Markdown در فیلد content می‌باشد.

بازیابی چندین سند با BatchGetDocuments

از متد documents.batchGet برای بازیابی حداکثر 20 سند بر اساس نام در یک فراخوانی API استفاده کنید. این روش کارآمدتر از ارسال چندین درخواست 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 پر شوند.

Enum 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 استاندارد APIهای گوگل (field mask) استفاده کنید.

فیلتر کردن فیلدها در 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"

برای برگرداندن فقط 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 بیش از ۵۰۰ کاراکتر است.
    • مهر زمانی update_time نامعتبر است (باید از قالب RFC 3339 استفاده شود).
    • بیش از 20 نام سند در درخواست BatchGetDocuments ارائه شده است.
  • 401 UNAUTHENTICATED : درخواست فاقد کلید API است یا از کلید نامعتبر استفاده می‌کند. به بخش احراز هویت مراجعه کنید.
  • 404 NOT_FOUND : نام سند درخواستی وجود ندارد یا متعلق به دامنه‌ای است که در مجموعه مقالات وجود ندارد.
  • 429 RESOURCE_EXHAUSTED : پروژه از سهمیه خود فراتر رفته است. به Quota and limits مراجعه کنید.

قدم بعدی چیست؟