شروع سریع: استفاده از gcloud CLI با Developer Knowledge API

این راهنمای شروع سریع نشان می‌دهد که چگونه بااستفاده از Google Cloud CLI، به پُرسمان‌ها پاسخ دهید و اسناد توسعه‌دهندگان را بااستفاده از Developer Knowledge API جستجو و بازیابی کنید.

قبل‌از شروع

قبل‌از شروع استفاده از Developer Knowledge API با gcloud CLI، مراحل زیر را تکمیل کنید.

نصب و پیکربندی gcloud CLI

برای نصب و پیکربندی gcloud CLI، مراحل زیر را تکمیل کنید:

  1. اگر gcloud CLI را نصب نکرده‌اید، gcloud CLI را نصب کنید.

  2. برای اطمینان از اینکه جدیدترین نسخه را دارید، فرمان gcloud components update را اجرا کنید:

    gcloud components update

  3. با اجرای فرمان gcloud auth login به سیستم حساب Google Cloud خود وارد شوید:

    gcloud auth login

  4. با اجرای فرمان gcloud config set، پروژه Google Cloud فعال خود را تنظیم کنید:

    gcloud config set project PROJECT_ID

    PROJECT_ID را با شناسه پروژه Google Cloud خودتان جایگزین کنید.

فعال کردن میانای برنامه‌سازی کاربردی

برای فعال کردن «میانای برنامه‌سازی کاربردی دانش توسعه‌دهنده»، مراحل زیر را تکمیل کنید:

  1. با اجرای فرمان gcloud services enable، میانای برنامه‌سازی کاربردی Developer Knowledge را در پروژه Google Cloud خود فعال کنید:

    gcloud services enable developerknowledge.googleapis.com

    برای فعال کردن یا استفاده از API، به نقش‌های خاص «مدیریت هویت و دسترسی‌ها» (IAM) نیاز ندارید.

  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 buckets، فرمان زیر را اجرا کنید:

    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: نشانی وب عمومی صفحه مستندات.
    • ‫view: نمای سند برگشت (DOCUMENT_VIEW_CONTENT، DOCUMENT_VIEW_BASIC، یا DOCUMENT_VIEW_FULL).

قدم بعدی چیست