Discovery API предоставляет список API Google для получения машиночитаемых метаданных «Документ обнаружения» для каждого API.
Этот документ предназначен для разработчиков, которые хотят писать клиентские библиотеки, подключаемые модули IDE и другие инструменты для взаимодействия с API Google.
История службы обнаружения
Концепции
Служба обнаружения API Google основана на двух основных принципах:
- Каталог API : список всех API, поддерживаемых службой обнаружения API. Каждая запись каталога показывает сведения о поддерживаемом API, включая его имя , краткое описание того, что он делает, и ссылку на документацию . API может иметь несколько записей в каталоге, по одной для каждой поддерживаемой версии.
- Документ обнаружения : машиночитаемое описание конкретного API. Документ Discovery описывает поверхность для конкретной версии API. В документе подробно описано, как получить доступ к различным методам каждого API через HTTP-вызовы RESTful. Документ Discovery включает описания данных и методов, связанных с API, а также информацию о доступных областях действия OAuth, а также описания схем, методов, параметров и доступных значений параметров.
Модель данных
Ресурс — это отдельный объект данных с уникальным идентификатором. Служба обнаружения API Google работает с двумя типами ресурсов, основанными на вышеуказанных концепциях.
Список каталогов API : список API.
Каждая запись каталога содержит пару имя / версия API со следующей информацией:
- Идентификационная и описательная информация : имя, версия, заголовок и описание.
- Информация о документации : значки и ссылка на документацию.
- Информация о состоянии , включая метки состояния и указание на то, является ли эта версия предпочтительной версией API.
- Ссылка на документ обнаружения , URI документа обнаружения для этого API (указанный как полный URL-адрес, например https://servicemanagement.googleapis.com/$discovery/rest?version=v1).
Ресурс Discovery Document : машиночитаемое описание конкретного API.
В дополнение к информации, представленной в каталоге API, документ Discovery также включает:
- Schemas — список схем ресурсов API, описывающих данные, к которым у вас есть доступ в каждом API; схемы службы обнаружения API Google основаны на схеме JSON .
- Methods , включая список методов API и доступных параметров для каждого метода.
- Области OAuth , определяющие список областей действия OAuth, доступных для этого API.
- Встроенная документация , содержащая краткие описания схем, методов, параметров и доступных значений параметров.
Единая коллекция каталогов — это концептуальный контейнер ресурса единого каталога API и ресурсов документа обнаружения для каждого поддерживаемого API.
Дополнительные сведения о ресурсе каталога API и ресурсе документа обнаружения приведены в документах « Использование API» и « Справочник ».
Операции
Вы можете вызывать два разных метода для коллекций и ресурсов в службе обнаружения API Google, как описано в следующей таблице.
| Операция | Описание | HTTP-сопоставления REST |
|---|---|---|
| список | Список всех поддерживаемых API. | GET для URI ресурса каталога. |
Стиль вызова
ОТДЫХАТЬ
Поддерживаемые операции Google APIs Discovery Service сопоставляются непосредственно с командой REST HTTP GET , как описано в разделе Операции .
Конкретный формат для URI службы обнаружения API Google:
https://discovery.googleapis.com/discovery/v1/apis?parameters
где api — это идентификатор ресурса Discovery Document, а version — идентификатор конкретной версии API, а _parameters_ — любые параметры, применяемые к запросу. Дополнительные сведения см. в сводке параметров запроса в справочной документации.
Подробная информация о полном наборе URI, используемых для каждой поддерживаемой операции в API, представлена в справочном документе Google APIs Discovery Service .
Вот несколько примеров того, как это работает в службе обнаружения API Google.
Перечислите все API, поддерживаемые службой обнаружения API Google:
GET https://discovery.googleapis.com/discovery/v1/apis
Попробуйте прямо сейчас в APIs Explorer!
Получите документ Discovery для Google Cloud Service Management API, версия 1:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1