מדריך למתחילים: שימוש ב-CLI של gcloud עם Developer Knowledge API

במדריך למתחילים הזה נסביר איך להשתמש ב-Google Cloud CLI כדי להריץ שאילתות, לחפש ולאחזר מסמכי עזרה למפתחים באמצעות Developer Knowledge API.

לפני שמתחילים

לפני שמתחילים להשתמש ב-Developer Knowledge API עם ה-CLI של gcloud, צריך לבצע את השלבים הבאים.

התקנה והגדרה של ה-CLI של gcloud

כדי להתקין ולהגדיר את ה-CLI של gcloud, פועלים לפי השלבים הבאים:

  1. אם לא התקנתם את ה-CLI של gcloud, מתקינים אותו.

  2. מריצים את הפקודה gcloud components update כדי לוודא שמותקנת אצלכם הגרסה העדכנית:

    gcloud components update

  3. נכנסים לחשבון Google Cloud על ידי הפעלת הפקודה gcloud auth login:

    gcloud auth login

  4. מגדירים את הפרויקט הפעיל ב-Google Cloud באמצעות הפקודה gcloud config set:

    gcloud config set project PROJECT_ID

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

הפעלת ה-API

כדי להפעיל את Developer Knowledge API:

  1. מפעילים את Developer Knowledge API בפרויקט בענן ב-Google Cloud באמצעות הפקודה gcloud services enable:

    gcloud services enable developerknowledge.googleapis.com

    לא צריך תפקידים ספציפיים ב-IAM (המערכת לניהול הזהויות והרשאות הגישה) כדי להפעיל את ה-API או להשתמש בו.

  2. מריצים את הפקודה gcloud services list כדי לוודא שה-API מופעל בפרויקט:

    gcloud services list --enabled \
    --filter="name:developerknowledge.googleapis.com"

    הפלט מציג את השם והכותרת של ה-API:

    NAME                                     TITLE
developerknowledge.googleapis.com  Developer Knowledge API

יצירת תשובות מתוך תיעוד

הפקודה gcloud developer-knowledge answer-query מאפשרת לשאול שאלות על מוצרי Google ולקבל תשובות ישירות בשפה טבעית. הפקודה שולפת מידע ממקורות רשמיים של מסמכים ומספקת ציטוטים לדפים שאליהם היא מתייחסת.

כדי לשאול שאלה ולקבל תשובה, מבצעים את השלבים הבאים:

  1. מריצים את הפקודה הבאה כדי לשאול איך ליצור קטגוריה של Cloud Storage:

    gcloud developer-knowledge answer-query \
    --query="How do I create a Cloud Storage bucket?"

  2. מוודאים שהפקודה מחזירה תשובה שנוצרה והפניות למקורות בפורמט YAML:

    answer:
  answerText: |-
    To create a Cloud Storage bucket, you can use the Google Cloud console,
    the gcloud CLI (`gcloud storage buckets create`), client libraries, or
    the REST API...
  citations:
  - endIndex: 158
    sources:
    - referenceIndex: 0
    startIndex: 0
  references:
  - documentReference:
      documentChunk:
        content: |-
          This document shows you how to create a Cloud Storage
          [bucket](https://docs.cloud.google.com/storage/docs/buckets)...
        document:
          dataSource: docs.cloud.google.com
          name: documents/docs.cloud.google.com/storage/docs/creating-buckets
          title: Create a bucket
          uri: https://docs.cloud.google.com/storage/docs/creating-buckets
        parent: documents/docs.cloud.google.com/storage/docs/creating-buckets

    אובייקט answer בפלט כולל את השדות הבאים:

    • ‫answerText: התשובה שנוצרה בשפה טבעית לשאילתה שלכם.
    • ‫citations: טווחי היסט בבייטים, startIndex ו-endIndex, ב-answerText שממופים לרשומות תומכות ב-references באמצעות referenceIndex.
    • ‫references: נתונים על המקורות ששימשו ליצירת התשובה, כולל document ו-parent.

חיפוש של קטעי מסמכים

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

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

  1. מריצים את הפקודה הבאה כדי לחפש תיעוד בנושא יצירת קטגוריות של Cloud Storage:

    gcloud developer-knowledge documents search-chunks \
    --query="How do I create a Cloud Storage bucket?"

  2. מוודאים שהפקודה מחזירה רשימה של חלקי מסמכים תואמים בפורמט YAML:

    ---
content: |-
  This document shows you how to create a Cloud Storage
  [bucket](https://docs.cloud.google.com/storage/docs/buckets). If not otherwise
  specified in your request, buckets are created in the
  [US multi-region](https://docs.cloud.google.com/storage/docs/locations)...
document:
  contentLengthBytes: 31842
  dataSource: docs.cloud.google.com
  description: World-wide storage and retrieval of data in Google Cloud.
  name: documents/docs.cloud.google.com/storage/docs/creating-buckets
  title: Create a bucket
  updateTime: '2026-09-10T20:05:41Z'
  uri: https://docs.cloud.google.com/storage/docs/creating-buckets
  view: DOCUMENT_VIEW_BASIC
id: c1
parent: documents/docs.cloud.google.com/storage/docs/creating-buckets
relevanceScore: 0.856608

    כל מקטע בפלט כולל את השדות הבאים:

    • ‫content: קטע הטקסט התואם מהתיעוד.
    • ‫document: מטא-נתונים על מסמך המקור, כולל title,‏ description,‏ uri,‏ dataSource ו-updateTime.
    • ‫id: המזהה של החלק במסמך.
    • ‫parent: שם המשאב של מסמך האב. אפשר להעביר את הערך הזה אל הפקודה describe כדי לאחזר את המסמך המלא.
    • ‫relevanceScore: ציון הרלוונטיות של החלק לשאילתת החיפוש.

שליפת מסמך

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

מריצים את הפקודה gcloud developer-knowledge documents describe עם שם המשאב של המסמך. לדוגמה, כדי לאחזר את המסמך בנושא יצירת קטגוריות של Cloud Storage, מבצעים את השלבים הבאים:

  1. מריצים את הפקודה הבאה:

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

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

    content: |
  This document shows you how to create a Cloud Storage [bucket](https://docs.cloud.google.com/storage/docs/buckets). If not otherwise specified in your request, buckets are
  created in the [`US` multi-region](https://docs.cloud.google.com/storage/docs/locations)
  with a default storage class of [Standard storage](https://docs.cloud.google.com/storage/docs/storage-classes)
  and have a seven-day [soft delete](https://docs.cloud.google.com/storage/docs/soft-delete)
  retention duration...
contentLengthBytes: 31842
dataSource: docs.cloud.google.com
description: World-wide storage and retrieval of data in Google Cloud.
name: documents/docs.cloud.google.com/storage/docs/creating-buckets
title: Create a bucket
updateTime: '2026-09-10T20:05:41Z'
uri: https://docs.cloud.google.com/storage/docs/creating-buckets
view: DOCUMENT_VIEW_CONTENT

    הפלט כולל את השדות הבאים:

    • ‫content: טקסט ה-Markdown המלא של המסמך.
    • ‫contentLengthBytes: הגודל הכולל של תוכן המסמך בבייטים.
    • ‫dataSource: הדומיין של המסמך שבו מתארח המסמך.
    • ‫description: סיכום קצר של המסמך.
    • ‫name: שם המשאב הייחודי של המסמך.
    • ‫title: שם המסמך.
    • ‫updateTime: חותמת הזמן שבה המסמך עודכן בפעם האחרונה.
    • ‫uri: כתובת ה-URL הציבורית של דף התיעוד.
    • ‫view: התצוגה של המסמך שהוחזרה (DOCUMENT_VIEW_CONTENT, DOCUMENT_VIEW_BASIC או DOCUMENT_VIEW_FULL).

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