این راهنما نمونههایی از نحوه استفاده از توابع رابط برنامهنویسی کاربردی دانش توسعهدهندگان (Developer Knowledge API) را ارائه میدهد: جستجوی اسناد، بازیابی یک سند واحد و بازیابی چندین سند به صورت دستهای.
قبل از شروع، مطمئن شوید که 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"
شما میتوانید نتایج جستجو را با استفاده از پارامترهایی مانند pageSize برای محدود کردن تعداد نتایج در هر صفحه و pageToken برای بازیابی صفحات بعدی، اصلاح کنید.
فیلتر کردن نتایج جستجو
از پارامتر filter برای اعمال یک فیلتر سختگیرانه بر روی نتایج جستجو استفاده کنید. این فیلتر بر روی متادیتای اسناد مرتبط با بخشهای نتیجه جستجو اعمال میشود.
فیلدهای پشتیبانی شده برای فیلتر کردن:
-
data_source(STRING): منبع سند، برای مثال،docs.cloud.google.com. -
update_time(TIMESTAMP): نشانگر زمانی آخرین بهروزرسانی سند. -
uri(STRING): آدرس اینترنتی سند، مثلاً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 برای بازیابی حداکثر ۱۰۰ سند بر اساس نام در یک فراخوانی API استفاده کنید. این روش کارآمدتر از ارسال چندین درخواست GetDocument است.
مثال زیر دو سند را بر اساس نام بازیابی میکند:
curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/DOCUMENT_ID_1&names=documents/DOCUMENT_ID_2&key=$DEVELOPERKNOWLEDGE_API_KEY"
پاسخ شامل فهرستی از منابع Document درخواستی است.