Package google.developers.knowledge.v1alpha

אינדקס

DeveloperKnowledge

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

ה-API נועד להיות המקור הקנוני לגישה בפורמט קריא למכונה למאמרי העזרה למפתחים של 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. מחזירה DocumentChunks על סמך השאילתה של המשתמש. יכולים להיות הרבה קטעים מאותו 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 unicode), כולל. אם יש תווים של כמה בייטים, כמו תווים שאינם ASCII, מדידת האינדקס ארוכה יותר מאורך המחרוזת.
end_index

int32

פלט בלבד. מציין את סוף הקטע, נמדד בבייטים (UTF-8 unicode), לא כולל. אם יש תווים של כמה בייטים, כמו תווים שאינם 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 (STRING): מקור המסמך, למשל 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.

שדות INTEGER תומכים באופרטורים =,‏ <,‏ <=,‏ > ו->=.

בשדות STRING יש תמיכה באופרטורים = (שווה ל-) ו-!= (לא שווה ל-) להתאמה מדויקת במחרוזת כולה. אין תמיכה בהתאמה חלקית, בהתאמה של קידומת ובהתאמה של ביטוי רגולרי (regex).

שדות 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 יכולה להכיל עד 500 תווים. ערכים ארוכים יותר יגרמו לשגיאה INVALID_ARGUMENT.

AnswerQueryResponse

הודעת התשובה של DeveloperKnowledge.AnswerQuery.

שדות
answer

Answer

התשובה לשאילתה.

BatchGetDocumentsRequest

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

שדות
names[]

string

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

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

כל שם יכול להיות באורך של עד 500 תווים. ערכים ארוכים יותר יגרמו לשגיאת INVALID_ARGUMENT.
view

DocumentView

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

BatchGetDocumentsResponse

הודעת התשובה של DeveloperKnowledge.BatchGetDocuments.

שדות
documents[]

Document

מכיל את המסמכים שביקשנו.

מסמך

מסמך מייצג דף תיעוד במאגר Developer Knowledge, כמו הדף בכתובת 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

פלט בלבד. מספק את ה-URI של התוכן, כמו 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 נכללים.

טיפוסים בני מנייה (enum)
DOCUMENT_VIEW_UNSPECIFIED ערך ברירת המחדל / ערך שלא הוגדר. אם לא צוין DocumentView, אפשר לראות את ערך ברירת המחדל של כל שיטת API.
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

השם לא יכול להיות ארוך מ-500 תווים. ערכים ארוכים יותר יגרמו לשגיאת INVALID_ARGUMENT.
view

DocumentView

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

SearchDocumentChunksRequest

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

שדות
query

string

חובה. מחרוזת השאילתה הגולמית שהמשתמש הזין, למשל "איך יוצרים קטגוריה של Cloud Storage?". השאילתה לא יכולה לחרוג מ-500 תווים. ערכים ארוכים יותר יגרמו לשגיאת INVALID_ARGUMENT.
page_size

int32

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

אם לא מציינים ערך, יוחזרו עד 5 תוצאות.

הערך המקסימלי הוא 100. ערכים גבוהים יותר יומרו ל-100.
page_token

string

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

string

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

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

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

  • ‫content_length_bytes (מספר שלם): האורך של השדה Document.content בבייטים.
  • data_source (STRING): מקור המסמך, למשל 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.

שדות INTEGER תומכים באופרטורים =,‏ <,‏ <=,‏ > ו->=.

בשדות STRING יש תמיכה באופרטורים = (שווה ל-) ו-!= (לא שווה ל-) להתאמה מדויקת במחרוזת כולה. אין תמיכה בהתאמה חלקית, בהתאמה של קידומת ובהתאמה של ביטוי רגולרי (regex).

שדות 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 יכולה להכיל עד 500 תווים. ערכים ארוכים יותר יגרמו לשגיאה INVALID_ARGUMENT.

SearchDocumentChunksResponse

הודעת התשובה של DeveloperKnowledge.SearchDocumentChunks.

שדות
results[]

DocumentChunk

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

string

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