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

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

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

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

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

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

gcloud

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

REST

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

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

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

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

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

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

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 را کدبندی نشانی وب کنید یا از --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 است.

نام‌های منبع دربرابر نشانی‌های وب

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

نام منبع (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). هنگام ساختن عبارت‌های --query-filter یا filter (برای مثال، uri = "https://docs.cloud.google.com/storage/docs/creating-buckets")، از این قالب برای فیلد uri استفاده کنید.

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

از روش documents.batchGet برای بازیابی حداکثر ۲۰ سند براساس نام در یک تماس 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 می‌تواند بزرگ باشد. اگر برنامه شما فقط به فراداده (مثل عنوان‌های صفحه، شناسه منابع یکنواخت، یا مُهر زمان) یا فیلدهای خاص نیاز دارد، می‌توانید اندازه‌های بار مفید را بهینه‌سازی کنید تا پهنای باند و تأخیر را کاهش دهید.

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

پرچم --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: فیلدهای فراداده را همراه با فیلد 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"

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

برای محدود کردن بیشتر بار پاسخ به فیلدهای خاص، از پارامتر پُرسمان استاندارد 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 و دلایل آن‌ها را در «میانای برنامه‌سازی کاربردی دانش توسعه‌دهنده» نگاشت می‌کنند:

400 INVALID_ARGUMENT:
- رشته عبارت filter از ۵۰۰ نویسه فراتر رفته است.
- مُهر زمان update_time نامعتبر است (باید از قالب RFC 3339 استفاده کنید).
- بیش‌از ۲۰ نام سند در یک درخواست BatchGetDocuments ارائه شده است.
401 UNAUTHENTICATED: درخواست کلید میانای API ندارد یا از کلید نامعتبر استفاده می‌کند. اصالت‌سنجی را ببینید.
404 NOT_FOUND: نام سند درخواستی وجود ندارد یا متعلق به دامنه‌ای است که در مجموعه پیکره‌ای وجود ندارد.
429 RESOURCE_EXHAUSTED: پروژه از سهمیه خود فراتر رفته است. سهمیه و محدودیت‌ها را ببینید.

قدم بعدی چیست

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

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

gcloud

REST

جستجوی اسناد

gcloud

REST

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

gcloud

REST

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

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

شرکت‌های مخابراتی پشتیبانی‌شده

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

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

gcloud

REST

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

gcloud

REST

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

gcloud

REST

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

gcloud

REST

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

gcloud

REST

کنار گذاشتن منابع داده

gcloud

REST

بازیابی سند

gcloud

REST

نام‌های منبع دربرابر نشانی‌های وب

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

بهینه‌سازی کردن محموله‌های پاسخ

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

gcloud

REST

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

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

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

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

مدیریت خطاها

قدم بعدی چیست

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

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

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

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

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