Esta página foi traduzida pela API Cloud Translation.

Como criar uma biblioteca de cliente

Introdução

Você pode usar o serviço de descoberta de APIs do Google para criar várias ferramentas diferentes com as APIs do Google. No entanto, o objetivo principal do documento de descoberta é permitir que o Google crie bibliotecas de cliente em várias linguagens de programação. Esta seção descreve como criar uma biblioteca de cliente personalizada para as APIs do Google.

Uma biblioteca de cliente estável e completa com todos os recursos é uma ferramenta complicada que pode levar meses para ser desenvolvida. No entanto, as instruções gerais para criar uma biblioteca de cliente simples para as APIs do Google podem ser divididas em três etapas simples:

Buscar o documento Discovery e construir a superfície da API
Como criar uma solicitação
Fazer uma chamada e buscar a resposta

Esses níveis são descritos em mais detalhes nas seções a seguir. Você também pode dar uma olhada na amostra Simple APIs client na seção "Exemplos" para ver como essas instruções mapeiam o código.

Etapa 1: buscar o documento de descoberta

Antes de começar a implementar uma biblioteca de cliente, há alguns requisitos básicos que afetam o processo de desenvolvimento. Por exemplo, a linguagem de programação de sua preferência pode ser digitada ou não. Se for digitada, ela pode ser estaticamente ou dinamicamente. Ele pode ser compilado ou interpretado. Esses requisitos orientarão sua abordagem para consumir e usar o documento Discovery.

A primeira tarefa de desenvolvimento é buscar o documento Discovery. Sua estratégia para exatamente quando o documento deve ser buscado é determinada pelos requisitos que você identificou. Por exemplo, em uma linguagem digitada estaticamente, você pode buscar o documento Discovery no início do processo e gerar código para processar a API específica descrita pelo documento Discovery. Para uma linguagem altamente tipada, você pode gerar um código e criar uma biblioteca compilada. Para uma linguagem dinâmica, é possível construir lentamente as estruturas de programação para interagir com a API em tempo real à medida que a superfície de programação é usada.

Etapa 2: criar uma solicitação

A criação de solicitações envolve duas etapas separadas:

Como escrever o corpo da solicitação.
Criação do URL de solicitação.

Se necessário, é preciso converter o corpo da solicitação de uma representação apropriada para o idioma no formato correto de transmissão. Por exemplo, em uma biblioteca cliente Java, pode haver uma classe para cada tipo de solicitação que permite a manipulação com segurança de tipo dos dados da solicitação e é serializável em JSON.

A construção do URL da solicitação é um processo um pouco mais complicado.

A propriedade path de cada método na API usa a sintaxe do URI do modelo v04. A propriedade pode conter variáveis que ficam entre chaves. Veja um exemplo de uma propriedade path com variáveis:

/example/path/var

No caminho acima, var é uma variável. O valor dessa variável vem da seção parameters do documento Discovery desse método. Cada nome de variável tem um valor correspondente no objeto parameters. No exemplo acima, há um parâmetro chamado var na seção parameters (e a propriedade location é path para indicar que é uma variável de caminho).

Ao fazer uma solicitação, substitua o valor de var pelo URL. Por exemplo, se o usuário da biblioteca fizer uma escolha que defina var como o valor foo, o novo URL será /example/path/foo.

A propriedade path é um URI relativo. Para calcular o URI absoluto, siga estas etapas:

Use a propriedade rootUrl do nível superior do documento do Discovery.
Por exemplo, a propriedade rootUrl no documento de descoberta da API Google Cloud Service Management é:

https://servicemanagement.googleapis.com/
Use o servicePath do nível superior do documento do Discovery.
Por exemplo, a propriedade servicePath no documento Discovery da API Google Cloud Service Management está vazia.
Concatene-os juntos para ter:

https://servicemanagement.googleapis.com/
Pegue a propriedade path, expanda-a como um modelo de URI e combine os resultados dessa expansão com o URI da etapa anterior.
Por exemplo, no método de serviço get da API Google Cloud Service Management, o valor da propriedade path é v1/services/{serviceName}. Assim, o URI completo do método é:

https://servicemanagement.googleapis.com/v1/services/{serviceName}

Uma chave de API é necessária para chamar a API Google Cloud Service Management. Portanto, depois de aplicar uma chave de API, o URI completo para receber a definição do serviço do API Discovery Service é:

https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY

Etapa 3: fazer uma chamada e processar a resposta

Depois de enviar a solicitação, você precisa desserializar a resposta na representação da linguagem apropriada, tomando cuidado de processar as condições de erro que podem ocorrer, tanto no transporte HTTP subjacente quanto nas mensagens de erro geradas pelo serviço da API. O formato dos erros é documentado como parte do Guia de estilo JSON do Google.

Examples

Para ver alguns exemplos concretos de bibliotecas de cliente e ferramentas que foram implementadas usando o serviço de descoberta de APIs do Google, consulte o documento Bibliotecas e amostras. Além disso, a seção a seguir mostra um exemplo simples de uma biblioteca de cliente das APIs.

Cliente de APIs simples

Veja abaixo um exemplo de uma biblioteca de cliente muito simples escrita em Python3 . O cliente cria uma interface para interagir com a API Google Cloud Service Management e recebe a definição do serviço da API Discovery Service usando essa interface.

Aviso: o código abaixo é uma versão significativamente simplificada de uma biblioteca de cliente típica. É uma implementação incompleta fornecida para demonstrar alguns aspectos da criação de uma biblioteca de cliente. Ele não é um código pronto para produção.

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'))

Os principais componentes do cliente são:

Etapa 1: buscar o documento Discovery
O documento Discovery da API Google Cloud Service Management é recuperado e analisado em uma estrutura de dados. Como Python é uma linguagem tipada dinamicamente, o documento Discovery pode ser buscado no momento da execução.
Etapa 2.a: criar o URI base
O URI de base é calculado.
Etapa 2.b: criar a solicitação
Quando um método é chamado em uma coleção, o modelo de URI é expandido com os parâmetros transmitidos ao método e os parâmetros com um local query são colocados nos parâmetros de consulta do URL. Por fim, a solicitação é enviada para o URL composto usando o método HTTP especificado no documento do Discovery.
Etapa 3.a: criar a superfície do cliente
A superfície do cliente é criada por ordem decrescente decrescente sobre o documento Discovery analisado. Para cada método na seção methods, um novo método é anexado ao objeto Collection. Como as coleções podem ser aninhadas, buscamos resources e criamos um objeto Collection recursivamente para todos os membros, se houver. Cada coleção aninhada também é anexada como um atributo ao objeto Collection.
Etapa 3.b: usar o cliente
Isso demonstra como a superfície da API criada é usada. Primeiro um objeto de serviço é criado com base no documento do Discovery. Em seguida, a definição do serviço da API Discovery é recuperada com a API Google Cloud Service Management.