Como implantar a configuração do Endpoints

Depois de configurar o Cloud Endpoints em um documento da OpenAPI, é preciso implantá-lo para que ele forneça as informações necessárias no gerenciamento da API. Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Esse comando usa a Service Infrastructure, a plataforma de serviços fundamentais do Google. Ela é usada pelo Endpoints e por outros serviços para criar e gerenciar APIs e serviços. Nesta página, descrevemos como implantar um documento do OpenAPI no Endpoints.

Pré-requisitos

Como ponto de partida, nesta página presume-se que você:

Como preparar o SDK do Cloud para implantação

Use a ferramenta de linha de comando gcloud para implantar a configuração. Consulte a Referência da gcloud para mais informações sobre os comandos.

Para se preparar para a implantação:

  1. Instale e inicialize o SDK do Cloud.
  2. Atualize o Cloud SDK:
    gcloud components update
    
  3. Verifique se o Cloud SDK tem autorização para acessar seus dados e serviços:
    gcloud auth login
    

    Uma nova guia do navegador será aberta, e você precisará escolher uma conta.

  4. Defina o projeto padrão. Substitua [YOUR-PROJECT-ID] pelo ID do projeto do GCP.
    gcloud config set project [YOUR-PROJECT-ID]
    
  5. Se você estiver implantando o back-end da API para o Kubernetes ou Kubernetes Engine, execute o comando a seguir para receber novas credenciais de usuário para o Application Default Credentials. As credenciais de usuário são necessárias para autorizar kubectl.
    gcloud auth application-default login
    Uma nova guia do navegador será aberta e você precisará escolher uma conta.

Como validar a sintaxe openapi.json

O arquivo do documento da OpenAPI pode estar no formato YAML ou JSON. Se estiver em JSON, recomendamos que a sintaxe seja confirmada antes da implantação do arquivo. Para verificar se o openapi.json é um arquivo JSON bem formatado, é possível abri-lo em um editor de texto de validação de JSON, como vim, usar um serviço de linter JSON on-line ou usar Python, por exemplo:

python -m json.tool openapi.json

Para melhorar a legibilidade, é possível formatar o estilo do arquivo JSON:

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

Substitua input.json pelo caminho do seu arquivo openapi.json. output.json é o arquivo JSON bem impresso.

Como validar o documento do OpenAPI

Nem todas as criações do OpenAPI são compatíveis atualmente com o Cloud Endpoints. Antes da implantação, valide o documento do OpenAPI.

Para isso:

  1. Altere o diretório para o local que contém o documento do OpenAPI.

  2. Confirme o projeto do Google Cloud em que você quer criar o serviço. Se você estiver usando um nome de domínio personalizado, como myapi.example.com, valide o ID do projeto retornado do comando a seguir para que o serviço não seja criado no projeto errado.

    gcloud config list project
    

    Se precisar alterar o projeto padrão, execute o seguinte comando e substitua [YOUR_PROJECT_ID] pelo ID do projeto do Google Cloud em que você 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 do OpenAPI que descreve a 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 gerenciado com o nome especificado no campo host no documento da OpenAPI. Quando você especifica a sinalização --validate-only, um serviço ainda é criado, mas a configuração não é implantada. Não há como validar o documento da OpenAPI sem criar um serviço. É possível excluir o serviço, mas o Service Management impede a criação de um com o mesmo nome por aproximadamente 30 dias.

Como implantar o documento da OpenAPI

Quando estiver tudo pronto para implantar a API, execute a ferramenta de linha de comando gcloud, que usa o Service Management para fazer upload da configuração da API e criar (ou atualizar) um serviço gerenciado.

Para implantar o documento da OpenAPI:

  1. Altere o diretório para o local que contém o documento do OpenAPI.

  2. Valide o código do projeto retornado do seguinte comando para garantir que o serviço não seja criado no projeto incorreto.

    gcloud config list project
    

    Se você precisar alterar o projeto padrão, execute o seguinte comando e substitua [YOUR_PROJECT_ID] pelo ID do projeto do Google Cloud em que você 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 do OpenAPI que descreve a API:

    gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]
    

Na primeira vez que você executa o comando anterior, o Service Management cria um novo serviço do Endpoints no projeto padrão com um nome que corresponde ao texto especificado no campo host no documento da OpenAPI e envia a configuração do serviço.

Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. Após a conclusão, uma linha semelhante a esta é exibida com o ID da configuraçã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.

Depois de realizar a implantação, é possível ver a API na página Endpoints > Serviços no Console do Cloud.

Se você receber uma mensagem de erro, consulte Como solucionar problemas de implantação na configuração do Endpoints.

Como fazer a reimplantação

Sempre que você fizer mudanças no documento da OpenAPI, implante-o novamente para que a versão mais recente da configuração da API esteja disponível para o Endpoints. Não é necessário reimplantar ou reiniciar o ESP se você já tiver implementado o ESP com a opção rollout definida como managed. Essa opção configura o ESP para usar a implantação mais recente da configuração do serviço. Quando você especifica essa opção, até 5 minutos depois de implantar uma nova configuração de serviço, o ESP detecta a alteração e começa a usá-la automaticamente. Recomendamos especificar essa opção em vez de um ID de configuração específico para uso do ESP.

Após a implantação inicial da configuração do Endpoints, é possível conceder a um usuário, uma conta de serviço ou um grupo um papel que permita a reimplantação da configuração do Endpoints. Consulte Como conceder e revogar o acesso à API para mais informações.

A seguir