Developer Knowledge API

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

סקירה כללית

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

• ‫SearchDocumentChunks כדי למצוא קטעי תוכן וכתובות URI רלוונטיות של דפים על סמך שאילתה.
• ‫GetDocument או BatchGetDocuments כדי לאחזר את התוכן המלא של תוצאות החיפוש.
• ‫AnswerQuery כדי ליצור תשובות לשאילתות שמבוססות על מאגר התיעוד.

‫Developer Knowledge API תומך בחיפוש ובאחזור של דפי תיעוד כתוכן Markdown לא מובנה. מאגר התוכן שניתן לחפש בו מפורט במסמך העזר של המאגר.

איך להשתמש ב-Developer Knowledge

אתם יכולים לגשת ל-Developer Knowledge דרך הפלטפורמות הבאות, בהתאם לתהליך העבודה שלכם:

• ‫API בארכיטקטורת REST ו-RPC API: קוראים ישירות לנקודות הקצה של HTTP או gRPC. בחומרי העזר של REST ובחומרי העזר של RPC מפורטים המאפיינים של ה-methods.
• ספריות לקוח: משלבים את Developer Knowledge API באפליקציות באמצעות ספריות לקוח רשמיות ל-C#‎,‏ Go,‏ Java,‏ Node.js ו-TypeScript,‏ PHP,‏ Python ו-Ruby.
• ‫Google Cloud CLI‏ (gcloud): מריצים פקודות gcloud developer-knowledge מהטרמינל כדי לחפש קטעי מסמכים, לאחזר תוכן Markdown וליצור תשובות.
• ‫Developer Knowledge MCP server: מחברים את העוזר האישי או הסוכן לתכנות מבוסס-AI למסמכי התיעוד של Google באמצעות כלי Model Context Protocol ‏ (MCP) (search_documents,‏ get_documents ו-answer_query). מידע נוסף זמין בחומר העזר בנושא MCP.

טיפ: אם אתם משתמשים בעוזר AI לעזרה בתכנות, אתם יכולים להתקין את הסקיל האג'נטי retrieving-developer-knowledge באמצעות הפקודה npx skills add google/skills --skill retrieving-developer-knowledge. הסקיל הזה מספק לעוזר האישי הוראות מובנות לגבי הכלי בשרת ה-MCP של Developer Knowledge שבו צריך לבחור, איך לטפל בשגיאות ואיך לקרוא ל-API בארכיטקטורת REST באמצעות curl אם שרת ה-MCP לא זמין. מידע נוסף זמין במאמר בנושא שימוש במיומנות של סוכן הידע למפתחים.

בוחרים בין ה-API לבין שרת ה-MCP

‫Developer Knowledge API ושרת MCP מיועדים לצרכים שונים של שילוב:

• משתמשים ב-Developer Knowledge API, בספריות לקוח או ב-CLI של gcloud במקרים הבאים:
  • בפרויקט שלכם לא נעשה שימוש בסוכן AI.
  • אתם רוצים להגדיר כלים מותאמים אישית או קבוצות כלים לסוכן.
  • אתם רוצים לעבד או לשלב תוצאות לפני שאתם מעבירים אותן למודל (לדוגמה, לבדוק את אורך המסמך בבייטים לפני שאתם מאחזרים את התוכן המלא).
  • צריך לסנן את תוצאות החיפוש (למשל לפי data_source או update_time) או להחיל מסכות שדות.
• כדאי להשתמש בשרת ה-MCP ובמיומנות הסוכן של Developer Knowledge במקרים הבאים:
  • אתם רוצים לחבר סוכן או עוזר AI לעזרה בתכנות בלי לכתוב הגדרות ותיאורים של כלים בהתאמה אישית.
  • אתם רוצים עדכונים אוטומטיים כשהשרת Developer Knowledge MCP מוסיף יכולות חדשות.
  • אתם לא צריכים סינון מותאם אישית של מטא נתונים בתוצאות החיפוש.

הפעלת ה-API

כדי להשתמש ב-Developer Knowledge API, קודם צריך להפעיל אותו בפרויקט ב-Google Cloud.

הערה: אם אין לכם פרויקט ב-Google Cloud, אתם יכולים ליצור פרויקט חדש באמצעות ההוראות ל-Google Cloud או ל-Firebase.

1. פותחים את הדף של Developer Knowledge API בספריית Google APIs.
2. מוודאים שבחרתם את הפרויקט הנכון שבו אתם מתכוונים להשתמש ב-API.
3. לוחצים על הפעלה. לא נדרשים תפקידים ספציפיים ב-IAM כדי להפעיל את ה-API או להשתמש בו.

אימות

אפשר לאמת בקשות ל-Developer Knowledge API באחת מהשיטות הבאות:

• מפתח API: מאמתים בקשות REST ישירות או את שרת ה-MCP של Developer Knowledge באמצעות פרמטר השאילתה key או הכותרת X-Goog-Api-Key.
• ‫Application Default Credentials ‏ (ADC),‏ OAuth 2.0 או חשבונות שירות: אימות בקשות כשמשתמשים בספריות הלקוח הרשמיות או בתהליכי עבודה בסביבת הייצור. מידע נוסף על הגדרת פרטי כניסה זמין במסמכי Application Default Credentials.
• פרטי כניסה של משתמש (ה-CLI של gcloud): אימות של בקשות CLI על ידי כניסה לחשבון Google Cloud באמצעות gcloud auth login. הוראות להגדרה מופיעות במדריך למתחילים של ה-CLI של gcloud.

היקפי ההרשאות של OAuth

כשמבצעים אימות באמצעות OAuth 2.0 או חשבונות שירות, ה-API של Developer Knowledge ושרת ה-MCP של Developer Knowledge מקבלים את היקפי ההרשאות הבאים של OAuth:

• ‫https://www.googleapis.com/auth/cloud-platform: היקף ברירת המחדל שמשמש את Application Default Credentials ‏ (ADC), את ה-CLI של gcloud ואת ספריות הלקוח הרשמיות של Google Cloud.
• ‫https://www.googleapis.com/auth/devprofiles.full_control: היקף ההרשאות שמשמש לתהליכי הסכמה של משתמשים ב-OAuth 2.0 ולשילובים של שרתי MCP.
• ‫https://www.googleapis.com/auth/developerprofiles.readonly: היקף קריאה בלבד שנתמך בחשבונות שירות ובפרטי כניסה שלא דורשים מסך הסכמה ל-OAuth של משתמש קצה.

הרשאה באמצעות טוקן למוכ"ז

כדי לאמת בקשות REST ישירות באמצעות חשבון שירות או אסימון גישה מסוג OAuth 2.0, מעבירים את האסימון בכותרת Authorization: Bearer ומציינים את הפרויקט לחיוב ב-X-Goog-User-Project:

export ACCESS_TOKEN=$(gcloud auth print-access-token)
curl -X POST "https://developerknowledge.googleapis.com/v1:answerQuery" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I create a BigQuery dataset?"}'

מחליפים את PROJECT_ID במזהה של הפרויקט ב-Google Cloud.

באפליקציות ב-Python, ב-Node.js, ב-Go וב-Java, ספריות הלקוח הרשמיות מטפלות באופן אוטומטי ב-Application Default Credentials ‏ (ADC) וברענון האסימונים. דוגמאות מופיעות במאמר שימוש בספריות לקוח עם Developer Knowledge API.

מסמכים כלולים

מידע על המסמכים שמתבצע בהם חיפוש באמצעות ה-API מופיע במאמר הפניית מאגר מידע.

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

מגבלות ידועות

• איכות ה-Markdown: ה-Markdown נוצר מה-HTML של המקור. יכול להיות שיהיו אי התאמות או בעיות עיצוב.
• היקף התוכן: רק דפים שגלויים לכולם במאגר המידע נכללים. התוכן לא כולל תוכן ממקורות אחרים כמו GitHub, אתרי OSS, בלוגים או YouTube.