Configuração do Cloud Endpoints

O Cloud Endpoints é compatível com as APIs descritas com a versão 2.0 da especificação OpenAPI. Basta descrever a superfície da API e configurar os recursos do Endpoints, como regras de autenticação ou cotas, em um documento da OpenAPI.

Os Endpoints fazem uso especial dos seguintes campos obrigatórios no documento OpenAPI:

  • host
  • info.title
  • info.version
  • operationId

Nesta página, você encontra informações sobre como o Endpoints usa os campos abaixo. Assim, você pode concluir a preparação do documento OpenAPI para a implantação.

Pré-requisitos

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

host

O Cloud Endpoints usa o nome configurado no campo host do documento da OpenAPI como o nome do serviço.

No Google Cloud, o nome do serviço da API precisa ser exclusivo. Como o Endpoints usa nomes compatíveis com o DNS para identificar serviços, recomendamos que você use o nome de domínio ou de subdomínio da API como o nome do serviço. Com essa abordagem, o nome do serviço que aparece na página Serviços do Endpoints corresponde ao nome usado nas solicitações para a API. Além disso, se o nome do serviço e o nome do domínio forem os mesmos, será possível criar um portal do Cloud Endpoints para os usuários da API. O Endpoints tem os seguintes requisitos para o nome de serviço:

  • The maximum length of the domain name is 253 characters.
  • The domain name must start with a lowercase letter.
  • Each section in the domain name, which is delimited by dots, has the following requirements:
    • Must start with a lowercase letter.
    • Must not end with a dash.
    • The remaining characters can be lowercase letters, numbers, or dashes.
    • The maximum length is 63 characters.

É possível registrar seu próprio domínio personalizado, como example.com, ou usar um domínio gerenciado pelo Google.

Usar um domínio gerenciado pelo Google

O Google é proprietário dos domínios cloud.goog e appspot.com, e os gerencia. Se você quer usar um domínio gerenciado pelo Google, use o ID do projeto do Google Cloud como parte do nome do serviço. Como os projetos do Google Cloud têm um ID de projeto exclusivo a nível global, esse requisito garante que você tenha um nome de serviço exclusivo.

O nome do domínio depende do back-end que hospedará sua API:

  • Para APIs hospedadas no ambiente flexível do App Engine, você precisa usar o domínio appspot.com. Além disso, o nome do serviço deve estar no seguinte formato, sendo YOUR_PROJECT_ID o ID do projeto do Google Cloud:

    YOUR_PROJECT_ID.appspot.com

    Ao implantar a API no App Engine, uma entrada DNS com um nome no formato YOUR_PROJECT_ID.appspot.com é automaticamente criada.

  • Para APIs hospedadas no Compute Engine, Google Kubernetes Engine ou Kubernetes, você precisa usar o domínio cloud.goog. Além disso, o nome do serviço deve estar no seguinte formato, sendo YOUR_API_NAME o nome da API:

    YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog

    Para usar esse domínio como o nome de domínio da API, leia Como configurar o DNS no domínio cloud.goog.

Usar um domínio personalizado

Se você não quer usar um domínio gerenciado pelo Google, saiba que é possível usar um domínio personalizado (myapi.mycompany.com, por exemplo), desde que você tenha autorização. Antes de implantar a configuração da API, siga as etapas abordadas em Verificar a propriedade do domínio.

info.title

O campo info.title é um nome fácil de usar para a API. O Endpoints > A página Serviços no console do Google Cloud exibe o que você configura no campo info.title. Caso você tenha mais de uma API por projeto do Google Cloud, o nome da API será exibido em uma lista quando a página for aberta pela primeira vez. Clique no nome da API para abrir outra página que exibe as métricas da API, o histórico de implantações e outras informações.

info.version

O menu Endpoints > A página Serviços no console do Google Cloud exibe o o número de versão da sua API. Antes de implantar a configuração da API pela primeira vez, faça o seguinte:

  • Defina o número da versão no campo info.version para a versão aplicável da API, como 1.0.

  • Defina o número da versão principal no campo basePath, como /v1.

Para mais informações sobre o controle de versão da sua API, consulte Gerenciamento do ciclo de vida da API.

operationId

O operationId é um campo opcional na Especificação da OpenAPI. Já no Endpoints ele é obrigatório, porque é usado para identificação interna da operação. A string que você usa para o operationId precisa ser exclusiva na API. Veja a descrição para operationId na especificação da OpenAPI para ver orientações sobre nomenclatura.

A seguir