Введение
Вы можете использовать службу обнаружения API Google для создания множества различных инструментов для использования с API Google. Однако основная цель документа Discovery — позволить Google создавать клиентские библиотеки на различных языках программирования. В этом разделе описывается, как можно создать пользовательскую клиентскую библиотеку для API Google.
Стабильная и полнофункциональная клиентская библиотека — это сложный инструмент, на разработку которого могут уйти месяцы. Однако общие инструкции по созданию простой клиентской библиотеки для API Google можно разбить на три простых шага:
- Получение документа Discovery и создание поверхности API
- Составление запроса
- Совершение звонка и получение ответа
Эти шаги более подробно описаны в следующих разделах. Вы также можете просмотреть пример клиента Simple APIs в разделе «Примеры», чтобы увидеть, как эти инструкции сопоставляются с кодом.
Шаг 1 : Получите документ Discovery
Прежде чем приступить к реализации клиентской библиотеки, необходимо выполнить некоторые основные требования, влияющие на то, как вы будете продвигаться по пути разработки. Например, выбранный вами язык программирования может быть либо типизированным, либо нетипизированным; если он типизирован, он может быть либо статически, либо динамически типизирован. Он может быть скомпилирован или интерпретирован. Эти требования будут определять ваш подход к потреблению и использованию документа Discovery.
Первая задача разработки — получить документ Discovery. Ваша стратегия точного определения того, когда документ должен быть извлечен, определяется установленными вами требованиями. Например, в языке со статической типизацией вы можете получить документ Discovery в начале процесса, а затем сгенерировать код для обработки конкретного API, описанного в документе Discovery. Для строго типизированного языка вы можете сгенерировать некоторый код и собрать скомпилированную библиотеку. Для динамически типизированного языка вы можете лениво создавать программные структуры для взаимодействия с API на лету по мере использования поверхности программирования.
Шаг 2 : Составьте запрос
Составление запроса включает два отдельных шага:
- Составление тела запроса.
- Создание URL-адреса запроса.
Вам необходимо преобразовать тело запроса, если таковое имеется, из представления, соответствующего языку, в правильный формат проводки. Например, в клиентской библиотеке Java может быть класс для каждого типа запроса, который позволяет безопасно манипулировать данными запроса и может сериализоваться в JSON.
Создание URL-адреса запроса — немного более сложный процесс.
Свойство path каждого метода в API использует синтаксис URI Template v04 . Это свойство может содержать переменные, заключенные в фигурные скобки. Вот пример свойства path с переменными:
/example/path/var
В приведенном выше пути var является переменной. Значение этой переменной берется из раздела parameters документа Discovery для этого метода. Каждое имя переменной имеет соответствующее значение в объекте parameters . В приведенном выше примере в разделе parameters есть параметр с именем var (и его свойство location равно path , чтобы указать, что это переменная пути).
При выполнении запроса вы должны подставить значение var в URL-адрес. Например, если пользователь библиотеки делает выбор, присваивая var значение foo , новый URL-адрес будет /example/path/foo .
Также обратите внимание, что свойство path является относительным URI. Чтобы вычислить абсолютный URI, выполните следующие действия:
Возьмите свойство
rootUrlс верхнего уровня документа Discovery.
Например, свойствоrootUrlв документе Discovery для Google Cloud Service Management API :https://servicemanagement.googleapis.com/Возьмите
servicePathс верхнего уровня документа Discovery.
Например, свойствоservicePathв документе Discovery для Google Cloud Service Management API пусто.Соедините их вместе, чтобы получить:
https://servicemanagement.googleapis.com/Возьмите свойство
path, разверните его как шаблон URI и объедините результаты этого расширения с URI из предыдущего шага.
Например, в методеgetслужбы Google Cloud Service Management API значением свойстваpathявляетсяv1/services/{serviceName}. Итак, полный URI метода:https://servicemanagement.googleapis.com/v1/services/{serviceName}
Для вызова Google Cloud Service Management API требуется ключ API. Таким образом, после применения ключа API полный URI для получения определения службы API Discovery Service выглядит следующим образом:
https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key= API_KEY
Шаг 3. Позвоните и обработайте ответ.
После отправки запроса вам необходимо десериализовать ответ в соответствующее языковое представление, позаботившись об обработке возможных ошибок — как в базовом HTTP-транспорте, так и в сообщениях об ошибках, генерируемых службой API. Формат ошибок задокументирован как часть Руководства по стилю Google JSON .
Примеры
Некоторые конкретные примеры клиентских библиотек и инструментов, реализованных с помощью службы обнаружения API Google, см. в документе « Библиотеки и примеры». Кроме того, в следующем разделе приведен простой пример клиентской библиотеки API.
Простой клиент API
Ниже приведен пример очень простой клиентской библиотеки, написанной на Python3. Клиент создает интерфейс для взаимодействия с Google Cloud Service Management API , а затем получает определение службы API Discovery Service с помощью этого интерфейса.
Предупреждение : приведенный ниже код представляет собой значительно упрощенную версию типичной клиентской библиотеки. Это неполная реализация, предназначенная для демонстрации некоторых аспектов построения клиентской библиотеки. Это не готовый к производству код.
import httplib2
import json
import uritemplate
import urllib
# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://servicemanagement.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)
# Step 2.a: Construct base URI
BASE_URL = discovery['rootUrl'] + discovery['servicePath']
class Collection(object): pass
def createNewMethod(name, method):
# Step 2.b Compose request
def newMethod(**kwargs):
body = kwargs.pop('body', None)
url = urllib.parse.urljoin(BASE_URL, uritemplate.expand(method['path'], kwargs))
for pname, pconfig in method.get('parameters', {}).items():
if pconfig['location'] == 'path' and pname in kwargs:
del kwargs[pname]
if kwargs:
url = url + '?' + urllib.parse.urlencode(kwargs)
return h.request(url, method=method['httpMethod'], body=body,
headers={'content-type': 'application/json'})
return newMethod
# Step 3.a: Build client surface
def build(discovery, collection):
for name, resource in discovery.get('resources', {}).items():
setattr(collection, name, build(resource, Collection()))
for name, method in discovery.get('methods', {}).items():
setattr(collection, name, createNewMethod(name, method))
return collection
# Step 3.b: Use the client
service = build(discovery, Collection())
print (service.services.get(serviceName='discovery.googleapis.com', key='API_KEY'))
Ключевыми компонентами клиента являются:
- Шаг 1 : Получите документ Discovery .
Документ обнаружения для Google Cloud Service Management API извлекается и анализируется в структуру данных. Поскольку Python является языком с динамической типизацией, документ Discovery можно получить во время выполнения. - Шаг 2.a : Создайте базовый URI .
Вычисляется базовый URI. - Шаг 2.b : Составьте запрос .
Когда метод вызывается для коллекции, шаблон URI расширяется с помощью параметров, переданных в метод, а параметры с расположениемqueryпомещаются в параметры запроса URL-адреса. Наконец, запрос отправляется на составленный URL-адрес с использованием метода HTTP, указанного в документе обнаружения. - Шаг 3.a : Создайте клиентскую поверхность .
Поверхность клиента создается путем рекурсивного спуска по проанализированному документу Discovery. Для каждого метода в разделеmethodsк объектуCollectionприсоединяется новый метод. Поскольку коллекции могут быть вложенными, мы ищемresourcesи рекурсивно создаем объектCollectionдля всех его элементов, если он найден. Каждая вложенная коллекция также прикрепляется как атрибут к объектуCollection. - Шаг 3.b : Используйте клиент .
Это демонстрирует, как используется построенная поверхность API. Сначала из документа Discovery создается объект службы, затем определение службы API Discovery Service извлекается через Google Cloud Service Management API.