Começar a usar o Cloud Endpoints para GKE com o ESPv2

OpenAPI   |  gRPC

Este tutorial mostra como configurar e implementar uma API de exemplo e o Extensible Service Proxy V2 (ESPv2) num cluster do Google Kubernetes Engine (GKE).

A API REST do exemplo de código é descrita através da especificação OpenAPI. O tutorial também mostra como criar uma chave da API e usá-la quando enviar pedidos à API.

O tutorial usa imagens de contentores pré-criadas do código de exemplo e do ESPv2, que estão armazenadas no Artifact Registry.

Para uma vista geral do Cloud Endpoints, consulte os artigos Acerca dos Endpoints e Arquitetura dos Endpoints.

Transferir o exemplo de código

Para ajudar a começar rapidamente, são fornecidos exemplos de código em vários idiomas. Para transferir o exemplo de código para a sua máquina local:

Java

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

2. Altere para o diretório que contém o código de exemplo:

   cd java-docs-samples/endpoints/getting-started

Python

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

2. Altere para o diretório que contém o código de exemplo:

   cd python-docs-samples/endpoints/getting-started

Ir

Para clonar ou transferir a API de exemplo:

1. Certifique-se de que a GOPATHvariável de ambiente está definida.
2. Clone o repositório da app de exemplo para a sua máquina local:

   go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

3. Altere para o diretório que contém o código de exemplo:

   cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

PHP

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

   git clone https://github.com/GoogleCloudPlatform/php-docs-samples

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

2. Altere para o diretório que contém o código de exemplo:

   cd php-docs-samples/endpoints/getting-started

Ruby

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

   git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

2. Altere para o diretório que contém o código de exemplo:

   cd ruby-docs-samples/endpoints/getting-started

NodeJS

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

2. Altere para o diretório que contém o código de exemplo:

   cd nodejs-docs-samples/endpoints/getting-started

Configurar pontos finais

O exemplo de código inclui o ficheiro de configuração da OpenAPI, openapi.yaml, que se baseia na especificação da OpenAPI v2.0. Para configurar pontos finais:

1. No diretório de código de exemplo, abra o ficheiro de configuração openapi.yaml.
   Java

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Python

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Ir

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   PHP

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Ruby

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   NodeJS

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Tenha em conta o seguinte:

   • O exemplo de configuração apresenta as linhas junto ao campo host que tem de modificar. Para implementar o ficheiro openapi.yaml nos Endpoints, é necessário o documento OpenAPI completo.
   • O ficheiro de exemplo openapi.yaml contém uma secção para configurar a autenticação que não é necessária para este tutorial. Não precisa de configurar as linhas com YOUR-SERVICE-ACCOUNT-EMAIL e YOUR-CLIENT-ID.
   • A OpenAPI é uma especificação independente do idioma. O mesmo ficheiro openapi.yaml encontra-se no exemplo getting-started em cada repositório do GitHub para sua conveniência.

2. No campo host, substitua o texto pelo nome do serviço Endpoints, que deve estar no seguinte formato:

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"

   Substitua YOUR_PROJECT_ID pelo ID do seu Google Cloud projeto. Por exemplo:

   host: "echo-api.endpoints.example-project-12345.cloud.goog"

Tenha em atenção que echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog é o nome do serviço Endpoints. Não é o nome do domínio totalmente qualificado (FQDN) que usa para enviar pedidos à API.

Para obter informações sobre os campos no documento OpenAPI que o Endpoints requer, consulte o artigo Configurar o Endpoints.

Depois de concluir todos os passos de configuração seguintes para poder enviar pedidos com êxito para a API de exemplo através de um endereço IP, consulte Configurar DNS de pontos finais para obter informações sobre como configurar echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog para ser o FQDN.

Implementar a configuração dos pontos finais

Para implementar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Este comando usa a gestão de serviços para criar um serviço gerido.

Para implementar a configuração dos Endpoints:

1. Certifique-se de que está no diretório endpoints/getting-started.
2. Carregue a configuração e crie um serviço gerido:

   gcloud endpoints services deploy openapi.yaml
   

Em seguida, o comando gcloud chama a API Service Management para criar um serviço gerido com o nome que especificou no campo host do ficheiro openapi.yaml. A gestão de serviços configura o serviço de acordo com as definições no ficheiro openapi.yaml. Quando faz alterações ao openapi.yaml, tem de voltar a implementar o ficheiro para atualizar o serviço Endpoints.

À medida que cria e configura o serviço, o Service Management envia informações para o terminal. Pode ignorar com segurança os avisos sobre os caminhos no ficheiro openapi.yaml que não requerem uma chave da API. Quando terminar de configurar o serviço, a gestão de serviços apresenta uma mensagem com o ID de configuração do serviço e o nome do serviço, semelhante ao seguinte:

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 serviço Endpoints. O ID de configuração do serviço consiste numa data/hora seguida de um número de revisão. Se implementar o ficheiro openapi.yaml novamente no mesmo dia, o número de revisão é incrementado no ID de configuração do serviço. Pode ver a configuração do serviço Endpoints na página Endpoints > Serviços na Google Cloud consola.

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

A verificar os serviços necessários

No mínimo, os pontos finais e o ESP requerem a ativação dos seguintes serviços Google:

Nome	Título
servicemanagement.googleapis.com	Service Management API
servicecontrol.googleapis.com	Service Control API

Na maioria dos casos, o comando gcloud endpoints services deploy ativa estes serviços obrigatórios. No entanto, o comando gcloud é concluído com êxito, mas não ativa os serviços necessários nas seguintes circunstâncias:

• Se usou uma aplicação de terceiros, como o Terraform, e não incluiu estes serviços.

• Implementou a configuração do Endpoints numGoogle Cloud projeto existente no qual estes serviços foram explicitamente desativados.

Use o seguinte comando para confirmar que os serviços necessários estão ativados:

gcloud services list

Se não vir os serviços necessários listados, ative-os:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Ative também o serviço Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, pode:

• Após implementar a configuração do Endpoints, aceda à página Endpoints na Cloud Console. A lista de ENDPOINTS_SERVICE_NAME possíveis é apresentada na coluna Nome do serviço.

• Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que especificou no campo host da sua especificação OpenAPI. Para o gRPC, o ENDPOINTS_SERVICE_NAME é o que especificou no campo name da sua configuração de pontos finais gRPC.

Para mais informações sobre os comandos gcloud, consulte os serviços gcloud.

Implementar o back-end da API

Até agora, implementou o documento OpenAPI na gestão de serviços, mas ainda não implementou o código que publica o back-end da API. Esta secção explica como implementar contentores pré-criados para a API de exemplo e o ESPv2 no cluster.

A verificar as autorizações necessárias

O ESP e o ESPv2 chamam os serviços Google que usam o IAM para verificar se a identidade de chamada tem autorizações suficientes para aceder aos recursos do IAM usados. A identidade de chamada é a conta de serviço anexada que implementa o ESP e o ESPv2.

Quando implementada no pod do GKE, a conta de serviço anexada é a conta de serviço do nó. Normalmente, é a conta de serviço predefinida do Compute Engine. Siga esta recomendação de autorização para escolher uma conta de serviço de nó adequada.

Se for usada a identidade de carga de trabalho, pode ser usada uma conta de serviço separada da conta de serviço do nó para comunicar com os serviços Google. Pode criar uma conta de serviço do Kubernetes para o pod executar o ESP e o ESPv2, criar uma conta de serviço Google e associar a conta de serviço do Kubernetes à conta de serviço Google.

Siga estes passos para associar uma conta de serviço do Kubernetes a uma conta de serviço Google. Esta conta de serviço Google é a conta de serviço anexada.

Se a conta de serviço anexada for a conta de serviço predefinida do Compute Engine do projeto e a configuração do serviço de ponto final for implementada no mesmo projeto, a conta de serviço deve ter autorizações suficientes para aceder aos recursos de IAM. Por isso, pode ignorar o passo de configuração das funções de IAM. Caso contrário, devem ser adicionadas as seguintes funções do IAM à conta de serviço anexada.

Adicione as funções IAM necessárias:

Esta secção descreve os recursos do IAM usados pelo ESP e pelo ESPv2, bem como as funções do IAM necessárias para que a conta de serviço anexada aceda a estes recursos.

Configuração do serviço de ponto final

O ESP e o ESPv2 chamam o Service Control, que usa a configuração do serviço de endpoint. A configuração do serviço de ponto final é um recurso do IAM, e o ESP e o ESPv2 precisam da função Service Controller para aceder a ele.

A função IAM está na configuração do serviço de ponto final e não no projeto. Um projeto pode ter várias configurações de serviços de pontos finais.

Use o seguinte comando gcloud para adicionar a função à conta de serviço anexada para a configuração do serviço de ponto final.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

Onde
* SERVICE_NAME é o nome do serviço de ponto final
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com é a conta de serviço anexada.

Cloud Trace

O ESP e o ESPv2 chamam o serviço Cloud Trace para exportar o rastreio para um projeto. Este projeto é denominado projeto de rastreio. No ESP, o projeto de rastreio e o projeto que detém a configuração do serviço de ponto final são os mesmos. No ESPv2, o projeto de rastreio pode ser especificado através da flag --tracing_project_id e é predefinido como o projeto de implementação.

O ESP e o ESPv2 requerem a função Agente do Cloud Trace para ativar o Cloud Trace.

Use o seguinte comando gcloud para adicionar a função à conta de serviço anexada:

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

Onde
* TRACING_PROJECT_ID é o ID do projeto de rastreio
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com é a conta de serviço anexada. Para mais informações, consulte o artigo O que são funções e autorizações?

Implementar os contentores no cluster

Nota: para frotas de pontos finais singulares/mais pequenas, use --rollout_strategy=managed com SERVICE_NAME. Para grandes frotas de pontos finais, monte a configuração do serviço, conforme mostrado na secção seguinte.

Os contentores oferecem um mecanismo de embalagem lógico no qual pode abstrair as aplicações do ambiente em que são executadas. Use o procedimento seguinte para implementar a API de exemplo e o ESPv2 no cluster. Para implementar os contentores no cluster:

1. Obtenha as credenciais do cluster e disponibilize-as a kubectl:

       gcloud container clusters get-credentials NAME --zone ZONE
       

   Substitua NAME pelo nome do cluster e ZONE pela zona do cluster.
2. Implemente um serviço Kubernetes no cluster do GKE. O serviço Kubernetes implementa a API. git clone este repositório, cd getting-started/ para a pasta e edite o ficheiro de configuração do Kubernetes LANG-deployment.yaml, e substitua SERVICE_NAME nas opções de arranque do ESPv2 pelo nome do seu serviço.
   Java

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed",
       "--healthz=/healthz",
     ]
     readinessProbe:
       httpGet:
         path: /healthz
         port: 8081

   Python

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port=8081",
       "--backend=http://127.0.0.1:8080",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed",
       "--healthz=/healthz",
     ]
     readinessProbe:
       httpGet:
         path: /healthz
         port: 8081

   Ir

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port", "8081",
       "--backend", "127.0.0.1:8080",
       "--service", "SERVICE_NAME",
       "--rollout_strategy", "managed",
       "--healthz=/healthz",
     ]
     readinessProbe:
       httpGet:
         path: /healthz
         port: 8081

   PHP

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port", "8081",
       "--backend", "127.0.0.1:8080",
       "--service", "SERVICE_NAME",
       "--rollout_strategy", "managed",
       "--healthz=/healthz",
     ]

   Ruby

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port", "8081",
       "--backend", "127.0.0.1:8080",
       "--service", "SERVICE_NAME",
       "--rollout_strategy", "managed",
       "--healthz=/healthz",
     ]

   NodeJS

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port", "8081",
       "--backend", "127.0.0.1:8080",
       "--service", "SERVICE_NAME",
       "--rollout_strategy", "managed",
       "--healthz=/healthz",
     ]
     readinessProbe:
       httpGet:
         path: /healthz
         port: 8081

   Por exemplo:

     args: [
       "--listener_port=8081",
       "--backend=http://127.0.0.1:8080",
       "--service=echo-api.endpoints.example-project-12345.cloud.goog ",
       "--rollout_strategy=managed",
     ]
   

   A opção --rollout_strategy=managed configura o ESPv2 para usar a configuração do serviço implementada mais recente. Quando especifica esta opção, no prazo de um minuto após implementar uma nova configuração de serviço, o ESPv2 deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de fornecer um ID de configuração específico para o ESPv2 usar. Para ver informações sobre as outras opções do ESPv2 usadas, consulte o artigo Opções de arranque do ESPv2.

   Recomendamos que defina o imagePullPolicy na especificação do contentor acima para Always. Isto permite que os pods recém-criados extraiam sempre a versão mais recente do ESPv2. Leia acerca das práticas recomendadas de configuração para ver mais detalhes. Quando é lançada uma nova versão do ESPv2, pode fazer um reinício contínuo de todos os pods para garantir que é usada a versão mais recente.

   Implementar configurações de serviços nos Endpoints

   Se executar uma grande frota de Endpoints (mais de 100) no mesmo projeto do Google Cloud, recomendamos que monte a configuração do serviço para o contentor em vez de usar a flag --rollout_strategy=managed para extrair a configuração do serviço da API Service Management.

   A API Service Management tem uma quota predefinida. Se uma grande frota de proxies ESPv2 usar --rollout_strategy=managed, todos vão sondar a configuração de serviço mais recente. A frota pode exceder a quota e, assim, causar falhas na atualização da configuração do serviço.

   Siga os passos abaixo para montar a configuração do serviço:
   1. Transfira a configuração JSON do serviço.

   curl -o "/tmp/service_config.json" -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://servicemanagement.googleapis.com/v1/services/SERVICE/configs/CONFIG_ID?view=FULL"
   

   2. Crie um recurso de mapa de configuração do Kubernetes a partir da configuração JSON.

   kubectl create configmap service-config-configmap \
     --from-file=service_config.json:/tmp/service_config.json
   

   3. Monte o recurso do mapa de configuração no contentor e use a flag --service_config_path para especificar o caminho do ficheiro de configuração.

   Por exemplo:

     containers:
     - args:
       - --listener_port=8081
       - --backend=http://127.0.0.1:8080
       - --service_json_path=/etc/espv2_config/service_config.json
       - --healthz=/healthz
       image: gcr.io/endpoints-release/endpoints-runtime:2
       name: esp
       ports:
       - containerPort: 8081
         protocol: TCP
       volumeMounts:
       - mountPath: /etc/espv2_config
         name: service-config-volume
     volumes:
     - configMap:
         defaultMode: 420
         name: service-config-configmap
       name: service-config-volume
   

3. Inicie o serviço Kubernetes com o comando kubectl apply:
   Java

   kubectl apply -f java-deployment.yaml

   Python

   kubectl apply -f python-deployment.yaml

   Ir

   kubectl apply -f golang-deployment.yaml

   PHP

   kubectl apply -f php-deployment.yaml

   Ruby

   kubectl apply -f ruby-deployment.yaml

   NodeJS

   kubectl apply -f nodejs-deployment.yaml

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas de pontos finais no GKE. Consulte o artigo Implementar o back-end da API para ver informações adicionais.

Obter o endereço IP externo do cluster

Para enviar pedidos para a API, precisa do IP externo do serviço. Pode demorar alguns minutos após iniciar o serviço no contentor até que o endereço IP externo esteja pronto.

1. Ver o endereço IP externo:

   kubectl get ingress

2. Tome nota do valor de EXTERNAL-IP. Usa esse endereço IP quando envia um pedido para a API de exemplo.

Enviar um pedido através de um endereço IP

Agora que o serviço está a ser executado no cluster de contentores e tem o endereço IP externo, pode enviar pedidos para a API.

Crie uma chave da API e defina uma variável de ambiente

O código de exemplo requer uma chave da API. Para simplificar o pedido, defina uma variável de ambiente para a chave da API.

1. No mesmo Google Cloud projeto que usou para a sua API, crie uma chave da API na página de credenciais da API. Se quiser criar uma chave da API num Google Cloud projeto diferente, consulte o artigo Ativar uma API no seu Google Cloud projeto.

   Aceda à página Credenciais

2. Clique em Criar credenciais e, de seguida, selecione Chave de API.
3. Copie a chave para a área de transferência.
4. Clique em Fechar.
5. No computador local, cole a chave da API para a atribuir a uma variável de ambiente:
   • No Linux ou macOS: export ENDPOINTS_KEY=AIza...
   • No Windows PowerShell: $Env:ENDPOINTS_KEY="AIza..."

Envie o pedido

Linux ou Mac OS

Use curl para enviar um pedido HTTP através da variável de ambiente ENDPOINTS_KEY que definiu anteriormente. Substitua IP_ADDRESS pelo endereço IP externo da sua instância.

curl --request POST \
   --header "content-type:application/json" \
   --data '{"message":"hello world"}' \
   "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"

Nos curl anteriores:

• A opção --data especifica os dados a publicar na API.
• A opção --header especifica que os dados estão no formato JSON.

PowerShell

Use Invoke-WebRequest para enviar um pedido HTTP através da variável de ambiente ENDPOINTS_KEY que definiu anteriormente. Substitua IP_ADDRESS pelo endereço IP externo da sua instância.

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

No exemplo anterior, as duas primeiras linhas terminam com um acento grave. Quando colar o exemplo no PowerShell, certifique-se de que não existe um espaço após os acentos graves. Para obter informações sobre as opções usadas no pedido de exemplo, consulte Invoke-WebRequest na documentação da Microsoft.

App de terceiros

Pode usar uma aplicação de terceiros, como a extensão do navegador Chrome Postman, para enviar o pedido:

• Selecione POST como verbo HTTP.
• Para o cabeçalho, selecione a chave content-type e o valor application/json.
• Para o corpo, introduza o seguinte:
  {"message":"hello world"}
• No URL, use a chave da API real em vez da variável de ambiente. Por exemplo:
  http://192.0.2.0:80/echo?key=AIza...

A API devolve a mensagem que envia e responde com o seguinte:

{
  "message": "hello world"
}

Se não recebeu uma resposta bem-sucedida, consulte o artigo Resolução de problemas de erros de resposta.

Acabou de implementar e testar uma API no Endpoints!

Nota: se quiser partilhar o que gostou neste tutorial, não hesite em enviar feedback na parte inferior desta página. O seu feedback ajuda-nos a melhorar estes tutoriais.
Se recebeu um erro, junte-se ao google-cloud-endpoints grupo Google e diga-nos o que correu mal. Este grupo recebe respostas de outros utilizadores do Endpoints e de engenheiros da Google, que monitorizam o grupo.

Acompanhamento da atividade da API

Para acompanhar a atividade da API:

1. Consulte os gráficos de atividade da sua API na página Endpoints > Serviços.
   

   Aceda à página Serviços de pontos finais

   
   Pode demorar alguns momentos até que o pedido se reflita nos gráficos.
2. Consulte os registos de pedidos da sua API na página do Explorador de registos.
   

   Aceda à página do Explorador de registos

Configurar o DNS para pontos finais

Uma vez que o nome do serviço Endpoints para a API está no domínio .endpoints.YOUR_PROJECT_ID.cloud.goog, pode usá-lo como o nome de domínio totalmente qualificado (FQDN) fazendo uma pequena alteração de configuração no ficheiro openapi.yaml. Desta forma, pode enviar pedidos para a API de exemplo através de echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog em vez do endereço IP.

Para configurar o DNS dos Endpoints:

1. Abra o ficheiro de configuração da OpenAPI, openapi.yaml, e adicione a propriedade x-google-endpoints no nível superior do ficheiro (sem recuo nem aninhamento), conforme mostrado no seguinte fragmento:

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
   x-google-endpoints:
   - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
     target: "IP_ADDRESS"

2. Na propriedade name, substitua YOUR_PROJECT_ID pelo ID do seu projeto.
3. Na propriedade target, substitua IP_ADDRESS pelo endereço IP que usou quando enviou um pedido para a API de exemplo.
4. Implemente o ficheiro de configuração OpenAPI atualizado na gestão de serviços:

   gcloud endpoints services deploy openapi.yaml
   

Por exemplo, suponha que o ficheiro openapi.yaml tem a seguinte configuração:

host: "echo-api.endpoints.example-project-12345.cloud.goog"
x-google-endpoints:
- name: "echo-api.endpoints.example-project-12345.cloud.goog"
  target: "192.0.2.1"

Quando implementa o ficheiro openapi.yaml através do comando gcloud anterior, a gestão de serviços cria um registo A de DNS, echo-api.endpoints.my-project-id.cloud.goog, que é resolvido para o endereço IP de destino, 192.0.2.1. A propagação da nova configuração de DNS pode demorar alguns minutos.

Configurar SSL

Para mais detalhes sobre como configurar o DNS e o SSL, consulte o artigo Ativar SSL para pontos finais.

Enviar um pedido através do FQDN

Agora que tem o registo DNS configurado para a API de exemplo, envie-lhe um pedido usando o FQDN (substitua YOUR_PROJECT_ID pelo ID do seu projeto) e a variável de ambiente ENDPOINTS_KEY definida anteriormente:

• No Linux ou Mac OS:

  curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"

• No Windows PowerShell:

  (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content