Ferramenta de linha de comando do Cloud Endpoints Frameworks para App Engine

Nesta página, você aprenderá a usar a ferramenta de linha de comando do Endpoints Frameworks para gerar uma biblioteca de cliente a partir da API de back-end do Python (o código executado no servidor). Qualquer app para Android ou em Java pode usar essa biblioteca para chamar a API.

É possível gerar pacotes de biblioteca de cliente que permitem que os aplicativos acessem a API usando a ferramenta de linha de comando do Endpoints Frameworks. Ao gerar uma biblioteca de cliente, a ferramenta de linha de comando do Endpoints Frameworks gera automaticamente um documento de descoberta que descreve a superfície da API.

A ferramenta de linha de comando do Endpoints Frameworks, endpointscfg.py, está disponível na biblioteca do Endpoints Frameworks. Para informações sobre como instalar a biblioteca do Endpoints Frameworks usando o pip, consulte Como instalar a biblioteca do Endpoints Frameworks. Os comandos a seguir presumem que você instalou a biblioteca do Endpoints Frameworks em um diretório chamado lib. Além disso, as instruções presumem que você tenha criado a API de back-end. Consulte o tutorial do Endpoints Frameworks para Python para ver um exemplo de como usar a ferramenta de linha de comando do Endpoints Frameworks no código de amostra.

Como gerar um pacote de biblioteca de cliente com base em uma API

É possível usar a ferramenta de linha de comando do Endpoints Frameworks para gerar os seguintes tipos de pacotes do cliente:

Maven: esse pacote inclui um arquivo pom.xml com as dependências de biblioteca de cliente do Endpoints Frameworks e da API do Google. O arquivo readme.html contém informações detalhadas sobre o que você precisa adicionar ao arquivo pom.xml em diferentes tipos de aplicativos cliente e como criar uma biblioteca de cliente para a API usando o Maven.
Gradle: esse pacote inclui um arquivo build.gradle com as dependências de biblioteca de cliente do Endpoints Frameworks e da API do Google. O arquivo readme.html contém informações detalhadas sobre o que você precisa adicionar ao arquivo build.gradle em diferentes tipos de aplicativos cliente e como criar uma biblioteca de cliente para a API usando o Gradle.
Pacote de cliente padrão: esse pacote contém todas as bibliotecas de dependência e o arquivo source.jar gerado, que é a biblioteca Java usada no cliente para chamar a API. O pacote fornece ao cliente todos os recursos da biblioteca de cliente da API do Google, incluindo o OAuth. O arquivo readme.html lista os arquivos .jar necessários para diferentes tipos de aplicativos cliente e outros detalhes para usar a biblioteca de cliente.

Se você estiver usando a biblioteca de cliente com um app Android, recomendamos o uso de um pacote de clientes do Gradle.

Geração da biblioteca de clientes

Para gerar a biblioteca de cliente:

Altere para o diretório que contém o arquivo app.yaml da API e as classes de serviço da API. Como alternativa, também é possível usar a opção --application para especificar algum outro local do diretório de aplicativos.
Invoque a ferramenta de linha de comando do Endpoints Frameworks semelhante ao seguinte:
```
lib/endpoints/endpointscfg.py get_client_lib java -bs gradle main.EchoApi
```
em que main é a classe que contém a API e EchoApi é o nome da API.
Aguarde enquanto a ferramenta gera a biblioteca de cliente. Quando terminar, uma mensagem como esta será exibida:
```
API client library written to ./echo-v1.zip
```
Adicione o JAR da biblioteca de cliente ao app para Android.
Repita as etapas acima sempre que modificar o código da API.

O pacote de biblioteca de cliente é gravado no diretório atual, a menos que você especifique outro diretório de saída usando a opção output.

Sintaxe da linha de comando

A sintaxe básica é a seguinte:

/path-to/your-app/lib/endpointscfg.py get_client_lib TARGET_LANG OPTIONS CLASS_NAME

onde:

TARGET_LANG especifica o tipo de pacote de cliente que você quer criar. Atualmente, é necessário fornecer o valor java (para clientes Java, como o Android);
OPTIONS, se fornecido, é um ou mais itens mostrados na tabela de Opções;
CLASS_NAME é o nome de classe totalmente qualificado da API.

Opções

É possível usar as seguintes opções:

Nome da opção	Descrição	Exemplo
`application`	Por padrão, a ferramenta gera da API de back-end no diretório atual. Se você quiser gerar usando um diretório diferente, especifique o caminho para o diretório que contém o `app.yaml` e as classes de serviço que implementam sua API.	`--application /my_path/my_api_dir`
`build-system`	Permite especificar que tipo de pacote de cliente será produzido. Especifique `gradle` para um pacote de clientes do Gradle para Android, `maven` para um pacote de clientes do Maven ou `default` (ou simplesmente omita essa opção) para um pacote que contenha somente as bibliotecas de dependência e um jar de origem.	`--build-system=gradle` `-bs gradle`
`hostname`	Especifica o documento de descoberta `rootURL`. Essa opção modifica o valor padrão derivado da entrada `application` no projeto da API de back-end `app.yaml` (`[YOUR_APP_ID].appspot.com`) e o `hostname` definido no decorador da API. Uma das finalidades dessa opção é fornecer o nome de host `localhost` como URL raiz para testes locais.	`--hostname localhost`
`format`	Não especifique, porque o único valor aceito é o valor padrão, `rest` para REST.	Não é necessário, use o padrão.
`output`	Define o diretório em que a saída é gravada. Padrão: o diretório a partir de que a ferramenta é invocada.	`--output /mydir` `-o /mydir`

Plataformas de cliente com suporte

As seguintes plataformas são compatíveis no pacote do cliente produzido pela ferramenta de linha de comando do Endpoints Frameworks:

Java 7 e superior
Android 1.6 e superior (em inglês)
App Engine

Como gerar um documento da OpenAPI a partir de uma API

A ferramenta endpointscfg.py fornece um comando para gerar um documento da OpenAPI a partir de um back-end de API. A sintaxe do comando é:

lib/endpoints/endpointscfg.py get_openapi_spec
    [-h]
    [-a APPLICATION]
    [--hostname HOSTNAME]
    [-o OUTPUT]
    service [service ...]

positional arguments:
  service               Fully qualified service class name.

optional arguments:
  -h, --help            Show this help message and exit.
  -a APPLICATION, --application APPLICATION
                        The path to the Python App Engine application.
  --hostname HOSTNAME   Default application hostname, if none is specified for the API service.
  -o OUTPUT, --output OUTPUT
                        The directory to store output files.
  --x-google-api-name   Add the 'x-google-api-name' field to the generated OpenAPI document.

Por exemplo, usando o exemplo echo (em inglês):

$ lib/endpoints/endpointscfg.py get_openapi_spec --hostname=echo-example.appspot.com main.EchoApi
OpenAPI spec written to ./echov1openapi.json