Этот документ предназначен для разработчиков, желающих создавать клиентские библиотеки, плагины для IDE и другие инструменты для взаимодействия с API Google. Служба обнаружения API Google позволяет делать всё вышеперечисленное, предоставляя машиночитаемые метаданные о других API Google через простой API. Данное руководство содержит обзор каждого раздела документа Discovery, а также полезные советы по его использованию.
Все вызовы API представляют собой неаутентифицированные запросы REST на основе JSON, использующие SSL, — другими словами, URL-адреса начинаются с https .
Формат документа Discovery
В этом разделе представлен обзор документа Discovery.
Во всех примерах ниже используется документ Discovery из API использования сервисов . Вы можете загрузить документ Discovery для API использования сервисов, выполнив следующий GET запрос:
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1
Формат документа Discovery включает информацию, которая относится к шести основным категориям:
- Базовое описание API.
- Информация об аутентификации для API.
- Подробная информация о ресурсах и схемах, описывающая данные API.
- Подробная информация о методах API .
- Информация о любых пользовательских функциях, поддерживаемых API.
- Встроенная документация , описывающая ключевые элементы API.
Каждый из этих разделов документа Discovery описан ниже.
Описание базового API
Документ Discovery содержит набор свойств, специфичных для API. Эти свойства не обязательно указаны в указанном порядке или в одном и том же разделе документа 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"
Эти свойства уровня API включают сведения о конкретной версии API, включая name , version , title и description . protocol всегда имеет фиксированное значение rest , поскольку служба обнаружения API поддерживает только RESTful-методы доступа к API.
Поле servicePath указывает префикс пути для данной конкретной версии API.
Аутентификация
Раздел auth содержит подробную информацию об областях авторизации OAuth 2.0 для API. Подробнее об использовании областей авторизации с OAuth 2.0 см. в статье «Использование OAuth 2.0 для доступа к API Google» .
Раздел 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. Чтобы узнать, как эти области действия связаны с методом API, обратитесь к разделу «Методы» ниже.
Ресурсы и схемы
Операции API работают с объектами данных, называемыми resources . Документ Discovery построен на концепции ресурсов. Каждый документ Discovery содержит раздел resources верхнего уровня, в котором сгруппированы все ресурсы, связанные с API. Например, API использования сервисов содержит ресурс services и ресурс operations в resources верхнего уровня:
"resources": { "services": { // Methods associated with the services resource } "operations": { // Methods associated with the operations resource } }
Внутри каждого раздела ресурсов находятся методы, связанные с этим ресурсом. Например, API использования сервисов содержит шесть методов, связанных с ресурсом services : get , enable , disable , batchGet , batchEnable и list .
Схемы отображают, как выглядят ресурсы в API. В каждом документе Discovery есть раздел schemas верхнего уровня, содержащий пару «имя/значение» идентификатора схемы для объекта. Идентификаторы схем уникальны для каждого API и используются для однозначной идентификации схемы в разделе 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 } }
Служба обнаружения API использует схему JSON Schema draft-03 для представления схемы. Ниже приведён фрагмент JSON Schema для ресурса EnableServiceResponse , а также служба GoogleApiServiceusagev1Service , на которую он ссылается. Наряду с этими схемами представлена часть фактического ответа на запрос на включение API Pub/Sub ( pubsub.googleapis.com ).
Схема JSON ресурса EnableServiceResponse : | Фактический ответ для включения услуги: |
"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" }, " | "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": {} }, " |
Поля, выделенные жирным шрифтом, показывают соответствие между схемой JSON и фактическим ответом.
Как показано в этом примере, схемы могут содержать ссылки на другие схемы. При создании клиентской библиотеки это может помочь вам эффективно моделировать объекты API в классах модели данных. В приведённом выше примере EnableServiceResponse свойство service — это ссылка на схему с идентификатором GoogleApiServiceusageV1Service , другую схему из документа Service Usage API Discovery. Вы можете заменить свойство GoogleApiServiceusageV1Service в ресурсе EnableServiceResponse значением схемы GoogleApiServiceusageV1Service (обратите внимание, что синтаксис $ref взят из спецификации JSON Schema ).
Методы также могут ссылаться на схемы при указании тел запросов и ответов. Подробнее см. в разделе «Методы» .
Методы
Основу документа Discovery составляют методы. Методы — это операции, которые можно выполнять с API. Раздел methods можно найти в различных разделах документа Discovery, в том числе на верхнем уровне (который мы называем методами уровня API) и на уровне resources .
"methods": { // API-level methods } "resources": { "resource1": { "methods": { // resource-level methods } "resources": { "nestedResource": { "methods": { // methods can even be found in nested-resources } } } } }
Хотя API может иметь методы уровня API, ресурс должен иметь раздел 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 , определённый ранее в этой документации, содержит информацию обо всех областях действия, поддерживаемых конкретным API. Если метод поддерживает одну из этих областей, у него будет массив scopes. В этом массиве есть одна запись для каждой области действия, поддерживаемой методом.
Обратите внимание, что выбор области действия аутентификации для использования в вашем приложении зависит от различных факторов, таких как вызываемые методы и параметры, передаваемые вместе с методом. Поэтому решение о выборе области действия остаётся за разработчиком. Discovery документирует только те области действия, которые допустимы для метода.
Запрос и ответ
Если метод содержит тело запроса или ответа, они документируются в разделах request или response соответственно. Например, для метода enable содержимое раздела request указывает, что запрос метода определён JSON-схемой с идентификатором EnableServiceRequest . Эту схему можно найти в разделе схем верхнего уровня.
Параметры
Если у метода есть параметры, которые должен указать пользователь, эти параметры документируются в разделе parameters на уровне метода. В этом разделе содержится сопоставление имени параметра по ключу и значению с более подробной информацией об этом параметре.
Например, для метода enable существует один параметр: name . Параметры могут указываться либо в path , либо в URL- query ; свойство location указывает, где клиентская библиотека должна разместить параметр.
Существует множество других свойств, описывающих параметр, включая type данных параметра (полезно для языков со строгой типизацией), required параметра и наличие перечисления. Подробнее об этих свойствах см. в справочной документации по этому API.
Порядок параметров
Клиентские библиотеки могут структурировать свои интерфейсы различными способами. Один из способов — создать метод с каждым параметром API в сигнатуре метода. Однако, поскольку 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 — это логическое значение, которое определяет, поддерживает ли метод загрузку медиафайлов. Если значение равно true, раздел mediaUpload содержит список типов медиафайлов, которые можно загрузить.
Свойство accept представляет собой список диапазонов медиафайлов , определяющих, какие MIME-типы допустимы для загрузки. Конечная точка, показанная в примере выше, принимает изображения любого формата.
Свойство maxSize определяет максимальный размер загружаемого файла. Значение — строка в единицах измерения: МБ, ГБ или ТБ. В приведённом выше примере максимальный размер загружаемого файла ограничен 10 МБ. Обратите внимание, что это значение не отражает оставшуюся квоту хранилища отдельного пользователя для данного API, поэтому даже если объём загружаемого файла меньше maxSize клиентская библиотека должна быть готова к обработке загружаемого файла, который может завершиться ошибкой из-за недостатка места.
В разделе protocols перечислены протоколы загрузки, поддерживаемые методом. simple протокол — это отправка медиа-данных в заданную конечную точку одним HTTP-запросом. resumable протокол подразумевает, что конечная точка, указанная в URI path , поддерживает протокол возобновляемой загрузки . Если свойство multipart равно true , то конечная точка принимает многокомпонентные загрузки, то есть и JSON-запрос, и медиа-данные можно объединить в тело mullipart/related и отправить вместе. Обратите внимание, что как simple , так и resumable протоколы могут поддерживать многокомпонентные загрузки.
Свойство path является шаблоном URI и должно быть расширено так же, как свойство path для метода, как описано в разделе Составление запроса .
Загрузка медиа
Если метод поддерживает загрузку мультимедиа, например изображений, аудио или видео, то это указывается параметром supportsMediaDownload :
"supportsMediaDownload": true,
При загрузке медиафайлов необходимо установить параметр запроса alt на media в URL-адресе запроса.
Если свойство useMediaDownloadService метода API имеет значение true , добавьте /download перед servicePath , чтобы избежать перенаправления. Например, путь загрузки будет /download/youtube/v3/captions/{id} если объединение servicePath и path — /youtube/v3/captions/{id} . Рекомендуется создавать URL для загрузки медиафайлов с помощью /download даже если useMediaDownloadService имеет значение false.
Общие параметры
Документ Discovery верхнего уровня содержит свойство parameters . Этот раздел аналогичен разделу параметров для каждого метода , однако эти параметры можно применить к любому методу в API.
Например, методы get и list API использования сервиса могут иметь параметр prettyPrint в параметрах запроса, который форматирует ответ для всех этих методов в удобном для восприятия формате. Вот список распространённых параметров:
| Параметр | Значение | Примечания | Применимость |
|---|---|---|---|
access_token | Токен OAuth 2.0 для текущего пользователя. |
| |
alt | Формат данных для ответа. |
|
|
callback | Функция обратного вызова. |
| |
fields | Селектор, указывающий подмножество полей для включения в ответ. |
| |
key | API-ключ. (ОБЯЗАТЕЛЬНО) |
| |
prettyPrint | Возвращает ответ с отступами и переносами строк. |
| |
quotaUser | Альтернатива userIp . |
| |
userIp | IP-адрес конечного пользователя, для которого выполняется вызов API. |
|
Встроенная документация
Каждый документ Discovery аннотирован рядом полей description , которые содержат встроенную документацию по API. Поля description доступны для следующих элементов API:
- API сам по себе
- Области OAuth
- Схемы ресурсов
- Методы API
- Параметры метода
- Допустимые значения для определенных параметров
Эти поля особенно полезны, если вы хотите использовать службу обнаружения API Google для создания удобочитаемой документации для клиентской библиотеки, например, JavaDoc.