Package google.developers.knowledge.v1alpha

شاخصه

DeveloperKnowledge

‫Developer Knowledge API دسترسی برنامه‌نویسی‌شده به مستندات عمومی توسعه‌دهنده Google را فراهم می‌کند و به شما امکان می‌دهد این پایگاه دانش را در برنامه‌ها و گردش‌های کاری خود ادغام کنید.

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

یک مورد استفاده معمول این است که ابتدا از DeveloperKnowledge.SearchDocumentChunks برای یافتن بخش‌های سند مرتبط براساس پُرسمان استفاده کنید، و سپس از DeveloperKnowledge.GetDocument یا DeveloperKnowledge.BatchGetDocuments با نام‌های منبع سند (مانند DocumentChunk.parent یا documents/{uri_without_scheme}) برای واکشی محتوای کامل نتایج برتر استفاده کنید.

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

AnswerQuery

rpc AnswerQuery(AnswerQueryRequest) returns (AnswerQueryResponse)

بااستفاده از تولید بااستناد به واقعیت به پُرسمان پاسخ می‌دهد.

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

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

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

برای اطلاعات بیشتر، به OAuth 2.0 Overview مراجعه کنید.
BatchGetDocuments

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

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

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

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

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

برای اطلاعات بیشتر، به OAuth 2.0 Overview مراجعه کنید.
GetDocument

rpc GetDocument(GetDocumentRequest) returns (Document)

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

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

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

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

برای اطلاعات بیشتر، به OAuth 2.0 Overview مراجعه کنید.
SearchDocumentChunks

rpc SearchDocumentChunks(SearchDocumentChunksRequest) returns (SearchDocumentChunksResponse)

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

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

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

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

برای اطلاعات بیشتر، به OAuth 2.0 Overview مراجعه کنید.

جواب دادن

پاسخ به پُرسمان.

فیلدها
answer_text

string

حاوی نوشتار پاسخ است.
citations[]

AnswerCitation

فقط خروجی. حاوی استنادهایی برای پاسخ است.
references[]

AnswerReference

فقط خروجی. حاوی مراجعی برای پاسخ است.

AnswerCitation

اطلاعات استناد برای یک بخش.

فیلدها
start_index

int32

فقط خروجی. نشان‌دهنده شروع بخش، اندازه‌گیری‌شده برحسب بایت (یونیکد UTF-8)، شامل. اگر نویسه‌های چندبایتی وجود داشته باشد، مثل نویسه‌های غیرASCII، اندازه‌گیری نمایه طولانی‌تر از طول رشته است.
end_index

int32

فقط خروجی. نشان‌دهنده پایان بخش است که برحسب بایت (یونیکد UTF-8) اندازه‌گیری می‌شود و شامل آن نمی‌شود. اگر نویسه‌های چندبایتی وجود داشته باشد، مثل نویسه‌های غیرASCII، اندازه‌گیری نمایه طولانی‌تر از طول رشته است.
sources[]

CitationSource

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

AnswerReference

ارجاع به منبع را نشان می‌دهد.

فیلدها
فیلد اتحادیه content. حاوی محتوای مرجع است. content فقط می‌تواند یکی از موارد زیر باشد:
document_reference

DocumentReference

فقط خروجی. سند مرجع.

CitationSource

منبع استناد.

فیلدها
reference_index

int32

فقط خروجی. حاوی نمایه Answer.AnswerReference در فیلد تکراری references است.

DocumentReference

نشان‌دهنده ارجاع به سند است.

فیلدها
document_chunk

DocumentChunk

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

AnswerQueryRequest

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

فیلدها
query

string

الزامی. پرسمانی که باید پاسخ داده شود.
filter

string

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

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

  • content_length_bytes (عدد صحیح): طول فیلد Document.content برحسب بایت.
  • data_source (رشته): منبع سند، برای مثال docs.cloud.google.com. برای مشاهده فهرست کامل منابع داده در پیکره، به https://developers.google.com/knowledge/reference/corpus-reference مراجعه کنید.
  • update_time (مُهر زمان): مُهر زمان آخرین باری که سند به‌طور معناداری به‌روز شده است. به‌روزرسانی معنادار به‌روزرسانی‌ای است که محتوای نشان‌گذاری یا فراداده سند را تغییر دهد.
  • uri (رشته): شناسه منبع یکسان سند، برای مثال https://docs.cloud.google.com/bigquery/docs/tables.

فیلدهای INTEGER از عملگرهای =، <، <=، >، و >= پشتیبانی می‌کنند.

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

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

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

مثال‌ها:

  • فیلتر براساس Document.content_length_bytes: content_length_bytes < 50000
  • 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 می‌شود.

AnswerQueryResponse

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

فیلدها
answer

Answer

پاسخ به پُرسمان.

BatchGetDocumentsRequest

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

فیلدها
names[]

string

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

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

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

DocumentView

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

BatchGetDocumentsResponse

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

فیلدها
documents[]

Document

حاوی اسناد درخواست‌شده باشد.

سند

«سند» نشان‌دهنده صفحه‌ای از اسناد در مجموعه «دانش توسعه‌دهنده» است، مانند صفحه https://docs.cloud.google.com/storage/docs/creating-buckets.

فیلدها
name

string

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

string

فقط خروجی. شناسه منبع یکسان محتوا را ارائه می‌دهد، مانند https://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 سند را مشخص می‌کند.
content_length_bytes

int32

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

DocumentChunk

یک 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 برای واکشی محتوای کامل سند استفاده کنند.
relevance_score

double

فقط خروجی. نشان‌دهنده امتیاز ارتباط قطعه با پُرسمان جستجو است. امتیاز بالاتر نشان‌دهنده ارتباط بیشتر بخش است. امتیاز در محدوده [0.0, 1.0] است.

DocumentView

مشخص می‌کند کدام فیلدهای Document گنجانده شده است.

شمارشی‌ها
DOCUMENT_VIEW_UNSPECIFIED مقدار پیش‌فرض / تنظیم‌نشده. اگر DocumentView مشخص نشده باشد، مقدار پیش‌فرض هر روش میانای برنامه‌سازی کاربردی را ببینید.
DOCUMENT_VIEW_BASIC

فقط شامل فیلدهای فراداده پایه می‌شود:

  • name
  • uri
  • data_source
  • title
  • description
  • update_time
  • view
  • content_length_bytes

این نمای پیش‌فرض برای DeveloperKnowledge.SearchDocumentChunks است.
DOCUMENT_VIEW_FULL شامل همه فیلدهای Document می‌شود.
DOCUMENT_VIEW_CONTENT

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

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

GetDocumentRequest

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

فیلدها
name

string

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

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

DocumentView

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

SearchDocumentChunksRequest

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

فیلدها
query

string

الزامی. رشته پُرسمان خام ارائه‌شده توسط کاربر را ارائه می‌دهد، مانند «چگونه یک سطل Cloud Storage ایجاد کنیم؟». پُرسمان نباید بیشتر از ۵۰۰ نویسه باشد؛ مقادیر طولانی‌تر از ۵۰۰ نویسه منجر به خطای INVALID_ARGUMENT می‌شود.
page_size

int32

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

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

حداکثر مقدار ۱۰۰ است؛ مقادیر بالاتر از ۱۰۰ به ۱۰۰ تبدیل خواهند شد.
page_token

string

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

string

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

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

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

  • content_length_bytes (عدد صحیح): طول فیلد Document.content برحسب بایت.
  • data_source (رشته): منبع سند، برای مثال docs.cloud.google.com. برای مشاهده فهرست کامل منابع داده در پیکره، به https://developers.google.com/knowledge/reference/corpus-reference مراجعه کنید.
  • update_time (مُهر زمان): مُهر زمان آخرین باری که سند به‌طور معناداری به‌روز شده است. به‌روزرسانی معنادار به‌روزرسانی‌ای است که محتوای نشان‌گذاری یا فراداده سند را تغییر دهد.
  • uri (رشته): شناسه منبع یکسان سند، برای مثال https://docs.cloud.google.com/bigquery/docs/tables.

فیلدهای INTEGER از عملگرهای =، <، <=، >، و >= پشتیبانی می‌کنند.

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

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

توجه: نام فیلدها باید در snake_case باشد (مثلاً data_source). مقادیر سمت راست عبارت‌های فیلتر باید رشته‌های دقیق محصور در گیومه باشند (مثلاً "docs.cloud.google.com").

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

مثال‌ها:

  • فیلتر براساس Document.content_length_bytes: content_length_bytes < 50000
  • 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 می‌شود.

SearchDocumentChunksResponse

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

فیلدها
results[]

DocumentChunk

حاوی نتایج جستجو برای پرسمان ارائه‌شده است. هر DocumentChunk در این فهرست حاوی گزیده‌ای از محتوای مرتبط با پُرسمان جستجو است. از فیلد DocumentChunk.parent هر نتیجه با DeveloperKnowledge.GetDocument یا DeveloperKnowledge.BatchGetDocuments برای بازیابی محتوای کامل سند استفاده کنید.
next_page_token

string

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