Создание клиентской библиотеки

Введение

Вы можете использовать службу обнаружения API Google для создания множества различных инструментов для использования с API Google. Однако основная цель документа Discovery — позволить Google создавать клиентские библиотеки на различных языках программирования. В этом разделе описывается, как можно создать пользовательскую клиентскую библиотеку для API Google.

Стабильная и полнофункциональная клиентская библиотека — это сложный инструмент, на разработку которого могут уйти месяцы. Однако общие инструкции по созданию простой клиентской библиотеки для API Google можно разбить на три простых шага:

  1. Получение документа Discovery и создание поверхности API
  2. Составление запроса
  3. Совершение звонка и получение ответа

Эти шаги более подробно описаны в следующих разделах. Вы также можете просмотреть пример клиента Simple APIs в разделе «Примеры», чтобы увидеть, как эти инструкции сопоставляются с кодом.

Шаг 1 : Получите документ Discovery

Прежде чем приступить к реализации клиентской библиотеки, необходимо выполнить некоторые основные требования, влияющие на то, как вы будете продвигаться по пути разработки. Например, выбранный вами язык программирования может быть либо типизированным, либо нетипизированным; если он типизирован, он может быть либо статически, либо динамически типизирован. Он может быть скомпилирован или интерпретирован. Эти требования будут определять ваш подход к потреблению и использованию документа Discovery.

Первая задача разработки — получить документ Discovery. Ваша стратегия точного определения того, когда документ должен быть извлечен, определяется установленными вами требованиями. Например, в языке со статической типизацией вы можете получить документ Discovery в начале процесса, а затем сгенерировать код для обработки конкретного API, описанного в документе Discovery. Для строго типизированного языка вы можете сгенерировать некоторый код и собрать скомпилированную библиотеку. Для динамически типизированного языка вы можете лениво создавать программные структуры для взаимодействия с API на лету по мере использования поверхности программирования.

Шаг 2 : Составьте запрос

Составление запроса включает два отдельных шага:

  1. Составление тела запроса.
  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, выполните следующие действия:

  1. Возьмите свойство rootUrl с верхнего уровня документа Discovery.
    Например, свойство rootUrl в документе Discovery для Google Cloud Service Management API :

    https://servicemanagement.googleapis.com/

  2. Возьмите servicePath с верхнего уровня документа Discovery.
    Например, свойство servicePath в документе Discovery для Google Cloud Service Management API пусто.

  3. Соедините их вместе, чтобы получить:

    https://servicemanagement.googleapis.com/

  4. Возьмите свойство 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.