Введение
Этот документ предназначен для разработчиков, которые хотят писать клиентские библиотеки, подключаемые модули IDE и другие инструменты для взаимодействия с API Google. Служба обнаружения API Google позволяет делать все вышеперечисленное, предоставляя машиночитаемые метаданные о других API Google через простой API. В этом руководстве представлен обзор каждого раздела документа Discovery, а также полезные советы по использованию документа.
Все вызовы API являются неаутентифицированными запросами REST на основе JSON, которые используют SSL, т. е. URL-адреса начинаются с https .
Если вы не знакомы с концепциями службы обнаружения API Google, вам следует прочитать Начало работы , прежде чем приступать к программированию.
Формат документа обнаружения
В этом разделе дается обзор документа Discovery.
Во всех приведенных ниже примерах используется документ Discovery из Google Cloud Service Management API . Вы можете загрузить документ обнаружения для Google Cloud Service Management API, выполнив этот GET :
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1Формат документа Discovery включает информацию, которая делится на шесть основных категорий:
- Базовое описание API.
- Информация об аутентификации для API.
- Сведения о ресурсах и схемах, описывающие данные API.
- Подробная информация о методах API .
- Информация о любых пользовательских функциях , поддерживаемых API.
- Встроенная документация , описывающая ключевые элементы API.
Каждый из этих разделов документа Discovery описан ниже. Обратитесь к справочной документации для получения более подробной информации о каждом свойстве.
Базовое описание API
Документ Discovery содержит набор специфичных для API свойств:
"kind": "discovery#restDescription", "name": "servicemanagement", "version": "v1", "title": "Service Management API", "description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.", "protocol": "rest", "rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live", "servicePath": "",
Эти свойства уровня 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.read-only": {
"description": "View your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management.readonly": {
"description": "View your Google API service configuration"
},
"https://www.googleapis.com/auth/cloud-platform": {
"description": "View and manage your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management": {
"description": "Manage your Google API service configuration"
}
}
}
}
Раздел auth определяет только области действия для конкретного API. Чтобы узнать, как эти области связаны с методом API, обратитесь к разделу « Методы » ниже.
Ресурсы и схемы
Операции API воздействуют на объекты данных, называемые resources . Документ Discovery построен вокруг концепции ресурсов. В каждом документе Discovery есть раздел resources верхнего уровня, в котором сгруппированы все ресурсы, связанные с API. Например, API управления облачными службами Google имеет ресурс services и ресурс operations в разделе ресурсов верхнего уровня, resources services имеет три configs : конфигурации, rollouts и consumers :
"resources": {
"services": {
// Methods and sub-resources associated with the services resource
"configs": {
// Methods and sub-resources associated with the services.configs resource
},
"rollouts": {
// Methods and sub-resources associated with the services.rollouts resource
},
"consumers": {
// Methods and sub-resources associated with the services.consumers resource
}
},
"operations": {
// Methods and sub-resources associated with the operations resource
}
}
Внутри каждого раздела ресурсов находятся методы, связанные с этим ресурсом. Например, Google Cloud Service Management API имеет три метода, связанных с ресурсом services.rollouts : get , list и create .
Схемы сообщают вам, как выглядят ресурсы в API. Каждый документ обнаружения имеет раздел schemas верхнего уровня, который содержит пару имя/значение идентификатора схемы для объекта. Идентификаторы схемы уникальны для каждого API и используются для уникальной идентификации схемы в разделе methods документа Discovery:
"schemas": {
"Rollout": {
// JSON Schema of the Rollout resource.
}
}
Служба обнаружения API использует черновик схемы JSON-03 для своих представлений схемы. Вот фрагмент схемы JSON для ресурса URL вместе с фактическим ресурсом ответа:
| Схема развертывания ресурса JSON: | Фактический ответ ресурса развертывания: |
{
"Rollout": {
"id": "Rollout",
"type": "object",
"description": "...",
"properties": {
"serviceName": {
"type": "string",
"description": "..."
},
"rolloutId": {
"type": "string",
"description": "..."
},
"status": {
"type": "string",
"enum": [
"ROLLOUT_STATUS_UNSPECIFIED",
"IN_PROGRESS",
"SUCCESS",
"CANCELLED",
"FAILED",
"PENDING",
"FAILED_ROLLED_BACK"
],
"enumDescriptions": [
...
],
"description": "..."
},
"trafficPercentStrategy": {
"$ref": "TrafficPercentStrategy",
"description": "..."
},
"deleteServiceStrategy": { ... },
"createTime": { ... },
"createdBy": { ... }
}
}
} | {
"serviceName": "discovery.googleapis.com",
"rolloutId": "2020-01-01R0",
"status": "SUCCESS",
"trafficPercentStrategy":{
"precentages":{
"2019-12-01R0": 70.00,
"2019-11-01R0": 30.00
}
}
} |
Поля, выделенные жирным шрифтом, показывают сопоставление между схемой JSON и фактическим ответом.
Схемы также могут содержать ссылки на другие схемы. Если вы создаете клиентскую библиотеку, это может помочь вам эффективно моделировать объекты API в ваших классах модели данных. В приведенном выше примере trafficPercentStrategy Rollout самом деле является ссылкой на схему с идентификатором TrafficPercentStrategy . Если вы посмотрите на раздел schemas , вы найдете схему TrafficPercentStrategy . Значением этой схемы можно заменить свойство trafficPercentStrategy в ресурсе Rollout (обратите внимание, что синтаксис $ref взят из спецификации схемы JSON ).
Методы также могут ссылаться на схемы при указании тела запроса и ответа. Обратитесь к разделу « Методы » для более подробной информации.
Методы
Ядро документа 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 , list и create :
"methods": {
"get": { //details about the "get" method },
"list": { //details about the "list" method },
"create": { //details about the "create" method }
}
Наконец, в разделе каждого метода подробно описаны различные свойства этого метода. Вот пример метода get :
"get": {
"id": "servicemanagement.services.rollouts.get",
"path": "v1/services/{serviceName}/rollouts/{rolloutId}",
"flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
"httpMethod": "GET",
"description": "Gets a service configuration rollout.",
"response": { "$ref": "Rollout" },
"parameters": { // parameters related to the method },
"parameterOrder": [ // parameter order related to the method ],
"scopes": [ // OAuth 2.0 scopes applicable to this method ],
"mediaUpload": { // optional media upload information },
},
Этот раздел содержит общие сведения о методе, такие как уникальный ID для идентификации метода, используемый httpMethod и path к методу (подробные сведения о том, как использовать свойство path для вычисления полного URL-адреса метода, см. в разделе Составление запроса ). ). В дополнение к этим общим свойствам метода есть несколько свойств, которые связывают метод с другими разделами документа Discovery:
Сферы
Раздел auth , определенный ранее в этой документации, содержит информацию обо всех областях, поддерживаемых конкретным API. Если метод поддерживает одну из этих областей, он будет иметь массив областей. В этом массиве есть одна запись для каждой области, поддерживаемой методом. Например, раздел scopes действия метода get Google Cloud Service Management API выглядит следующим образом:
"scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/cloud-platform.read-only", "https://www.googleapis.com/auth/service.management", "https://www.googleapis.com/auth/service.management.readonly" ]
Обратите внимание, что выбор области проверки подлинности для использования в вашем приложении зависит от различных факторов, например от того, какие методы вызываются и какие параметры отправляются вместе с методом. Поэтому решение о том, какую область использовать, остается за разработчиком. Обнаружение только документирует, какие области допустимы для метода.
Запрос и ответ
Если у метода есть тело запроса или ответа, они задокументированы в разделах request или response соответственно. В приведенном get примере метод имеет тело response :
"response": {
"$ref": "Rollout"
} Приведенный выше синтаксис указывает, что тело ответа определяется схемой JSON с идентификатором Rollout . Эту схему можно найти в разделе схем верхнего уровня. И запрос, и тело ответа используют синтаксис $ref для ссылки на схемы.
Параметры
Если у метода есть параметры, которые должны быть указаны пользователем, эти параметры задокументированы в разделе parameters уровня метода. Этот раздел содержит сопоставление ключа/значения имени параметра с более подробной информацией об этом параметре:
"parameters": {
"serviceName": {
"type": "string",
"description": "Required. The name of the service.",
"required": true,
"location": "path"
},
"rolloutId": { ... }
},
"parameterOrder": [
"serviceName",
"rolloutId"
]
В приведенном выше примере у метода get есть два параметра: serviceName и rolloutId . Параметры могут быть либо в path , либо в URL- query ; свойство location указывает, куда клиентская библиотека должна поместить параметр.
Есть много других свойств, описывающих параметр, включая type данных параметра (полезно для строго типизированных языков), является ли параметр required и является ли параметр перечислением. Обратитесь к Справочному руководству для получения более подробной информации о свойствах.
Порядок параметров
Для клиентских библиотек существует множество способов структурировать свои интерфейсы. Один из способов — иметь метод с каждым параметром API в сигнатуре метода. Однако, поскольку JSON является неупорядоченным форматом, программно сложно понять, как упорядочить параметры в сигнатуре метода. Массив parameterOrder обеспечивает фиксированный порядок параметров для выполнения запросов. В массиве перечислены имена каждого параметра в порядке значимости; он может содержать параметры пути или запроса, но каждый параметр в массиве является обязательным. В приведенном выше примере сигнатура метода Java может выглядеть примерно так:
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters); Первое значение в массиве parameterOrder , serviceName , также является первым элементом в сигнатуре метода. Если бы в массиве parameterOrder были другие параметры, они шли бы после параметра serviceName . Поскольку массив parameterOrder содержит только обязательные параметры, рекомендуется включить для пользователей способ указания необязательных параметров. В приведенном выше примере это делается с помощью карты optionalParameters .
Загрузка медиа
Если метод поддерживает загрузку мультимедиа, например изображений, аудио или видео, то местоположение и протоколы, поддерживаемые для загрузки этого мультимедиа, задокументированы в разделе 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, и медиаданные могут быть заключены вместе в составное/связанное тело и отправлены вместе. Обратите внимание, что как 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.
Общие параметры
Документ обнаружения верхнего уровня содержит свойство parameters . Этот раздел аналогичен разделу параметров для каждого метода , однако эти параметры можно применить к любому методу в API.
Например, методы get, insert или list API управления облачными службами Google могут иметь параметр prettyPrint в параметрах запроса, который будет форматировать ответ для всех этих методов в удобочитаемом формате. Вот список общих параметров:
| Параметр | Значение | Заметки | Применимость |
|---|---|---|---|
access_token | Токен OAuth 2.0 для текущего пользователя. |
| |
alt | Формат данных для ответа. |
|
|
callback | Функция обратного вызова. |
| |
fields | Селектор, указывающий подмножество полей для включения в ответ. |
| |
key | API-ключ. (ТРЕБУЕТСЯ*) |
| |
prettyPrint | Возвращает ответ с идентификаторами и разрывами строк. |
| |
quotaUser | Альтернатива userIp . |
| |
userIp | IP-адрес конечного пользователя, для которого выполняется вызов API. |
|
Функции
В некоторых случаях API поддерживают пользовательские функции, выходящие за рамки остальной части документа Discovery. Они собраны в массиве features . Массив функций содержит строковую метку для каждой специальной функции, поддерживаемой API. В настоящее время dataWrapper является единственной поддерживаемой функцией, но в будущем могут поддерживаться и другие функции.
"features": dataWrapper
Функция dataWrapper указывает, что все запросы к API и ответы от API упаковываются в объект data JSON. Это функция старых API Google, но в дальнейшем она устаревает. Следующие API поддерживают функцию dataWrapper : Moderator v1 и Translate v2 .
Как разработчик клиентской библиотеки, если API поддерживает функцию «dataWrapper», вы должны сделать следующее:
- По запросам: оберните ресурс запроса в объект
dataJSON. - Об ответах: найдите ресурс внутри объекта
dataJSON.
Схемы в документе Discovery не содержат оболочку данных, поэтому вы должны явно добавлять и удалять их. Например, предположим, что есть API с ресурсом с именем «Foo», который выглядит так:
{
"id": 1,
"foo": "bar"
}Прежде чем вставить этот ресурс с помощью API, вам нужно обернуть его в элемент данных:
{
"data": {
"id": 1,
"foo": "bar"
}
}С другой стороны, когда вы получаете ответ от API, он также содержит оболочку данных:
{
"data": {
"id": 1,
"foo": "bar"
}
}Чтобы получить ресурс, определенный схемой, вам нужно удалить оболочку данных:
{
"id": 1,
"foo": "bar"
}Встроенная документация
Каждый документ Discovery аннотирован рядом полей description , которые предоставляют встроенную документацию для API. Поля description можно найти для следующих элементов API:
- сам API
- Область действия OAuth
- Схемы ресурсов
- Методы API
- Параметры метода
- Допустимые значения некоторых параметров
Эти поля особенно полезны, если вы хотите использовать службу обнаружения API Google для создания удобочитаемой документации для клиентской библиотеки, например JavaDoc.