Package google.developers.knowledge.v1

فهرست

دانش توسعه‌دهنده

رابط برنامه‌نویسی کاربردی (API) دانش توسعه‌دهندگان، دسترسی برنامه‌نویسی‌شده به اسناد عمومی توسعه‌دهندگان گوگل را فراهم می‌کند و شما را قادر می‌سازد تا این پایگاه دانش را در برنامه‌ها و گردش‌های کاری خود ادغام کنید.

این API به گونه‌ای طراحی شده است که منبع اصلی برای دسترسی قابل خواندن توسط ماشین به اسناد توسعه‌دهندگان گوگل باشد.

یک مورد استفاده معمول این است که ابتدا از DeveloperKnowledge.SearchDocumentChunks برای یافتن URI های صفحه مربوطه بر اساس یک پرس و جو استفاده کنید و سپس از DeveloperKnowledge.GetDocument یا DeveloperKnowledge.BatchGetDocuments برای دریافت محتوای کامل نتایج برتر استفاده کنید.

تمام محتوای سند در قالب Markdown ارائه شده است.

مستندات دسته‌ای

rpc BatchGetDocuments( BatchGetDocumentsRequest ) returns ( BatchGetDocumentsResponse )

چندین سند را بازیابی می‌کند، که هر کدام محتوای کامل Markdown خود را دارند.

دامنه‌های مجوز

به یکی از حوزه‌های OAuth زیر نیاز دارد:

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

برای اطلاعات بیشتر، بهOAuth 2.0 Overview .

دریافت سند

rpc GetDocument( GetDocumentRequest ) returns ( Document )

یک سند واحد را با محتوای کامل Markdown آن بازیابی می‌کند.

دامنه‌های مجوز

به یکی از حوزه‌های OAuth زیر نیاز دارد:

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

برای اطلاعات بیشتر، بهOAuth 2.0 Overview .

جستجوی قطعات سند

rpc SearchDocumentChunks( SearchDocumentChunksRequest ) returns ( SearchDocumentChunksResponse )

جستجوی دانش توسعه‌دهنده در اسناد توسعه‌دهندگان گوگل. بر اساس جستجوی کاربر، DocumentChunk ها را برمی‌گرداند. ممکن است تکه‌های زیادی از یک Document وجود داشته باشد. برای بازیابی اسناد کامل، DeveloperKnowledge.GetDocument یا DeveloperKnowledge.BatchGetDocuments با DocumentChunk.parent در SearchDocumentChunksResponse.results برگردانده شده است، استفاده کنید.

دامنه‌های مجوز

به یکی از حوزه‌های OAuth زیر نیاز دارد:

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

برای اطلاعات بیشتر، بهOAuth 2.0 Overview .

درخواست اسناد دسته‌ای

درخواست پیام برای DeveloperKnowledge.BatchGetDocuments .

فیلدها
names[]

string

الزامی. نام اسنادی که باید بازیابی شوند را مشخص می‌کند. حداکثر ۲۰ سند را می‌توان به صورت دسته‌ای بازیابی کرد. اسناد به همان ترتیبی که names در درخواست آمده‌اند، بازگردانده می‌شوند.

قالب: documents/{uri_without_scheme} مثال: documents/docs.cloud.google.com/storage/docs/creating-buckets

view

DocumentView

اختیاری. DocumentView سند را مشخص می‌کند. اگر مشخص نشود، DeveloperKnowledge.BatchGetDocuments به طور پیش‌فرض روی DOCUMENT_VIEW_CONTENT تنظیم می‌شود.

پاسخ BatchGetDocuments

پیام پاسخ برای DeveloperKnowledge.BatchGetDocuments .

فیلدها
documents[]

Document

حاوی مدارک درخواستی.

سند

یک سند، بخشی از محتوا را از مجموعه دانش توسعه‌دهندگان نشان می‌دهد.

فیلدها
name

string

شناسه. شامل نام منبع سند است. قالب: documents/{uri_without_scheme} مثال: documents/docs.cloud.google.com/storage/docs/creating-buckets

uri

string

فقط خروجی. آدرس اینترنتی (URI) محتوا، مانند docs.cloud.google.com/storage/docs/creating-buckets را ارائه می‌دهد.

content

string

فقط خروجی. شامل محتوای کامل سند در قالب Markdown است.

description

string

فقط خروجی. توضیحی از سند ارائه می‌دهد.

data_source

string

فقط خروجی. منبع داده سند را مشخص می‌کند. مثال منبع داده: firebase.google.com

title

string

فقط خروجی. عنوان سند را ارائه می‌دهد.

update_time

Timestamp

فقط خروجی. نشان‌دهنده‌ی آخرین به‌روزرسانی محتوا یا فراداده‌ی سند است.

view

DocumentView

فقط خروجی. نمای سند DocumentView را مشخص می‌کند.

سندچانک

یک DocumentChunk نشان‌دهنده‌ی بخشی از محتوا از یک Document در مجموعه‌ی DeveloperKnowledge است. برای دریافت کل محتوای سند، parent به DeveloperKnowledge.GetDocument یا DeveloperKnowledge.BatchGetDocuments ارسال کنید.

فیلدها
parent

string

فقط خروجی. شامل نام منبع سندی است که این قطعه از آن است. قالب: documents/{uri_without_scheme} مثال: documents/docs.cloud.google.com/storage/docs/creating-buckets

id

string

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

content

string

فقط خروجی. شامل محتوای بخش سند است.

document

Document

فقط خروجی. نشان‌دهنده‌ی فراداده‌های مربوط به Document است که این بخش از آن است. پیام DocumentView این Document روی DOCUMENT_VIEW_BASIC تنظیم خواهد شد. این پیام برای راحتی در اینجا گنجانده شده است تا کلاینت‌ها در صورتی که فقط به فیلدهای فراداده نیاز دارند، نیازی به فراخوانی DeveloperKnowledge.GetDocument یا DeveloperKnowledge.BatchGetDocuments نداشته باشند. در غیر این صورت، کلاینت‌ها باید DeveloperKnowledge.GetDocument یا DeveloperKnowledge.BatchGetDocuments برای دریافت محتوای کامل سند استفاده کنند.

نمای سند

مشخص می‌کند که کدام فیلدهای Document شامل می‌شوند.

انوم‌ها
DOCUMENT_VIEW_UNSPECIFIED مقدار پیش‌فرض / تنظیم نشده. در صورت مشخص نشدن DocumentView برای اطلاع از مقدار پیش‌فرض هر متد API به آن مراجعه کنید.
DOCUMENT_VIEW_BASIC

فقط شامل فیلدهای فراداده اولیه است: - name - uri - data_source - title - description - update_time - view

این نمای پیش‌فرض برای DeveloperKnowledge.SearchDocumentChunks است.

DOCUMENT_VIEW_FULL شامل تمام فیلدهای Document می‌شود.
DOCUMENT_VIEW_CONTENT

شامل فیلدهای DOCUMENT_VIEW_BASIC و فیلد content می‌شود.

این نمای پیش‌فرض برای DeveloperKnowledge.GetDocument و DeveloperKnowledge.BatchGetDocuments است.

درخواست دریافت سند

درخواست پیام برای DeveloperKnowledge.GetDocument .

فیلدها
name

string

الزامی. نام سندی را که باید بازیابی شود مشخص می‌کند. قالب: documents/{uri_without_scheme} مثال: documents/docs.cloud.google.com/storage/docs/creating-buckets

view

DocumentView

اختیاری. نمای سند DocumentView ) را مشخص می‌کند. اگر مشخص نشود، DeveloperKnowledge.GetDocument به طور پیش‌فرض روی DOCUMENT_VIEW_CONTENT تنظیم می‌شود.

درخواست جستجو

درخواست پیام برای DeveloperKnowledge.SearchDocumentChunks .

فیلدها
query

string

الزامی. رشته پرس‌وجوی خام ارائه شده توسط کاربر، مانند «چگونه یک مخزن ذخیره‌سازی ابری ایجاد کنیم؟» را ارائه می‌دهد.

page_size

int32

اختیاری. حداکثر تعداد نتایجی که باید برگردانده شود را مشخص می‌کند. سرویس ممکن است کمتر از این مقدار را برگرداند.

اگر مشخص نشده باشد، حداکثر ۵ نتیجه برگردانده خواهد شد.

حداکثر مقدار ۲۰ است؛ مقادیر بالاتر از ۲۰ منجر به خطای INVALID_ARGUMENT می‌شوند.

page_token

string

اختیاری. شامل یک توکن صفحه است که از فراخوانی قبلی SearchDocumentChunks دریافت شده است. برای بازیابی صفحه بعدی، این را ارائه دهید.

filter

string

اختیاری. یک فیلتر سختگیرانه بر روی نتایج جستجو اعمال می‌کند. این عبارت از زیرمجموعه‌ای از سینتکس شرح داده شده در https://google.aip.dev/160 پشتیبانی می‌کند.

در حالی که SearchDocumentChunks مقدار DocumentChunk برمی‌گرداند، فیلتر روی فیلدهای DocumentChunk.document اعمال می‌شود.

فیلدهای پشتیبانی شده برای فیلتر کردن:

  • data_source (STRING): منبع سند، مثلاً docs.cloud.google.com . برای فهرست کامل منابع داده در مجموعه داده به https://developers.google.com/knowledge/reference/corpus-reference مراجعه کنید.
  • update_time (TIMESTAMP): مهر زمانی آخرین به‌روزرسانی معنادار سند. به‌روزرسانی معنادار، به‌روزرسانی‌ای است که محتوای markdown یا فراداده سند را تغییر می‌دهد.
  • uri (رشته): آدرس اینترنتی سند، مثلاً https://docs.cloud.google.com/bigquery/docs/tables .

فیلدهای STRING از عملگرهای = (برابر) و != (نه برابر) برای تطبیق دقیق در کل رشته پشتیبانی می‌کنند. تطبیق جزئی، تطبیق پیشوندی و تطبیق عبارت منظم پشتیبانی نمی‌شوند.

فیلدهای TIMESTAMP از عملگرهای = ، < ، <= ، > و >= پشتیبانی می‌کنند. مهرهای زمانی باید در قالب RFC-3339 باشند، مثلاً "2025-01-01T00:00:00Z" .

شما می‌توانید عبارات را با استفاده از عملگرهای منطقی AND ، OR و NOT (یا - ) ترکیب کنید. OR اولویت بالاتری نسبت به AND دارد. برای گروه‌بندی اولویت‌دار صریح، از پرانتز استفاده کنید.

مثال‌ها:

  • data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"
  • data_source != "firebase.google.com"
  • update_time < "2024-01-01T00:00:00Z"
  • update_time >= "2025-01-22T00:00:00Z" AND (data_source = "developer.chrome.com" OR data_source = "web.dev")
  • uri = "https://docs.cloud.google.com/release-notes"

رشته filter نباید بیش از ۵۰۰ کاراکتر باشد؛ مقادیر بیش از ۵۰۰ کاراکتر منجر به خطای INVALID_ARGUMENT می‌شوند.

جستجوقطعات سندپاسخ

پیام پاسخ برای DeveloperKnowledge.SearchDocumentChunks .

فیلدها
results[]

DocumentChunk

شامل نتایج جستجو برای عبارت جستجو شده است. هر DocumentChunk در این لیست شامل یک قطعه از محتوای مرتبط با عبارت جستجو است. برای بازیابی محتوای کامل سند، از فیلد DocumentChunk.parent هر نتیجه به همراه DeveloperKnowledge.GetDocument یا DeveloperKnowledge.BatchGetDocuments استفاده کنید.

next_page_token

string

اختیاری. یک توکن ارائه می‌دهد که می‌تواند به عنوان page_token برای بازیابی صفحه بعدی ارسال شود. اگر این فیلد حذف شود، صفحات بعدی وجود نخواهند داشت.