بدء الاستخدام السريع: استخدام gcloud CLI مع Developer Knowledge API

يوضّح لك هذا الدليل السريع كيفية الإجابة عن الاستعلامات والبحث عن مستندات المطوّرين واستردادها باستخدام Developer Knowledge API من خلال Google Cloud CLI.

قبل البدء

قبل البدء في استخدام Developer Knowledge API مع gcloud CLI، أكمِل الخطوات التالية.

تثبيت gcloud CLI وإعداده

لتثبيت gcloud CLI وضبط إعداداته، يُرجى اتّباع الخطوات التالية:

  1. إذا لم يسبق لك تثبيت gcloud CLI، عليك تثبيت gcloud CLI.

  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.

تفعيل واجهة برمجة التطبيقات

لتفعيل واجهة برمجة التطبيقات Developer Knowledge API، أكمِل الخطوات التالية:

  1. فعِّل Developer Knowledge API في مشروعك على Google Cloud من خلال تنفيذ الأمر gcloud services enable:

    gcloud services enable developerknowledge.googleapis.com

    لست بحاجة إلى أدوار معيّنة في "إدارة الهوية وإمكانية الوصول" (IAM) لتفعيل واجهة برمجة التطبيقات أو استخدامها.

  2. تأكَّد من تفعيل واجهة برمجة التطبيقات لمشروعك من خلال تنفيذ أمر gcloud services list:

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

    تعرض النتيجة اسم واجهة برمجة التطبيقات وعنوانها:

    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. يفحص هذا الأمر مجموعة مستندات API ويعرض أجزاء المحتوى المطابقة إلى جانب أسماء الموارد الخاصة بالمستندات الرئيسية.

للبحث عن أجزاء من المستند، أكمل الخطوات التالية:

  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)

الخطوات التالية