Package google.developers.knowledge.v1

אינדקס

DeveloperKnowledge

‫Developer Knowledge API מספק גישה פרוגרמטית לתיעוד הפומבי של Google למפתחים, ומאפשר לכם לשלב את מאגר הידע הזה באפליקציות ובסביבות העבודה שלכם.

ה-API נועד להיות המקור הקנוני לגישה לקריאת מכונה למסמכי העזרה למפתחים של Google.

תרחיש שימוש אופייני הוא קודם להשתמש ב-DeveloperKnowledge.SearchDocumentChunks כדי למצוא כתובות URI רלוונטיות של דפים על סמך שאילתה, ואז להשתמש ב-DeveloperKnowledge.GetDocument או ב-DeveloperKnowledge.BatchGetDocuments כדי לאחזר את התוכן המלא של התוצאות המובילות.

כל תוכן המסמך מופיע בפורמט Markdown.

BatchGetDocuments

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.
GetDocument

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.
SearchDocumentChunks

rpc SearchDocumentChunks(SearchDocumentChunksRequest) returns (SearchDocumentChunksResponse)

חיפוש ידע למפתחים במסמכי התיעוד למפתחים של Google. הפונקציה מחזירה DocumentChunks על סמך השאילתה של המשתמש. יכול להיות שיש הרבה נתונים מאותו 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.

BatchGetDocumentsRequest

בקשת הודעה עבור DeveloperKnowledge.BatchGetDocuments.

שדות
names[]

string

חובה. מציינת את השמות של המסמכים שיש לאחזר. אפשר לאחזר עד 20 מסמכים באצווה. המסמכים מוחזרים באותו סדר שבו הם מופיעים בבקשה names.

פורמט: documents/{uri_without_scheme} דוגמה: documents/docs.cloud.google.com/storage/docs/creating-buckets
view

DocumentView

אופציונלי. מציין את DocumentView של המסמך. אם לא מציינים ערך, ברירת המחדל של DeveloperKnowledge.BatchGetDocuments היא DOCUMENT_VIEW_CONTENT.

BatchGetDocumentsResponse

הודעת תגובה ל-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

‫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 כדי לאחזר את התוכן המלא של המסמך.

DocumentView

מציינים אילו שדות של Document נכללים.

טיפוסים בני מנייה (enum)
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.

GetDocumentRequest

בקשת הודעה עבור 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.

SearchDocumentChunksRequest

בקשת הודעה עבור DeveloperKnowledge.SearchDocumentChunks.

שדות
query

string

חובה. השדה הזה מכיל את מחרוזת השאילתה הגולמית שהמשתמש סיפק, למשל 'איך יוצרים קטגוריה של Cloud Storage?'.
page_size

int32

אופציונלי. מציין את המספר המקסימלי של תוצאות שיוחזרו. יכול להיות שהשירות יחזיר פחות מהערך הזה.

אם לא מציינים ערך, יוצגו לכל היותר 5 תוצאות.

הערך המקסימלי הוא 20. ערכים מעל 20 יגרמו לשגיאה INVALID_ARGUMENT.
page_token

string

אופציונלי. כולל טוקן של דף שהתקבל מקריאה קודמת של SearchDocumentChunks. צריך להזין את הטוקן כדי לאחזר את הדף הבא.
filter

string

אופציונלי. החלת מסנן מחמיר על תוצאות החיפוש. הביטוי תומך בקבוצת משנה של התחביר שמתואר בכתובת https://google.aip.dev/160.

הפונקציה SearchDocumentChunks מחזירה DocumentChunk, אבל המסנן מוחל על השדות DocumentChunk.document.

שדות נתמכים לסינון:

  • ‫data_source (מחרוזת): המקור של המסמך, למשל docs.cloud.google.com. הרשימה המלאה של מקורות הנתונים בקורפוס זמינה בכתובת https://developers.google.com/knowledge/reference/corpus-reference.
  • ‫update_time (TIMESTAMP): חותמת הזמן של העדכון המשמעותי האחרון של המסמך. עדכון משמעותי הוא עדכון שמשנה את תוכן ה-Markdown או את המטא-נתונים של המסמך.
  • ‫uri (מחרוזת): ה-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 לא יכולה להיות ארוכה מ-500 תווים. ערכים ארוכים מ-500 תווים יגרמו לשגיאה INVALID_ARGUMENT.

SearchDocumentChunksResponse

הודעת תגובה ל-DeveloperKnowledge.SearchDocumentChunks.

שדות
results[]

DocumentChunk

מכיל את תוצאות החיפוש של השאילתה שצוינה. כל DocumentChunk ברשימה הזו מכיל קטע תוכן שרלוונטי לשאילתת החיפוש. כדי לאחזר את התוכן המלא של המסמך, משתמשים בשדה DocumentChunk.parent של כל תוצאה עם DeveloperKnowledge.GetDocument או DeveloperKnowledge.BatchGetDocuments.
next_page_token

string

אופציונלי. התגובה כוללת טוקן שאפשר לשלוח כ-page_token כדי לאחזר את הדף הבא. אם משמיטים את השדה הזה, לא יופיעו דפים נוספים.