تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

استخدام Discovery API

هذا المستند مخصّص للمطوّرين الذين يريدون كتابة مكتبات برامج وأدوات إضافية لبيئات التطوير المتكاملة (IDE) وأدوات أخرى للتفاعل مع واجهات Google API. تتيح لك خدمة Google APIs Discovery Service تنفيذ كل ما سبق من خلال عرض بيانات وصفية قابلة للقراءة آليًا حول واجهات Google APIs الأخرى من خلال واجهة برمجة تطبيقات بسيطة. يقدّم هذا الدليل نظرة عامة على كل قسم من مستند Discovery، بالإضافة إلى نصائح مفيدة حول كيفية استخدام المستند.

جميع الطلبات الموجّهة إلى واجهة برمجة التطبيقات هي طلبات REST غير مصادَق عليها تستند إلى JSON وتستخدم طبقة المقابس الآمنة (SSL)، أي أنّ عناوين URL تبدأ بـ https.

تنسيق مستند الاكتشاف

يقدّم هذا القسم نظرة عامة على مستند Discovery.

تستخدم جميع الأمثلة أدناه مستند الاكتشاف من Service Usage API. يمكنك تحميل المستند المرتبط بميزة "اقتراحات" لواجهة Service Usage API من خلال تنفيذ طلب GET التالي:

GET https://serviceusage.googleapis.com/$discovery/rest?version=v1

يتضمّن تنسيق مستند Discovery معلومات تندرج ضمن ست فئات رئيسية:

وصف أساسي لواجهة برمجة التطبيقات
معلومات المصادقة الخاصة بواجهة برمجة التطبيقات
تفاصيل الموارد والمخططات التي تصف بيانات واجهة برمجة التطبيقات
تفاصيل حول طُرق واجهة برمجة التطبيقات
معلومات عن أي ميزات مخصّصة تتوافق مع واجهة برمجة التطبيقات
مستندات مضمّنة تصف العناصر الرئيسية في واجهة برمجة التطبيقات

يتم توضيح كل قسم من أقسام مستند Discovery أدناه.

وصف واجهة برمجة التطبيقات الأساسية

يحتوي مستند Discovery على مجموعة من الخصائص الخاصة بواجهة برمجة التطبيقات. لا تظهر هذه الخصائص بالضرورة بهذا الترتيب أو في القسم نفسه من مستند الاكتشاف:

"id": "serviceusage:v1",
"canonicalName": "Service Usage",
"revision": "20240331",
"servicePath": "",
"baseUrl": "https://serviceusage.googleapis.com/",
"kind": "discovery#restDescription",
"description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.",
"ownerDomain": "google.com",
"version_module": true,
"version": "v1",
"fullyEncodeReservedExpansion": true,
"name": "serviceusage",
"title": "Service Usage API",
"discoveryVersion": "v1",
"rootUrl": "https://serviceusage.googleapis.com/",
"protocol": "rest"

تتضمّن خصائص مستوى واجهة برمجة التطبيقات تفاصيل حول إصدار معيّن من واجهة برمجة التطبيقات، بما في ذلك name وversion وtitle وdescription. تحتوي السمة protocol دائمًا على القيمة الثابتة rest، لأنّ خدمة Discovery Service لواجهات برمجة التطبيقات لا تتيح سوى طرق RESTful للوصول إلى واجهات برمجة التطبيقات.

يشير الحقل servicePath إلى بادئة المسار الخاصة بإصدار واجهة برمجة التطبيقات هذا.

المصادقة

يحتوي القسم auth على تفاصيل حول نطاقات تفويض OAuth 2.0 لواجهة برمجة التطبيقات. لمزيد من المعلومات حول كيفية استخدام النطاقات مع OAuth 2.0، يُرجى الانتقال إلى مقالة استخدام بروتوكول OAuth 2.0 للدخول إلى Google APIs.

يحتوي القسم auth على القسمَين المدمجَين oauth2 وscopes. يمثّل القسم scopes عملية ربط مفتاح/قيمة من قيمة النطاق إلى المزيد من التفاصيل حول النطاق:

"auth": {
  "oauth2": {
    "scopes": {
      "https://www.googleapis.com/auth/cloud-platform": {
        "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account."
      },
      "https://www.googleapis.com/auth/cloud-platform.read-only": {
        "description": "View your data across Google Cloud services and see the email address of your Google Account"
      },
      "https://www.googleapis.com/auth/service.management": {
        "description": "Manage your Google API service configuration"
      }
    }
  }
}

لا يحدّد القسم auth سوى نطاقات واجهة برمجة تطبيقات معيّنة. للتعرّف على كيفية ربط هذه النطاقات بطريقة API، راجِع قسم الطُرق أدناه.

المراجع والمخططات

تتفاعل عمليات واجهة برمجة التطبيقات مع عناصر البيانات التي تُسمى resources. يتم إنشاء مستند Discovery استنادًا إلى مفهوم الموارد. يحتوي كل مستند Discovery على قسم resources في المستوى الأعلى يجمع كل الموارد المرتبطة بواجهة برمجة التطبيقات. على سبيل المثال، تتضمّن Service Usage API المورد services والمورد operations ضمن المستوى الأعلى resources:

"resources": {
  "services": {
    // Methods associated with the services resource
  }
  "operations": {
    // Methods associated with the operations resource
  }
}

داخل كل قسم من أقسام الموارد، ستجد الطرق المرتبطة بهذا المورد. على سبيل المثال، تتضمّن واجهة برمجة التطبيقات Service Usage API ست طرق مرتبطة بمورد services: get وenable وdisable وbatchGet وbatchEnable وlist.

توضّح لك المخططات شكل الموارد في واجهة برمجة التطبيقات. يحتوي كل مستند Discovery على قسم schemas من المستوى الأعلى، ويتضمّن زوجًا من الاسم والقيمة لمعرّف المخطط إلى العنصر. تكون أرقام تعريف المخطط فريدة لكل واجهة برمجة تطبيقات، ويتم استخدامها لتحديد المخطط بشكل فريد في القسم methods من مستند Discovery. على سبيل المثال، في ما يلي بعض المخططات في مستند Service Usage API Discovery:

"schemas": {
  "Method": {
    // JSON schema of the Method resource
  },
  "Authentication": {
    // JSON schema of the Authentication resource
  },
  "RubySettings": {
    // JSON schema of the RubySettings resource
  },
  "EnableServiceResponse": {
   // JSON schema of the EnableServiceResponse resource
  }
}

تستخدِم خدمة APIs Discovery Service المسودة 03 من مخطط JSON لتمثيلات المخطط. في ما يلي مقتطف من مخطط JSON لمورد EnableServiceResponse، بالإضافة إلى GoogleApiServiceusagev1Service الذي يشير إليه. إلى جانب هذه المخططات، يتوفّر جزء من ردّ فعلي على طلب تفعيل واجهة برمجة تطبيقات Pub/Sub‏ (pubsub.googleapis.com).

EnableServiceResponse مخطط JSON الخاص بالمرجع: الرد الفعلي لتفعيل إحدى الخدمات:

"EnableServiceResponse": {
  "id": "EnableServiceResponse",
  "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.",
  "properties": {
    "service": {
      "description": "The new state of the service after enabling.",
      "$ref": "GoogleApiServiceusageV1Service"
    }
  },
  "type": "object"
},
"GoogleApiServiceusageV1Service": {
  "description": "A service that is available for use by the consumer.",
  "properties": {
    "config": {
      "$ref": "GoogleApiServiceusageV1ServiceConfig",
      "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method."
    },
    "name": {
      "type": "string",
      "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com"
    },
    "state": {
      "enumDescriptions": [
        "The default value, which indicates that the enabled state of the service is unspecified or not meaningful. Currently, all consumers other than projects (such as folders and organizations) are always in this state.",
        "The service cannot be used by this consumer. It has either been explicitly disabled, or has never been enabled.",
        "The service has been explicitly enabled for use by this consumer."
      ],
      "description": "Whether or not the service has been enabled for use by the consumer.",
      "type": "string",
      "enum": [
        "STATE_UNSPECIFIED",
        "DISABLED",
        "ENABLED"
      ]
    },
    "parent": {
      "type": "string",
      "description": "The resource name of the consumer. A valid name would be: - projects/123"
    }
  },
  "id": "GoogleApiServiceusageV1Service",
  "type": "object"
}

"response": {
  "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse",
  "service": {
    "name": "projects/232342569935/services/pubsub.googleapis.com",
    "config": {
      "name": "pubsub.googleapis.com",
      "title": "Cloud Pub/Sub API",
      "documentation": {
        "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n"
      },
      "quota": {},
      "authentication": {},
      "usage": {
        "requirements": [
          "serviceusage.googleapis.com/tos/cloud"
        ]
      },
      "monitoring": {}
    },
    "state": "ENABLED",
    "parent": "projects/232342569935"
  }
}

تعرض الحقول بالخط العريض عملية الربط بين مخطّط JSON والاستجابة الفعلية.

كما هو موضّح في هذا المثال، يمكن أن تحتوي المخططات على مراجع لمخططات أخرى. إذا كنت بصدد إنشاء مكتبة برامج للعميل، يمكن أن يساعدك ذلك في تصميم عناصر واجهة برمجة التطبيقات بشكل فعّال في فئات نموذج البيانات. في مثال EnableServiceResponse أعلاه، تشير السمة service إلى مخطط يحمل المعرّف GoogleApiServiceusageV1Service، وهو مخطط آخر في مستند Service Usage API Discovery. يمكنك استبدال السمة GoogleApiServiceusageV1Service في مرجع EnableServiceResponse بقيمة مخطط GoogleApiServiceusageV1Service (يُرجى العِلم أنّ بنية $ref مستمدة من مواصفات مخطط JSON).

قد تشير الطرق أيضًا إلى المخططات عند تحديد نص الطلب والرد. يُرجى الرجوع إلى قسم الطُرق لمزيد من التفاصيل.

الطُرق

يتم إنشاء أساس مستند Discovery حول الطرق. الطُرق هي العمليات التي يمكن تنفيذها على واجهة برمجة التطبيقات. يمكنك العثور على القسم methods في مناطق مختلفة من مستند Discovery، بما في ذلك في المستوى الأعلى (الذي نسمّيه طرق على مستوى واجهة برمجة التطبيقات) أو في المستوى resources.

"methods": {
  // API-level methods
}
"resources": {
  "resource1": {
    "methods": {
      // resource-level methods
    }
    "resources": {
      "nestedResource": {
        "methods": {
          // methods can even be found in nested-resources
        }
      }
    }
  }
}

على الرغم من أنّ واجهة برمجة التطبيقات يمكنها أن تتضمّن طرقًا على مستوى واجهة برمجة التطبيقات، يجب أن يتضمّن المرجع قسم methods.

كل قسم methods هو خريطة مفتاح-قيمة من اسم الطريقة إلى تفاصيل أخرى حول هذه الطريقة. يوضّح المثال أدناه ثلاث طرق، وهي get وenable وdisable:

"methods": {
  "get": { //details about the "get" method },
  "enable": { //details about the "enable" method },
  "disable": { //details about the "disable" method }
}

أخيرًا، يوضّح قسم كل طريقة خصائص مختلفة حول هذه الطريقة. في ما يلي مثال على طريقة enable:

"enable": {
  "path": "v1/{+name}:enable",
  "request": {
    "$ref": "EnableServiceRequest"
  },
  "parameterOrder": [
    "name"
  ],
  "id": "serviceusage.services.enable",
  "response": {
    "$ref": "Operation"
  },
  "description": "Enable a service so that it can be used with a project.",
  "httpMethod": "POST",
  "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable",
  "scopes": [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/service.management"
  ],
  "parameters": {
    "name": {
      "location": "path",
      "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.",
      "required": true,
      "type": "string",
      "pattern": "^[^/]+/[^/]+/services/[^/]+$"
    }
  }
},

يحتوي هذا القسم على تفاصيل عامة حول الطريقة، مثل ID فريد لتحديد الطريقة، وhttpMethod المطلوب استخدامه، وpath الخاص بالطريقة (للحصول على تفاصيل حول كيفية استخدام السمة path لاحتساب عنوان URL الكامل للطريقة، راجِع القسم إنشاء طلب). بالإضافة إلى خصائص الطريقة العامة هذه، هناك بعض الخصائص التي تربط الطريقة بأقسام أخرى في مستند Discovery:

المستويات

يحتوي القسم auth المحدّد سابقًا في هذه المستندات على معلومات حول جميع النطاقات التي تتيحها واجهة برمجة تطبيقات معيّنة. إذا كانت إحدى الطرق تتوافق مع أحد هذه النطاقات، ستحتوي على مصفوفة نطاقات. يحتوي هذا الصفيف على إدخال واحد لكل نطاق متوافق مع الطريقة.

يُرجى العِلم أنّ اختيار نطاق تفويض لاستخدامه في تطبيقك يعتمد على عوامل مختلفة، مثل الطرق التي يتم استدعاؤها والمعلَمات التي يتم إرسالها مع الطريقة. لذلك، يعود للمطوّر تحديد النطاق الذي يريد استخدامه. تعرض هذه السمة المستندات التي تتضمّن نطاقات صالحة لطريقة معيّنة.

الطلب والاستجابة

إذا كانت الطريقة تتضمّن نص طلب أو استجابة، يتم توثيق ذلك في القسم request أو القسم response على التوالي. على سبيل المثال، بالنسبة إلى طريقة enable، يشير محتوى القسم request إلى أنّ طلب الطريقة محدّد بواسطة مخطط JSON يتضمّن المعرّف EnableServiceRequest. ويمكن العثور على هذا المخطط في قسم المخططات ذات المستوى الأعلى.

المعلمات

إذا كانت إحدى الطرق تتضمّن مَعلمات يجب أن يحدّدها المستخدم، يتم توثيق هذه المَعلمات في القسم parameters على مستوى الطريقة. يحتوي هذا القسم على عملية ربط بين المفتاح والقيمة لاسم المَعلمة والمزيد من التفاصيل حول هذه المَعلمة.

على سبيل المثال، هناك مَعلمة واحدة للطريقة enable: name. يمكن وضع المَعلمات في path أو في عنوان URL query، وتشير السمة location إلى المكان الذي يجب أن تضع فيه مكتبة العميل المَعلمة.

هناك العديد من السمات الأخرى التي تصف المَعلمة، بما في ذلك بيانات المَعلمة type (مفيدة للغات ذات الكتابة القوية)، وما إذا كانت المَعلمة required، وما إذا كانت المَعلمة عبارة عن تعداد. يمكنك الاطّلاع على المستندات المرجعية الخاصة بواجهة برمجة التطبيقات هذه للحصول على مزيد من التفاصيل حول هذه الخصائص.

ترتيب المَعلمات

تتوفّر العديد من الطرق التي يمكن لمكتبات البرامج الخاصة بالعملاء اتّباعها لتنظيم واجهاتها. إحدى الطرق هي توفير طريقة تتضمّن كل مَعلمة من معلمات واجهة برمجة التطبيقات في توقيع الطريقة. ومع ذلك، بما أنّ JSON هو تنسيق غير مرتّب، يصعب معرفة كيفية ترتيب المَعلمات في توقيع الطريقة آليًا. تقدّم مصفوفة parameterOrder ترتيبًا ثابتًا للمعلمات عند تقديم الطلبات. تسرد المصفوفة اسم كل مَعلمة حسب ترتيب أهميتها، ويمكن أن تحتوي على مَعلمات مسار أو طلب بحث، ولكن يجب توفّر كل مَعلمة في المصفوفة.

تحميل الوسائط

إذا كانت إحدى الطرق تتيح تحميل الوسائط، مثل الصور أو الصوت أو الفيديو، سيتم توثيق الموقع الجغرافي والبروتوكولات المتوافقة مع تحميل هذه الوسائط في القسم mediaUpload. يحتوي هذا القسم على تفاصيل حول بروتوكولات التحميل المتوافقة، ومعلومات حول أنواع الوسائط التي يمكن تحميلها.

لا تحتوي طريقة enable على قسم mediaUpload. ومع ذلك، قد يبدو قسم mediaUpload نموذجيًا على النحو التالي:

"supportsMediaUpload": true,
"mediaUpload": {
  "accept": [
    "image/*"
  ],
  "maxSize": "10MB",
  "protocols": {
    "simple": {
      "multipart": true,
      "path": "/upload/storage/v1beta1/b/{bucket}/o"
    },
    "resumable": {
      "multipart": true,
      "path": "/resumable/upload/storage/v1beta1/b/{bucket}/o"
    }
  }
}

في المثال أعلاه، السمة supportsMediaUpload هي قيمة منطقية تحدّد ما إذا كانت الطريقة تتيح تحميل الوسائط. إذا كانت القيمة صحيحة، يوضّح القسم mediaUpload أنواع الوسائط التي يمكن تحميلها.

السمة accept هي قائمة بنطاقات وسائط تحدّد أنواع MIME المقبولة للتحميل. ستقبل نقطة النهاية الموضّحة في المثال أعلاه أي تنسيق صورة.

تمثّل السمة maxSize الحدّ الأقصى لحجم عملية التحميل. القيمة هي سلسلة بوحدات ميغابايت أو غيغابايت أو تيرابايت. في المثال أعلاه، يقتصر حجم عمليات التحميل على 10 ميغابايت كحدّ أقصى. يُرجى العِلم أنّ هذه القيمة لا تعكس حصة التخزين المتبقية لمستخدم فردي في واجهة برمجة التطبيقات هذه، لذا حتى إذا كان حجم التحميل أقل من maxSize، يجب أن تكون مكتبة البرامج جاهزة للتعامل مع عملية تحميل يتعذّر إجراؤها بسبب عدم توفّر مساحة كافية.

يسرد القسم protocols بروتوكولات التحميل التي تتيحها إحدى الطرق. بروتوكول simple هو ببساطة عملية نشر الوسائط إلى نقطة النهاية المحدّدة في طلب HTTP واحد. يشير البروتوكول resumable إلى أنّ نقطة النهاية المحدّدة في معرّف الموارد المنتظم path تتوافق مع بروتوكول التحميل القابل للاستئناف. إذا كانت قيمة السمة multipart هي true، يعني ذلك أنّ نقطة النهاية تقبل عمليات تحميل متعددة الأجزاء، ما يعني أنّه يمكن تضمين كلّ من طلب JSON والوسائط معًا في نص mutlipart/related وإرسالهما معًا. يُرجى العِلم أنّ البروتوكولَين simple وresumable قد يتيحان عمليات التحميل المتعددة الأجزاء.

السمة path هي نموذج URI ويجب توسيعها تمامًا مثل السمة path الخاصة بالطريقة، كما هو موضّح في القسم إنشاء طلب.

تنزيل الوسائط

إذا كانت إحدى الطرق تتيح تنزيل الوسائط، مثل الصور أو المحتوى الصوتي أو الفيديو، يتم توضيح ذلك من خلال المَعلمة supportsMediaDownload:

"supportsMediaDownload": true,

عند تنزيل الوسائط، يجب ضبط مَعلمة طلب البحث alt على media في عنوان URL للطلب.

إذا كانت قيمة السمة useMediaDownloadService لطريقة واجهة برمجة التطبيقات هي true، أدرِج /download قبل servicePath لتجنُّب إعادة التوجيه. على سبيل المثال، مسار التنزيل هو /download/youtube/v3/captions/{id} إذا كان تسلسل servicePath وpath هو /youtube/v3/captions/{id}. يُنصح بإنشاء عنوان URL لتنزيل الوسائط باستخدام /download حتى عندما تكون قيمة useMediaDownloadService هي "خطأ".

ملاحظة: يُسمح لطريقة واحدة من طرق واجهة برمجة التطبيقات بتوفير إمكانية تنزيل الوسائط وتحميلها. تعمل منطق إنشاء عناوين URL الخاصة بطلبات تحميل الوسائط وتنزيلها بشكل مستقل، ولا يتداخل بعضها مع بعض. نتيجةً لذلك، سيكون لطريقة واجهة برمجة التطبيقات هذه عنوان URL واحد /download/... لتنزيل الوسائط وعنوان URL واحد /upload/... لتحميل الوسائط. ومع ذلك، لا يمكن تحميل الوسائط وتنزيلها في طلب واحد.

المَعلمات الشائعة

يحتوي مستند Discovery ذو المستوى الأعلى على السمة parameters. يشبه هذا القسم قسم المَعلمات لكل طريقة، ولكن يمكن تطبيق هذه المَعلمات على أي طريقة في واجهة برمجة التطبيقات.

على سبيل المثال، يمكن أن تتضمّن الطريقتان get وlist في Service Usage API المعلّمة prettyPrint في مَعلمات الطلب، ما يؤدي إلى تنسيق الاستجابة لجميع هذه الطرق بتنسيق يمكن للمستخدمين قراءته. في ما يلي قائمة بالمعلَمات الشائعة:

المَعلمة	المعنى	ملاحظات	قابلية التطبيق
`access_token`	الرمز المميز من الإصدار 2.0 من OAuth للمستخدم الحالي	إحدى الطرق الممكنة لتوفير رمز مميز لبروتوكول OAuth 2.0.
`alt`	تنسيق البيانات للردّ	القيم الصالحة: `json` و`atom` و`csv` القيمة التلقائية: تختلف حسب واجهة برمجة التطبيقات. لا تتوفّر بعض القيم لكل واجهة برمجة تطبيقات.	ينطبق ذلك على جميع العمليات لجميع الموارد.
`callback`	دالّة رد الاتصال	اسم دالة ردّ الاتصال JavaScript التي تعالج الردّ. يُستخدم في طلبات JSON-P في JavaScript.
`fields`	محدّد يحدّد مجموعة فرعية من الحقول المطلوب تضمينها في الاستجابة.	يجب استخدامها لتحسين الأداء.
`key`	مفتاح واجهة برمجة التطبيقات (مطلوب)	هذه السمة مطلوبة ما لم تقدّم رمز OAuth 2.0 المميز. يحدّد مفتاح واجهة برمجة التطبيقات مشروعك ويوفّر لك إمكانية الوصول إلى واجهة برمجة التطبيقات والحصة والتقارير. احصل على مفتاح واجهة برمجة التطبيقات الخاص بمشروعك من وحدة تحكّم واجهات برمجة التطبيقات.
`prettyPrint`	تعرض هذه السمة الرد مع مسافات بادئة وفواصل أسطر.	تعرض هذه السمة الرد بتنسيق يمكن للمستخدم قراءته إذا كانت القيمة `true`. القيمة التلقائية: تختلف حسب واجهة برمجة التطبيقات. عندما تكون القيمة `false`، يمكن أن يؤدي ذلك إلى تقليل حجم حمولة الرد، ما قد يؤدي إلى تحسين الأداء في بعض البيئات.
`quotaUser`	بديل لـ "`userIp`"	تتيح لك فرض حصص لكل مستخدم من تطبيق من جهة الخادم حتى في الحالات التي يكون فيها عنوان IP الخاص بالمستخدم غير معروف. يمكن أن يحدث ذلك، على سبيل المثال، مع التطبيقات التي تنفّذ مهام cron على App Engine نيابةً عن المستخدم. يمكنك اختيار أي سلسلة عشوائية تحدّد المستخدم بشكل فريد، ولكن يجب ألا تتجاوز 40 حرفًا. يتم تجاهل `userIp` إذا تم توفير كليهما. مزيد من المعلومات حول تحديد سقف للاستخدام
`userIp`	عنوان IP للمستخدم النهائي الذي يتم إجراء طلب البيانات من واجهة برمجة التطبيقات له	تتيح لك فرض حصص لكل مستخدم عند استدعاء واجهة برمجة التطبيقات من تطبيق من جهة الخادم. مزيد من المعلومات حول تحديد سقف للاستخدام

المستندات المضمّنة

يتم إرفاق كل مستند Discovery بعدد من description الحقول التي توفّر مستندات مضمّنة لواجهة برمجة التطبيقات. يمكن العثور على حقول description لعناصر واجهة برمجة التطبيقات التالية:

واجهة برمجة التطبيقات نفسها
نطاقات OAuth
مخططات الموارد
طُرق واجهة برمجة التطبيقات
مَعلمات الطريقة
القيم المقبولة لبعض المَعلمات

تكون هذه الحقول مفيدة بشكل خاص إذا كنت تريد استخدام خدمة Google APIs Discovery Service لإنشاء مستندات قابلة للقراءة من قِبل الإنسان لمكتبة برامج، مثل JavaDoc.

استخدام Discovery API تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.