شروع سریع: استفاده از رابط خط فرمان gcloud به همراه رابط برنامه‌نویسی کاربردی دانش توسعه‌دهندگان

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

قبل از اینکه شروع کنی

قبل از شروع استفاده از رابط برنامه‌نویسی کاربردی دانش توسعه‌دهندگان (Developer Knowledge API) با رابط خط فرمان gcloud، مراحل زیر را انجام دهید.

نصب و پیکربندی رابط خط فرمان gcloud

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

  1. اگر رابط خط فرمان gcloud را نصب نکرده‌اید، آن را نصب کنید .

  2. دستور gcloud components update اجرا کنید تا مطمئن شوید که آخرین نسخه را دارید:

    gcloud components update

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

    gcloud auth login

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

    gcloud config set project PROJECT_ID

    به جای PROJECT_ID ، شناسه پروژه گوگل کلود خود را وارد کنید.

فعال کردن API

برای فعال کردن رابط برنامه‌نویسی کاربردی دانش توسعه‌دهندگان (Developer Knowledge API)، مراحل زیر را انجام دهید:

  1. با اجرای دستور gcloud services enable ، رابط برنامه‌نویسی کاربردی دانش توسعه‌دهندگان (Developer Knowledge API) را در پروژه گوگل کلود خود فعال کنید:

    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 به شما امکان می‌دهد در مورد محصولات گوگل سؤال بپرسید و پاسخ‌های مستقیم و به زبان طبیعی دریافت کنید. این دستور اطلاعات را از منابع رسمی اسناد استخراج می‌کند و به صفحات ارجاع داده شده استناد می‌دهد.

برای پرسیدن سوال و دریافت پاسخ، مراحل زیر را انجام دهید:

  1. دستور زیر را اجرا کنید تا بپرسید چگونه یک سطل ذخیره‌سازی ابری ایجاد کنید:

    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 که با استفاده از referenceIndex به ورودی‌های پشتیبانی در references نگاشت می‌شوند.
    • references : بخش‌هایی از مستندات منبع و فراداده‌ها، شامل document و parent که برای تولید پاسخ استفاده می‌شوند.

جستجوی تکه‌های سند

برای یافتن گزیده‌های متنی خاص در مستندات توسعه‌دهندگان گوگل به جای پاسخ تولید شده، از دستور gcloud developer-knowledge documents search-chunks استفاده کنید. این دستور مجموعه‌ی مستندات را اسکن کرده و بخش‌های محتوای منطبق را در کنار نام منابع اسناد والد آنها برمی‌گرداند.

برای جستجوی تکه‌های سند، مراحل زیر را انجام دهید:

  1. برای جستجوی مستندات مربوط به ایجاد مخازن ذخیره‌سازی ابری، دستور زیر را اجرا کنید:

    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 را به همراه نام منبع سند اجرا کنید. به عنوان مثال، برای بازیابی سند در هنگام ایجاد مخازن ذخیره‌سازی ابری، مراحل زیر را انجام دهید:

  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 ).

قدم بعدی چیست؟