‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

חיפוש ואחזור מסמכים

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

במסמך הזה תמצאו דוגמאות למשימות הבאות:

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

לפני שמתחילים, צריך להגדיר את הסביבה עבור הכלי המועדף:

gcloud

מתקינים ומגדירים את ה-CLI של gcloud ומפעילים את Developer Knowledge API.

REST

הפעלת ה-API ויצירת מפתח Developer Knowledge API. אחר כך שומרים את המפתח במשתנה סביבה:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

מחליפים את הערך YOUR_API_KEY במפתח ה-API שלכם ל-Developer Knowledge.

חיפוש מסמכים

כדי למצוא נתחי מסמכים שתואמים למחרוזת שאילתה, משתמשים בפקודה gcloud developer-knowledge documents search-chunks ‎ או בשיטת REST‏ documents.searchDocumentChunks. התוצאות כוללות קטעי תוכן ממסמכים תואמים, לצד parentהפניה שאפשר להשתמש בה כדי לאחזר את התוכן המלא של המסמכים האלה.

בדוגמה הבאה מתבצע חיפוש של מסמכים שתואמים למונח BigQuery:

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery"

REST

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&key=$DEVELOPERKNOWLEDGE_API_KEY"

הפלט אמור להיראות כך:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "BigQuery overview",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z"
      },
      "relevanceScore": 0.92
    }
  ]
}

כל תוצאה ברשימה results כוללת:

‫parent: שם משאב המסמך (לדוגמה, documents/docs.cloud.google.com/bigquery/docs/introduction).
‫id: מזהה החלק במסמך (לדוגמה, chunk_0).
‫content: קטע הטקסט התואם מהמסמך.
‫document: מטא-נתונים על מסמך המקור, כמו title,‏ uri,‏ dataSource ו-updateTime.
‫relevanceScore: ציון הרלוונטיות של החלק לשאילתת החיפוש, בטווח [0.0, 1.0].

מידע נוסף על סכֵימת תשובה ועל כל שדות המטא-נתונים שזמינים מופיע במאמרי העזרה של ה-API בנושא documents.searchDocumentChunks.

עימוד תוצאות החיפוש

אם שאילתת חיפוש מחזירה כמה התאמות, אפשר לנווט בין התוצאות באמצעות פרמטרים של חלוקה לדפים:

‫--page-size (ה-CLI של gcloud) או pageSize (מספר שלם): מציין את המספר המקסימלי של תוצאות שיוחזרו בכל דף. אם לא מציינים ערך, ה-API יחזיר כברירת מחדל חמש תוצאות. הערך המקסימלי המותר הוא 100. ערכים גבוהים יותר יומרו ל-100.
‫--limit (gcloud CLI) או pageToken (מחרוזת): ב-CLI של gcloud, משתמשים ב---limit כדי לשלוט במספר הכולל של התוצאות שמוחזרות בדפים. בבקשות REST, מעבירים את הערך pageToken שהתקבל בתגובה הקודמת כדי לאחזר את דף התוצאות הבא.

gcloud

מעבירים את הדגלים --page-size ו---limit כדי לשלוט במספר התוצאות בדף ובמספר הכולל של התוצאות שמוחזרות:

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --page-size=5 \
  --limit=10

REST

כדי לבקש את הדף הראשון, מעבירים את הפרמטר pageSize בבקשה:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&key=$DEVELOPERKNOWLEDGE_API_KEY"

אם יש תוצאות נוספות, התשובה כוללת nextPageToken:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "What is BigQuery?",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z",
        "view": "DOCUMENT_VIEW_BASIC"
      },
      "relevanceScore": 0.88
    }
  ],
  "nextPageToken": "CAUQABgB"
}

כדי לאחזר דפים נוספים, צריך להעביר את הערך של nextPageToken לפרמטר pageToken בבקשה הבאה:
```
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"
```
כשמגיעים לדף האחרון של התוצאות, nextPageToken לא מופיע בתגובה.

סינון תוצאות החיפוש

כדי להחיל מסנן מחמיר על תוצאות החיפוש, משתמשים בדגל --query-filter ב-CLI של gcloud או בפרמטר filter בבקשות REST. ביטוי הסינון מוחל על המטא-נתונים של מסמך האב לכל נתח.

אורך הביטוי של המסנן מוגבל ל-500 תווים.

שדות נתמכים

אפשר לסנן את תוצאות החיפוש באמצעות השדות הבאים של מסמך האב:

‫content_length_bytes (מספר שלם): האורך של השדה content במסמך בבייטים.
‫data_source (string): דומיין המקור של המסמך, למשל docs.cloud.google.com או firebase.google.com. במאמר בנושא קורפוסים מפורטים כל מקורות הנתונים הנתמכים.
‫update_time (חותמת זמן): חותמת הזמן שבה המסמך עודכן בפעם האחרונה. הערכים צריכים להיות בפורמט RFC 3339 (לדוגמה, "2025-01-01T00:00:00Z").
‫uri (מחרוזת): ה-URI המלא של המסמך (לדוגמה, https://docs.cloud.google.com/bigquery/docs/tables).

אופרטורים נתמכים

מנתח ביטויי הסינון תומך באופרטורים שונים בהתאם לסוג הנתונים של השדה:

שדות מחרוזת (data_source, uri): תומכים ב-= (שווה ל) וב-!= (לא שווה ל) להתאמה מדויקת של מחרוזות. אין תמיכה בהתאמות חלקיות, בהתאמות של קידומת ובהתאמות של ביטוי רגולרי.
שדות של חותמות זמן (update_time): תמיכה בערכים =, <, <=, > ו->=.
שדות של מספרים שלמים (content_length_bytes): תומכים בערכים =,‏ !=,‏ <,‏ <=,‏ > ו->=.
אופרטורים לוגיים: שילוב תנאים באמצעות AND,‏ OR ו-NOT (או -).

דוגמאות לסינון

בדוגמאות הבאות מוסבר איך ליצור ביטויי סינון. כשמשתמשים ב-CLI של gcloud, מעבירים את הביטוי לדגל --query-filter. כשקוראים ל-API בארכיטקטורת REST עם curl, חשוב לבצע קידוד כתובת URL של הפרמטר filter או להשתמש ב---data-urlencode.

התאמה למקור נתונים יחיד

הגבלת תוצאות החיפוש לדומיין תיעוד יחיד:

data_source = "docs.cloud.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Functions deployment" \
  --query-filter='data_source = "docs.cloud.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Functions deployment" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

התאמה של כמה מקורות נתונים

משתמשים ב-OR כדי לכלול מסמכים מכמה מקורות:

data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="database" \
  --query-filter='data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=database" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

סינון לפי חותמת זמן

כדי למצוא תוכן שעודכן אחרי תאריך מסוים, משתמשים באופרטורים להשוואה עם חותמות זמן בפורמט RFC 3339:

update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --query-filter='update_time >= "2025-01-01T00:00:00Z"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=BigQuery" \
  --data-urlencode 'filter=update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

סינון לפי אורך התוכן

אפשר להשתמש באופרטורים להשוואה עם content_length_bytes כדי למצוא מסמכים לפי גודלם בבייט:

content_length_bytes < 5000

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Storage" \
  --query-filter='content_length_bytes < 5000'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Storage" \
  --data-urlencode 'filter=content_length_bytes < 5000' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

שילוב של מקור נתונים, חותמת זמן וקיבוץ

משלבים בין AND, OR וסוגריים (...) כדי להגביל את התוצאות למקורות ספציפיים שעודכנו אחרי תאריך מסוים:

(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="service worker" \
  --query-filter='(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=service worker" \
  --data-urlencode 'filter=(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

החרגה של מקורות נתונים

כדי להחריג תוצאות ממקור ספציפי, משתמשים בסימן NOT או !=:

data_source != "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="authentication" \
  --query-filter='data_source != "firebase.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=authentication" \
  --data-urlencode 'filter=data_source != "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

שליפת מסמך

כדי לאחזר את התוכן המלא של מסמך יחיד, משתמשים בפקודה gcloud developer-knowledge documents describe או בשיטת ה-REST‏ documents.get.

בדוגמה הבאה מאחזרים מסמך לפי שם המשאב שלו:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"

התשובה היא משאב Document שמכיל מטא-נתונים ואת התוכן המלא ב-Markdown בשדה content.

שמות משאבים לעומת מזהי URI

כשמפנים למסמכים ב-Developer Knowledge API, חשוב לשים לב להבדל בין שמות של משאבים לבין מזהי URI באינטרנט:

שם המשאב (parent,‏ name): בפורמט documents/{uri_without_scheme} (לדוגמה, documents/docs.cloud.google.com/storage/docs/creating-buckets). מעבירים את הערך הזה כארגומנט מיקום ב-gcloud developer-knowledge documents describe, כפרמטר של הנתיב ב-GetDocument או בפרמטר names של BatchGetDocuments.
‫Web URI (uri): כתובת URL מלאה לאתר, כולל הסכימה (לדוגמה, https://docs.cloud.google.com/storage/docs/creating-buckets). משתמשים בפורמט הזה בשדה uri כשיוצרים ביטויים מסוג --query-filter או filter (לדוגמה, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

אחזור של כמה מסמכים באמצעות `BatchGetDocuments`

אפשר להשתמש בשיטה documents.batchGet כדי לאחזר עד 20 מסמכים לפי שם בקריאה ל-API אחת. השיטה הזו יעילה יותר מאשר שליחת כמה בקשות GetDocument.

בדוגמה הבאה מאחזרים שני מסמכים לפי שם:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&key=$DEVELOPERKNOWLEDGE_API_KEY"

התשובה מכילה רשימה של משאבי Document שביקשתם, לפי הסדר שבו ביקשתם אותם.

אופטימיזציה של מטען ייעודי (payload) של תשובות

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

שימוש בתצוגות מסמכים

הדגל --view ב-CLI של gcloud או הפרמטר view בבקשות REST קובעים אילו שדות יאוכלסו בהודעות Document.

הערכים הבאים נתמכים בדגל --view וב-enum‏ DocumentView:

‫--view=basic (ה-CLI של gcloud) או DOCUMENT_VIEW_BASIC: מחזיר רק שדות בסיסיים של מטא-נתונים (name,‏ uri,‏ dataSource,‏ title,‏ description,‏ updateTime ו-view). השדה content מושמט.
‫--view=content (ה-CLI של gcloud) או DOCUMENT_VIEW_CONTENT: מחזירה שדות מטא-נתונים יחד עם השדה content של Markdown. זהו ערך ברירת המחדל של gcloud developer-knowledge documents describe, GetDocument ו-BatchGetDocuments.
‫--view=full (ה-CLI של gcloud) או DOCUMENT_VIEW_FULL: מחזירה את כל השדות במסמך.

כדי לאחזר רק את המטא-נתונים של המסמך בלי להוריד תוכן גדול בפורמט Markdown, מציינים את התצוגה הבסיסית של המסמך:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets \
  --view=basic

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

אפשר גם להשתמש ב-view=DOCUMENT_VIEW_BASIC עם BatchGetDocuments:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

שימוש במסכות שדות

כדי להגביל עוד יותר את מטען הייעודי לתגובה לשדות ספציפיים, משתמשים בפרמטר השאילתה fields (field mask) של ממשקי ה-API הרגילים של Google.

סינון שדות ב-`GetDocument`

כדי לאחזר רק את השדות title, uri ו-updateTime של מסמך:

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?fields=title,uri,updateTime&key=$DEVELOPERKNOWLEDGE_API_KEY"

סינון שדות ב-`BatchGetDocuments`

כדי לאחזר רק שדות ספציפיים לכל מסמך באצווה:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&fields=documents(name,title,uri)&key=$DEVELOPERKNOWLEDGE_API_KEY"

סינון שדות ב-`SearchDocumentChunks`

כדי להחזיר רק את המקטע id ואת content, את מסמך האב title ואת uri, ואת nextPageToken מחיפוש:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&fields=results(id,content,document(title,uri)),nextPageToken&key=$DEVELOPERKNOWLEDGE_API_KEY"

טיפול בשגיאות

ממשק ה-API של Developer Knowledge מחזיר קודי סטטוס רגילים של HTTP. בדוגמאות הפונקציונליות הבאות ממופים קודי סטטוס של HTTP והסיבות להם ב-Developer Knowledge API:

‫400 INVALID_ARGUMENT:
- מחרוזת הביטוי filter ארוכה מ-500 תווים.
- חותמת הזמן update_time לא תקינה (צריך להשתמש בפורמט RFC 3339).
- בBatchGetDocuments בקשה צוינו יותר מ-20 שמות של מסמכים.
‫401 UNAUTHENTICATED: הבקשה לא כוללת מפתח API או שהמפתח לא תקין. מידע על אימות
‫404 NOT_FOUND: שם המסמך המבוקש לא קיים או שהוא שייך לדומיין שלא נכלל במאגר.
‫429 RESOURCE_EXHAUSTED: הפרויקט חרג מהמכסה שלו. מידע נוסף זמין במאמר בנושא מכסות ומגבלות.

המאמרים הבאים

אפשר לעיין במאמר בנושא יצירת תשובות מתוך מסמכים.
מתחברים לשרת ה-MCP של Developer Knowledge ומתקינים את retrieving-developer-knowledge agent skill כדי שעוזר ה-AI לתכנות יוכל לחפש ולקרוא מסמכים רשמיים.
איך משתמשים בספריות לקוח ב-Python, ב-Node.js, ב-Go או ב-Java
איך משתמשים ב-CLI של gcloud
אפשר לעיין במאמרי העזרה כדי לראות את כל המקורות הנתמכים של מסמכים.
במאמרי העזרה של ה-API בארכיטקטורת REST מפורטות כל המפרטים של ה-methods.
בדקו את המכסות והמגבלות של קצב יצירת הבקשות ומכסות ה-API.

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

gcloud

REST

חיפוש מסמכים

gcloud

REST

עימוד תוצאות החיפוש

gcloud

REST

סינון תוצאות החיפוש

שדות נתמכים

אופרטורים נתמכים

דוגמאות לסינון

התאמה למקור נתונים יחיד

gcloud

REST

התאמה של כמה מקורות נתונים

gcloud

REST

סינון לפי חותמת זמן

gcloud

REST

סינון לפי אורך התוכן

gcloud

REST

שילוב של מקור נתונים, חותמת זמן וקיבוץ

gcloud

REST

החרגה של מקורות נתונים

gcloud

REST

שליפת מסמך

gcloud

REST

שמות משאבים לעומת מזהי URI

אחזור של כמה מסמכים באמצעות BatchGetDocuments

אופטימיזציה של מטען ייעודי (payload) של תשובות

שימוש בתצוגות מסמכים

gcloud

REST

שימוש במסכות שדות

סינון שדות ב-GetDocument

סינון שדות ב-BatchGetDocuments

סינון שדות ב-SearchDocumentChunks

טיפול בשגיאות

המאמרים הבאים

חיפוש ואחזור מסמכים

אחזור של כמה מסמכים באמצעות `BatchGetDocuments`

סינון שדות ב-`GetDocument`

סינון שדות ב-`BatchGetDocuments`

סינון שדות ב-`SearchDocumentChunks`