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

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

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

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"

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

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

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

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

  • ‫data_source (STRING): המקור של המסמך, לדוגמה, docs.cloud.google.com.
  • ‫update_time (TIMESTAMP): חותמת הזמן של העדכון האחרון של המסמך.
  • ‫uri (STRING): ה-URI של המסמך, לדוגמה: https://docs.cloud.google.com/bigquery/docs/tables.

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

  • בשדות STRING יש תמיכה באופרטורים = (שווה) ו-!= (לא שווה) להתאמות מדויקות של המחרוזת כולה.
  • שדות חותמת הזמן תומכים בערכים =, <, <=, > ו->=. חותמות הזמן צריכות להיות בפורמט RFC-3339 (לדוגמה, "2025-01-01T00:00:00Z").

אפשר לשלב בין ביטויים באמצעות האופרטורים הלוגיים AND, OR ו-NOT (או -). שימו לב שהתג OR מקבל עדיפות גבוהה יותר מהתג AND.

בדוגמה הבאה מחפשים מסמכים שתואמים למונח BigQuery ומגבילים את התוצאות לאלה שמגיעות מ-docs.cloud.google.com:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&filter=data_source%3D%22docs.cloud.google.com%22&key=$DEVELOPERKNOWLEDGE_API_KEY"

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

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

בדוגמה הבאה מאחזרים מסמך בשם documents/DOCUMENT_ID:

curl "https://developerknowledge.googleapis.com/v1/documents:get?name=documents/DOCUMENT_ID&key=$DEVELOPERKNOWLEDGE_API_KEY"

התשובה היא משאב Document מלא, כולל השדה content.

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

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

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

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/DOCUMENT_ID_1&names=documents/DOCUMENT_ID_2&key=$DEVELOPERKNOWLEDGE_API_KEY"

התשובה מכילה רשימה של משאבי Document המבוקשים.