Como adicionar gerenciamento de APIs

O Cloud Endpoints Frameworks oferece recursos de gerenciamento de APIs que são comparáveis com os recursos que o Extensible Service Proxy (ESP) fornece para o Cloud Endpoints. Os frameworks do Endpoints incluem um gateway de API (em inglês) integrado que intercepta todas as solicitações e realiza as verificações necessárias, como autenticação, antes de encaminhar a solicitação ao back-end da API. Quando o back-end responde, o Endpoints Frameworks coleta e relata a telemetria. É possível ver as métricas da API na página Endpoints > Serviços no Console do Google Cloud.

Os recursos de gerenciamento de APIs disponíveis no Endpoints Frameworks incluem os itens a seguir:

Para que sua API seja gerenciada pelo Cloud Endpoints, implante um documento do OpenAPI que descreva sua API usando a versão 2.0 da Especificação OpenAPI. Nesta página, você aprenderá como gerar e implantar um documento OpenAPI que ative o Endpoints para gerenciar sua API.

Se você não adicionar o gerenciamento da API, ela ainda exibirá solicitações, mas não aparecerá na página Endpoints > Serviços do Console do Google Cloud. Além disso, a funcionalidade fornecida pelo Endpoints, como geração de registros, monitoramento e definição de cotas, não estará disponível.

Como instalar e configurar o software necessário

Instale e configure a Google Cloud CLI para Python, se ainda não tiver feito isso, e adicione a biblioteca Python do Endpoints Frameworks ao diretório do projeto da API para que seja carregada com o código da API na implantação.

Instalar e configurar a CLI gcloud para Python

Instale e inicialize a CLI gcloud:

Fazer o download e instalar a CLI gcloud
Instale o componente gcloud que inclui a extensão do App Engine para Python:
```
gcloud components install app-engine-python
```
Atualizar a CLI gcloud:
```
gcloud components update
```
Verifique se a CLI gcloud está autorizada a acessar seus dados e serviços no Google Cloud:
```
gcloud auth login
```
Uma nova guia do navegador será aberta e você precisará escolher uma conta.
Defina o projeto padrão como o ID do projeto. Substitua o YOUR_PROJECT_ID pelo ID do projeto do Google Cloud.
```
gcloud config set project YOUR_PROJECT_ID
```
Para Linux, configure a variável de ambiente ENDPOINTS_GAE_SDK no caminho da pasta do SDK do App Engine:
```
PATH_TO_CLOUD_SDK/platform/google_appengine
```
Substitua PATH_TO_CLOUD_SDK pela saída do comando a seguir:
```
gcloud info --format="value(installation.sdk_root)"
```

Adicione a biblioteca em Python do Endpoints Frameworks

Compile as extensões de C para Python.
- Windows: é necessário ter o Microsoft Visual C++ 9.0 ou posterior. Faça o download do Microsoft Visual C++ Compiler para Python 2.7 no Centro de download da Microsoft.
- Outros sistemas operacionais: dependendo do seu sistema operacional, talvez seja necessário instalar ferramentas de compilação (às vezes em um pacote chamado build-essential) e/ou os cabeçalhos de desenvolvimento em Python (às vezes em um pacote chamado python-dev).
Altere o diretório para o principal da sua API.
Crie um subdiretório /lib no diretório principal da API:
```
mkdir lib
```

Instale a biblioteca:

pip install -t lib google-endpoints --ignore-installed

Gerar o documento OpenAPI

No diretório principal da API, gere um documento OpenAPI usando as ferramentas de framework. Exemplo:

Classe única

Substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud no comando a seguir.

python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi \
    --hostname YOUR_PROJECT_ID.appspot.com

Ignore os avisos exibidos.

Várias classes

Você pode listar várias classes na linha de comando. O Endpoints gera um documento OpenAPI para cada combinação de nome/versão da API.

Se você quer implantar várias classes de API com nomes de API diferentes como parte de um único serviço, também será preciso adicionar a sinalização --x-google-api-name. A ativação dessa sinalização adiciona outras restrições aos nomes de API. Especificamente, os nomes devem corresponder à expressão regular [a-z][a-z0-9]{0,39}. Ou seja, o nome deve conter de 1 a 40 caracteres, que podem ser caracteres alfabéticos minúsculos ou números, sendo que o primeiro deles não pode ser um número. Exemplo:

Substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud no comando a seguir.

python lib/endpoints/endpointscfg.py get_openapi_spec main.FooApi main.BarApi \
   --hostname YOUR_PROJECT_ID.appspot.com \
   --x-google-api-name

Ignore os avisos exibidos.

O Endpoints usa o texto especificado no argumento hostname como o nome do serviço. Ao implantar a API no App Engine, uma entrada DNS com um nome no formato YOUR_PROJECT_ID.appspot.com é automaticamente criada.

Implantar o documento OpenAPI

Classe única

gcloud endpoints services deploy echov1openapi.json

Várias classes

Se você tiver vários documentos OpenAPI, liste todos na linha de comando. Exemplo:

 gcloud endpoints services deploy foov1openapi.json barv1openapi.json

Na primeira vez que você implanta um ou mais documentos da OpenAPI, um novo serviço do Endpoints é criado com o nome YOUR_PROJECT_ID.appspot.com.

Após a conclusão, uma linha semelhante a esta será exibida com o código da configuração e o nome do serviço:

Service Configuration 2017-02-13r0 uploaded for service example-project-12345.appspot.com

No exemplo acima, 2017-02-13r0 é o ID de configuração do serviço. Esse ID de configuração do serviço consiste em um registro de data e número de revisão. Se você implantar o documento OpenAPI novamente, o número de revisão será incrementado no código da configuração do serviço.

Caso precise exibir o ID de configuração do serviço novamente, execute o comando a seguir, mas substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud:

gcloud endpoints configs list --service=YOUR_PROJECT_ID.appspot.com

É possível criar seu próprio documento OpenAPI e implantá-lo em vez de usar um gerado. Simplesmente substitua echov1openapi.json, visto acima, pelo caminho para seu documento da OpenAPI. Para mais informações sobre como escrever um documento OpenAPI, consulte visão geral do OpenAPI.

Reimplantar a API e testar

Edite o arquivo app.yaml do seu projeto e adicione uma seção env_variables desta forma:
```
env_variables:
  ENDPOINTS_SERVICE_NAME: YOUR_PROJECT_ID.appspot.com
  ENDPOINTS_SERVICE_VERSION: YOUR_SERVICE_VERSION
```
Substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud e YOUR_SERVICE_VERSION pelo ID de configuração do serviço da seção anterior. Com essa adição ao arquivo app.yaml, o Endpoints gerencia a API depois que você implanta o aplicativo novamente.
Implante o aplicativo novamente:
```
gcloud app deploy
```
Aguarde a conclusão bem-sucedida da implantação, ignorando as mensagens de aviso. Quando a implantação for concluída, será exibida uma mensagem parecida com esta:
```
File upload done.
Updating service [default]...done.
```

Verifique se a reimplantação foi bem-sucedida, por exemplo, usando curl:

curl --request POST \
    --header "Content-Type: application/json" \
    --data '{"content":"echo"}' \
    https://YOUR_PROJECT_ID.appspot.com/_ah/api/echo/v1/echo?n=2

Substitua echo pelo nome da API.

Os resultados exibirão algo semelhante a:

{
 "content": "echo echo"
}

Faça algumas solicitações adicionais à API.
Para ver as métricas da API, abra a página Endpoints > Serviços no console do Google Cloud do seu projeto:

Ir para a página Serviços do Endpoints