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

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

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

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

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

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

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

חיפוש מסמכים באמצעות `SearchDocumentChunks`

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

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

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.

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

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

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

בקשה של הדף הראשון

כדי להגדיר את גודל הדף, מעבירים את הפרמטר 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 מושמט מהתגובה.

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

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

האורך של הביטוי filter מוגבל ל-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 (או -).

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

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

התאמה למספר מקורות נתונים

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

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

curl בקשה:

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"

curl בקשה:

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

curl בקשה:

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"

curl בקשה:

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"

curl בקשה:

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"

אחזור מסמך באמצעות `GetDocument`

משתמשים בשיטה documents.get כדי לאחזר את התוכן המלא של מסמך יחיד.

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

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

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

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

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

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

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

הערכים הבאים נתמכים ב-enum‏ DocumentView:

‫DOCUMENT_VIEW_BASIC: מחזירה רק שדות בסיסיים של מטא-נתונים (name,‏ uri,‏ data_source,‏ title,‏ description,‏ update_time ו-view). השדה content מושמט.
‫DOCUMENT_VIEW_CONTENT: מחזירה שדות של מטא-נתונים יחד עם השדה [Markdown] ‫content. זוהי ברירת המחדל לתגים GetDocument ו-BatchGetDocuments.
‫DOCUMENT_VIEW_FULL: מחזירה את כל השדות של המסמך.

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

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"

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

ה-Developer Knowledge API מחזיר קודי סטטוס רגילים של 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: הפרויקט חרג מהמכסה שלו. מידע נוסף זמין במאמר בנושא מכסות ומגבלות.

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

איך עונים על שאילתות באמצעות יצירה שמבוססת על מקורות
איך משתמשים בספריות לקוח ב-Python, ב-Node.js, ב-Go או ב-Java
אפשר לעיין במאמרי העזרה כדי לראות את כל המקורות הנתמכים של מסמכים.
במאמרי העזרה של ה-API בארכיטקטורת REST מפורטות כל המפרטים של ה-methods.
בדקו את המכסות והמגבלות של קצב יצירת הבקשות ומכסות ה-API.

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

חיפוש מסמכים באמצעות SearchDocumentChunks

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

בקשה של הדף הראשון

אחזור דפים עוקבים

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

שדות נתמכים

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

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

התאמה למספר מקורות נתונים

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

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

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

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

אחזור מסמך באמצעות GetDocument

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

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

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

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

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

שדות סינון בGetDocument

שדות סינון בBatchGetDocuments

שדות סינון בSearchDocumentChunks

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

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

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

חיפוש מסמכים באמצעות `SearchDocumentChunks`

אחזור מסמך באמצעות `GetDocument`

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

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

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

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