Configurar o Cloud Endpoints

O Cloud Endpoints suporta APIs descritas através da versão 2.0 da especificação OpenAPI. Descreve a superfície da API e configura funcionalidades dos Endpoints, como regras de autenticação ou quotas, num documento OpenAPI.

Os pontos finais fazem uma utilização especial dos seguintes campos obrigatórios no seu documento OpenAPI:

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

Esta página fornece informações sobre como os Endpoints usam os campos anteriores. Com estas informações, pode terminar a preparação do documento OpenAPI para implementação.

Pré-requisitos

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

host

O Cloud Endpoints usa o nome que configurar no campo host do seu documento OpenAPI como o nome do seu serviço.

O nome do seu serviço de API tem de ser exclusivo no Google Cloud. Uma vez que os Endpoints usam nomes compatíveis com DNS para identificar serviços, recomendamos que use o nome do domínio ou o nome do subdomínio da sua API como o nome do serviço. Com esta abordagem, o nome do serviço que aparece na página Serviços Endpoints corresponde ao nome usado nos pedidos à sua API. O Endpoints tem os seguintes requisitos para o nome do serviço:

  • O comprimento máximo do nome do domínio é de 253 carateres.
  • O nome do domínio tem de começar com uma letra minúscula.
  • Cada secção no nome de domínio, delimitada por pontos, tem os seguintes requisitos:
    • Tem de começar por uma letra minúscula.
    • Não pode terminar com um travessão.
    • Os restantes carateres podem ser letras minúsculas, números ou travessões.
    • O comprimento máximo é de 63 carateres.

Pode registar o seu próprio domínio personalizado (como example.com) ou pode usar um domínio gerido pela Google.

Utilize um domínio gerido pela Google

A Google é proprietária e gere os domínios cloud.goog e appspot.com. Se quiser usar um domínio gerido pela Google, tem de usar oGoogle Cloud ID do projeto como parte do nome do serviço. Uma vez que Google Cloud os projetos têm um ID do projeto exclusivo a nível global, este requisito garante que tem um nome de serviço exclusivo.

O nome do domínio que usa depende do back-end que aloja a sua API:

  • Para APIs alojadas no ambiente flexível do App Engine, tem de usar o domínio appspot.com e o nome do serviço tem de estar no seguinte formato, em que YOUR_PROJECT_ID é o ID do projeto: Google Cloud 

    YOUR_PROJECT_ID.appspot.com

    Quando implementa a sua API no App Engine, é criada automaticamente uma entrada DNS com um nome no formato YOUR_PROJECT_ID.appspot.com.

  • Para APIs alojadas no Compute Engine, no Google Kubernetes Engine ou no Kubernetes, tem de usar o domínio cloud.goog e o nome do serviço tem de estar no seguinte formato, em que YOUR_API_NAME é o nome da sua API:

    YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog

    Para usar este domínio como o nome de domínio da API, leia o artigo Configurar o DNS no domínio cloud.goog.

Use um domínio personalizado

Se não quiser usar um domínio gerido pela Google, pode usar um domínio personalizado (por exemplo, myapi.mycompany.com) que esteja autorizado a usar. Antes de implementar a configuração da API, siga os passos em Validar a propriedade do domínio.

info.title

O campo info.title é um nome intuitivo para a sua API. A página Endpoints > Services na Google Cloud consola apresenta o texto que configura no campo info.title. Se tiver mais do que uma API por Google Cloud projeto, o nome da API é apresentado numa lista quando abre a página pela primeira vez. Pode clicar no nome da API para abrir outra página que apresenta as métricas, o histórico de implementação e outras informações da API.

info.version

A página Endpoints > Services na Google Cloud consola apresenta o número da versão da sua API. Antes de implementar a configuração da API pela primeira vez:

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

  • Defina o campo basePath para o número da versão principal, por exemplo, /v1.

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

operationId

Embora o campo operationId seja opcional na especificação OpenAPI, o campo é obrigatório no Endpoints porque é usado para a identificação interna da operação. A string que usa para o operationId tem de ser única na sua API. Consulte a descrição de operationId na especificação OpenAPI para obter orientações sobre a nomenclatura.

O que se segue?