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.

O nome do serviço da API precisa ser exclusivo no Google Cloud. 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:

  • O comprimento máximo do nome do domínio é de 253 caracteres.
  • O nome de domínio precisa começar com uma letra minúscula.
  • Cada seção no nome de domínio, delimitada por pontos, apresenta os seguintes requisitos:
    • Precisa começar com uma letra minúscula.
    • Não pode terminar com um traço.
    • Os outros caracteres podem ser letras minúsculas, números ou traços.
    • O comprimento máximo é de 63 caracteres.

É 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 doGoogle Cloud como parte do nome do serviço. Como os projetos do Google Cloud têm um ID de projeto exclusivo globalmente, 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 precisa estar no seguinte formato, em que 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. A página Endpoints > Serviços no console Google Cloud mostra o texto que você configura no campo info.title. Se você tiver 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

A página Endpoints > Serviços no console Google Cloud mostra o número da versão da 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. Para orientações sobre nomenclatura, consulte a descrição de operationId na Especificação da OpenAPI.

A seguir