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

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

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

במאמר הזה מופיעות דוגמאות למשימות הבאות:

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

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

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 או ב-method ל-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].

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

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

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

‫--page-size (ה-CLI של gcloud) או pageSize (מספר שלם): מציין את מספר התוצאות המקסימלי שיוחזרו בכל דף. אם לא מציינים ערך, ה-API יחזיר כברירת מחדל חמש תוצאות. הערך המקסימלי המותר הוא 100. ערכים גבוהים יותר יומרו ל-100.
‫--limit (ה-CLI של gcloud) או 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 (מחרוזת): דומיין המקור של המסמך, למשל 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 או ב-method ל-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`

משתמשים ב-method‏ 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 או חותמות זמן) או שדות ספציפיים, אפשר לבצע אופטימיזציה של גודל המטען הייעודי (payload) כדי לצמצם את רוחב הפס ואת זמן הטעינה.

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

הדגל --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"

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

כדי להגביל עוד יותר את המטען הייעודי (payload) של התגובה לשדות ספציפיים, משתמשים בפרמטרים של שאילתה הרגילים של Google APIs fields (מסכת שדה).

סינון שדות ב-`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).
- צוינו יותר מ-20 שמות של מסמכים בבקשה מסוג BatchGetDocuments.
‫401 UNAUTHENTICATED: בבקשה חסר מפתח API או טוקן למוכ"ז, או שהיא משתמשת בפרטי כניסה לא חוקיים. מידע נוסף זמין במאמר בנושא אימות.
‫404 NOT_FOUND: שם המסמך המבוקש לא קיים או שייך לדומיין שלא נכלל בקורפוס.
‫429 RESOURCE_EXHAUSTED: הפרויקט חרג מהמכסה שלו. מידע נוסף זמין במאמר בנושא מכסות ומגבלות.

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

יצירת תשובות ממסמכים
התחברו לשרת Developer Knowledge MCP והתקינו את מיומנות הסוכן של retrieving-developer-knowledge כדי לעזור לעוזר האישי מבוסס ה-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`