Esta página foi traduzida pela API Cloud Translation.

Crie uma biblioteca de cliente

Pode usar o Google APIs Discovery Service para criar várias ferramentas diferentes para usar com as APIs Google. No entanto, o objetivo principal do documento Discovery é permitir que a Google crie bibliotecas cliente em várias linguagens de programação. Este documento descreve como pode criar uma biblioteca cliente personalizada para as APIs Google.

Uma biblioteca cliente estável e com todas as funcionalidades é uma ferramenta complexa que pode demorar meses a ser desenvolvida. No entanto, as instruções gerais para criar uma biblioteca cliente simples para as APIs Google podem ser divididas em três passos simples:

Obter o documento de deteção e construir a superfície da API
Compor um pedido
Fazer uma chamada e obter a resposta

Estes passos são descritos mais detalhadamente nas secções seguintes. Também pode consultar o exemplo do cliente de APIs simples na secção Exemplos para ver como estas instruções se relacionam com o código.

Obtenha o documento de deteção

Antes de começar a implementar uma biblioteca cliente, existem alguns requisitos básicos que afetam a forma como vai avançar no seu caminho de desenvolvimento. Por exemplo, a linguagem de programação da sua escolha pode ser escrita ou não escrita. Se for escrita, pode ser escrita estática ou dinamicamente. Pode ser compilado ou interpretado. Estes requisitos vão orientar a sua abordagem ao consumo e utilização do documento Discovery.

A primeira tarefa de desenvolvimento é obter o documento Discovery. A sua estratégia para saber exatamente quando o documento deve ser obtido é determinada pelos requisitos que identificou. Por exemplo, numa linguagem de tipagem estática, pode obter o documento Discovery no início do processo e, em seguida, gerar código para processar a API específica descrita pelo documento Discovery. Para um idioma com tipos fortes, pode gerar algum código e criar uma biblioteca compilada. Para uma linguagem de tipos dinâmicos, pode construir as estruturas de programação de forma diferida para interagir com a API em tempo real à medida que a superfície de programação é usada.

Componha um pedido

A composição de pedidos envolve dois passos separados:

Compor o corpo do pedido.
Construir o URL do pedido.

Tem de converter o corpo do pedido, se existir, de uma representação adequada ao idioma para o formato de transmissão correto. Por exemplo, numa biblioteca de cliente Java, pode existir uma classe para cada tipo de pedido que permita a manipulação segura de tipos dos dados do pedido e que seja serializável em JSON.

A construção do URL do pedido é um processo ligeiramente mais complicado.

A propriedade path de cada método na API usa a sintaxe do modelo de URI v04. Esta propriedade pode conter variáveis, que estão entre chavetas. Segue-se um exemplo de uma propriedade path com variáveis:

/example/path/var

No caminho acima, var é uma variável. O valor desta variável é proveniente da secção parameters do documento Discovery para esse método. Cada nome de variável tem um valor correspondente no objeto parameters. No exemplo acima, existe um parâmetro denominado var na secção parameters (e a respetiva propriedade location é path, para indicar que é uma variável de caminho).

Quando fizer um pedido, deve substituir o valor de var no URL. Por exemplo, se o utilizador da biblioteca fizer uma escolha que defina var para o valor foo, o novo URL será /example/path/foo.

Tenha também em atenção que a propriedade path é um URI relativo. Para calcular o URI absoluto, siga estes passos:

Se souber a sua localização (região) e o documento de descoberta tiver a propriedade endpoints, verifique se a sua localização está presente na lista endpoints. Se assim for, selecione o endpointUrl da lista endpoints cujo location corresponde ao seu.
Se não existir uma propriedade endpoints no documento Discovery ou a sua localização não estiver presente na lista endpoints, ou se quiser segmentar o ponto final global, obtenha a propriedade rootUrl do nível superior do documento Discovery.

Por exemplo, a propriedade rootUrl no documento de descoberta para a API Service Usage é:
```
https://serviceusage.googleapis.com/
```
Obtenha o servicePath do nível superior do documento de descoberta. Por exemplo, a propriedade servicePath no documento Discovery para a API Service Usage está vazia.
Concatene-os para obter:
```
https://serviceusage.googleapis.com/
```
Obtenha a propriedade path, expanda-a como um modelo de URI e combine os resultados dessa expansão com o URI do passo anterior. Por exemplo, no método serviceusage.services.enable da API Service Usage v1, o valor da propriedade path é v1/{+name}:enable. Assim, o URI completo do método é:
```
https://serviceusage.googleapis.com/v1/{+name}:enable
```

Não precisa de uma chave da API para chamar a API Service Usage. No entanto, se a API que está a chamar exigir uma chave da API, pode adicionar a chave da API à string de consulta do URI:

REQUEST_URI?key=API_KEY

Fazer uma chamada e processar a resposta

Depois de enviar o pedido, tem de desserializar a resposta na representação de linguagem adequada, tendo o cuidado de processar as condições de erro que possam ocorrer, tanto no transporte HTTP subjacente como nas mensagens de erro geradas a partir do serviço da API. O formato dos erros está documentado como parte do guia de estilo JSON da Google.

Exemplos

A secção seguinte apresenta um exemplo simples de uma biblioteca de cliente de APIs.

Cliente de APIs simples

Segue-se um exemplo de uma biblioteca cliente muito simples escrita em Python3. O cliente cria uma interface para interagir com a API Service Usage e, em seguida, usa essa interface para ativar a API Compute Engine (compute.googleapis.com) no projeto my-project.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://serviceusage.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)
location = None # Set this to your location if appropriate
use_global_endpoint = True # Set this to False if you want to target the endpoint for your location

# Step 2.a: Construct base URI
BASE_URL = None
if not use_global_endpoint and location:
  if discovery['endpoints']:
    BASE_URL = next((item['endpointUrl'] for item in discovery['endpoints'] if item['location'] == location), None)
if not BASE_URL:
  BASE_URL = discovery['rootUrl']
BASE_URL += 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 (serviceusage.services.enable(name='projects/my-project/services/compute.googleapis.com'))

Os componentes essenciais do cliente são:

Passo 1: obtenha o documento Discovery. O documento de descoberta da API Service Usage é obtido e analisado numa estrutura de dados. Uma vez que o Python é uma linguagem de programação com tipagem dinâmica, o documento Discovery pode ser obtido no momento da execução.
Passo 2.a: construa o URI base. O URI base é calculado.
Passo 2.b: componha o pedido. Quando um método é chamado numa coleção, o modelo de URI é expandido com os parâmetros transmitidos para o método e os parâmetros com uma localização de query são colocados nos parâmetros de consulta do URL. Por fim, é enviado um pedido para o URL composto através do método HTTP especificado no documento Discovery.
Passo 3.a: crie a superfície do cliente. A superfície do cliente é criada através da descida recursiva sobre o documento Discovery analisado. Para cada método na secção methods, é anexado um novo método ao objeto Collection. Como as coleções podem ser aninhadas, procuramos resources e criamos recursivamente um objeto Collection para todos os respetivos membros, se for encontrado um. Cada coleção aninhada também está anexada como um atributo ao objeto Collection.
Passo 3.b: use o cliente. Isto demonstra como a superfície da API incorporada é usada. Primeiro, é criado um objeto de serviço a partir do documento Discovery e, em seguida, a API Service Usage é usada para ativar a API Compute Engine no projeto my-project.