‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

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

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

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

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

قبل‌از شروع، محیط را برای ابزار ترجیحی‌تان راه‌اندازی کنید:

gcloud

«میانای خط فرمان gcloud» را نصب و پیکربندی کنید و «میانای برنامه‌سازی کاربردی دانش توسعه‌دهندگان» را فعال کنید.

استراحت

«میانای برنامه‌سازی کاربردی» را فعال کنید و کلید «میانای برنامه‌سازی کاربردی دانش توسعه‌دهنده» را تولید کنید. سپس، کلیدتان را در متغیر محیطی ذخیره کنید:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

‫YOUR_API_KEY را با کلید «میانای برنامه‌سازی کاربردی دانش توسعه‌دهنده» خود جایگزین کنید.

جستجوی اسناد

از 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].

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

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

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

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

استراحت

برای درخواست صفحه اول، پارامتر 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 استفاده کنید تا فیلتر سخت‌گیرانه‌ای بر نتایج جستجو اعمال شود. عبارت فیلتر به فراداده سند اصلی برای هر تکه اعمال می‌شود.

عبارت فیلتر دارای محدودیت ۵۰۰ نویسه است.

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

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

content_length_bytes (عدد صحیح): طول فیلد content سند به بایت.
‫data_source (رشته): دامنه منبع سند، مثل docs.cloud.google.com یا firebase.google.com. برای همه منابع داده تحت پشتیبانی، مرجع پیکره را ببینید.
‫update_time (مُهر زمان): مُهر زمان آخرین به‌روزرسانی سند. مقادیر باید از قالب 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 (یا -) شرایط را ترکیب کنید.

نمونه‌های فیلتر

مثال‌های زیر نحوه ساختن عبارت‌های فیلتر را نشان می‌دهد. هنگام استفاده از 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"'

استراحت

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"'

استراحت

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'

استراحت

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"'

استراحت

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

استراحت

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): نشانی وب کامل شامل طرح (برای مثال، 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 برای بازیابی حداکثر ۲۰ سند براساس نام در یک فراخوانی میانای برنامه‌سازی کاربردی استفاده کنید. این روش کارآمدتر از ارسال چندین درخواست 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 CLI یا پارامتر view در درخواست‌های REST کنترل می‌کند که کدام فیلدها در پیام‌های Document پر شوند.

پرچم --view و DocumentView enum از مقادیر زیر پشتیبانی می‌کنند:

--view=basic (gcloud CLI) یا DOCUMENT_VIEW_BASIC: فقط فیلدهای فراداده پایه (name، uri، dataSource، title، description، updateTime، و view) را برمی‌گرداند. فیلد content حذف می‌شود.
--view=content (gcloud CLI) یا DOCUMENT_VIEW_CONTENT: فیلدهای فراداده را همراه با فیلد Markdown content برمی‌گرداند. این تنظیم پیش‌فرض برای 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

استراحت

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"

استفاده از پوشش فیلد

برای محدود کردن بیشتر بار پاسخ به فیلدهای خاص، از پارامتر پُرسمان استاندارد Google APIs fields (پوشش فیلد) استفاده کنید.

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

قدم بعدی چیست

به تولید پاسخ از مستندات مراجعه کنید.
به سرور MCP «دانش توسعه‌دهنده» متصل شوید و مهارت عامل retrieving-developer-knowledge را نصب کنید تا به دستیار کدنویسی هوش مصنوعی‌تان کمک کنید مستندات رسمی را جستجو کند و بخواند.
با نحوه استفاده از کتابخانه‌های کارخواه در Python،‏ Node.js،‏ Go، یا Java آشنا شوید.
ببینید چگونه از gcloud CLI استفاده کنید.
برای مشاهده همه منابع اسناد پشتیبانی‌شده، مرجع مجموعه را مرور کنید.
برای مشخصات کامل روش، مرجع REST API را مرور کنید.
سهمیه و محدودیت‌ها را برای محدودیت‌های نرخ و سهمیه‌های API بررسی کنید.

جستجو و بازیابی اسناد با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

gcloud

استراحت

جستجوی اسناد

gcloud

REST

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

gcloud

استراحت

فیلتر کردن نتایج جستجو

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

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

نمونه‌های فیلتر

مطابقت دادن یک منبع داده

gcloud

استراحت

مطابقت دادن چندین منبع داده

gcloud

استراحت

فیلتر کردن براساس مُهر زمان

gcloud

REST

فیلتر کردن براساس طول محتوا

gcloud

استراحت

ترکیب منبع داده، مُهر زمان، و گروه‌بندی

gcloud

REST

مستثنی کردن منابع داده

gcloud

استراحت

بازیابی سند

gcloud

استراحت

نام‌های منبع درمقابل URIها

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

بهینه‌سازی بار داده‌های پاسخ

استفاده از نماهای سند

gcloud

استراحت

استفاده از پوشش فیلد

فیلتر کردن فیلدها در GetDocument

فیلتر کردن فیلدها در BatchGetDocuments

فیلتر کردن فیلدها در SearchDocumentChunks

مدیریت خطاها

قدم بعدی چیست

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

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

فیلتر کردن فیلدها در `GetDocument`

فیلتر کردن فیلدها در `BatchGetDocuments`

فیلتر کردن فیلدها در `SearchDocumentChunks`