Implementar a configuração dos pontos finais

Depois de configurar o Cloud Endpoints num documento OpenAPI, implementa-o para que o Endpoints tenha as informações necessárias para gerir a sua API. Para implementar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Este comando usa a infraestrutura de serviços, a plataforma de serviços fundamentais da Google, usada pelos Endpoints e outros serviços para criar e gerir APIs e serviços. Esta página descreve como implementar um documento OpenAPI nos Endpoints.

Pré-requisitos

Como ponto de partida, esta página pressupõe que:

Preparar a CLI do Google Cloud para a implementação

Use a ferramenta de linha de comandos gcloud para implementar a configuração. Consulte a referência gcloud para mais informações sobre os comandos.

Para se preparar para a implementação:

  1. Instale e inicialize a CLI gcloud.
  2. Atualize a CLI gcloud: 
    gcloud components update
  3. Certifique-se de que a CLI gcloud está autorizada a aceder aos seus dados e serviços: 
    gcloud auth login

    É aberto um novo separador do navegador e é-lhe pedido que escolha uma conta.

  4. Defina o projeto predefinido. Substitua [YOUR-PROJECT-ID] pelo ID do seu projeto da GCP 
    gcloud config set project [YOUR-PROJECT-ID]
  5. Se vai implementar o seu back-end da API no Kubernetes ou no Kubernetes Engine, execute o seguinte comando para adquirir novas credenciais do utilizador a usar para as credenciais predefinidas da aplicação. As credenciais do utilizador são necessárias para autorizar kubectl. 
    gcloud auth application-default login
     É aberto um novo separador do navegador e é-lhe pedido que escolha uma conta.

A validar a sintaxe openapi.json

O ficheiro do documento OpenAPI pode estar no formato YAML ou JSON. Se estiver no formato JSON, recomendamos que valide a sintaxe antes de implementar o ficheiro. Para verificar se o seu openapi.json é um ficheiro JSON bem formatado, pode abri-lo num editor de texto de validação JSON, como o vim, usar um serviço de análise estática JSON online ou usar o Python, por exemplo:

python -m json.tool openapi.json

Para melhorar a legibilidade, pode formatar o ficheiro JSON:

python -m json.tool input.json > output.json

Substitua input.json pelo caminho para o ficheiro openapi.json. output.json é o ficheiro JSON formatado.

Validar o seu documento OpenAPI

Atualmente, nem todas as construções da OpenAPI são suportadas pelos Cloud Endpoints. Antes de implementar, pode validar o seu documento OpenAPI.

Para validar o seu documento OpenAPI:

  1. Mude o diretório para a localização que contém o seu documento OpenAPI.

  2. Confirme o Google Cloud projeto onde quer criar o serviço. Se estiver a usar um nome de domínio personalizado (como myapi.example.com), certifique-se de que valida o ID do projeto devolvido pelo seguinte comando para que o serviço não seja criado no projeto errado.

    gcloud config list project

    Se precisar de alterar o projeto predefinido, execute o seguinte comando e substitua [YOUR_PROJECT_ID] pelo Google Cloud ID do projeto no qual quer criar o serviço:

    gcloud config set project [YOUR_PROJECT_ID]

  3. Execute o seguinte comando e substitua [YOUR_OPENAPI_DOCUMENT] pelo nome do documento OpenAPI que descreve a sua API:

    gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT] --validate-only

Em seguida, o comando gcloud chama a API Service Management para criar um serviço gerido com o nome que especificou no campo host no seu documento OpenAPI. Quando especifica a flag --validate-only, continua a ser criado um serviço, mas a configuração não é implementada. Não existe uma forma de validar o seu documento OpenAPI sem criar um serviço. Embora possa eliminar o serviço, a gestão de serviços impede a criação de um serviço com o mesmo nome durante um período de aproximadamente 30 dias.

Implementar o documento OpenAPI

Quando estiver tudo pronto para implementar a sua API, executa a CLI Google Cloud, que usa o Service Management para carregar a configuração da API e para criar (ou atualizar) um serviço gerido.

Para implementar o seu documento OpenAPI:

  1. Mude o diretório para a localização que contém o seu documento OpenAPI.

  2. Valide o ID do projeto devolvido pelo seguinte comando para se certificar de que o serviço não é criado no projeto errado.

    gcloud config list project

    Se precisar de alterar o projeto predefinido, execute o seguinte comando e substitua [YOUR_PROJECT_ID] pelo Google Cloud ID do projeto no qual quer criar o serviço::

    gcloud config set project [YOUR_PROJECT_ID]

  3. Execute o seguinte comando e substitua [YOUR_OPENAPI_DOCUMENT] pelo nome do documento OpenAPI que descreve a sua API:

    gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]

Quando executa o comando anterior pela primeira vez, o Service Management cria um novo serviço de Endpoints no projeto predefinido com um nome que corresponde ao texto especificado no campo host no seu documento OpenAPI e carrega a configuração do serviço.

À medida que cria e configura o serviço, a gestão de serviços envia informações para o terminal. Após a conclusão com êxito, é apresentada uma linha semelhante à seguinte, que apresenta o ID da configuração do serviço e o nome do serviço:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço e echo-api.endpoints.example-project-12345.cloud.goog é o nome do serviço.

Após uma implementação bem-sucedida, pode ver a API na página Endpoints > Serviços na Google Cloud consola.

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas de implementação da configuração dos Endpoints.

A voltar a implementar

Sempre que alterar algo no seu documento OpenAPI, certifique-se de que o implementa novamente para que o Endpoints tenha a versão mais recente da configuração do serviço da sua API. Não precisa de voltar a implementar nem reiniciar o ESP se o tiver implementado anteriormente com a opção rollout definida como managed. Esta opção configura o ESP para usar a configuração do serviço implementada mais recente. Quando especifica esta opção, até 5 minutos após implementar uma nova configuração de serviço, o ESP deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de um ID de configuração específico para o ESP usar.

Após a implementação da configuração inicial dos Endpoints, pode conceder a um utilizador, a uma conta de serviço ou a um grupo uma função que lhe permita reimplementar a configuração dos Endpoints. Consulte o artigo Conceder e revogar acesso à API para mais informações.

O que se segue?