Введение

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