Começar a usar o Cloud Endpoints para Kubernetes com o ESP

OpenAPI   |  gRPC

Este tutorial mostra como configurar e implementar uma API de exemplo e o proxy de serviço extensível (ESP) num cluster do Kubernetes que não está no Google Cloud. Se quiser usar o Google Kubernetes Engine (GKE), consulte o artigo Introdução aos Endpoints no GKE.

A API REST do código de exemplo é descrita através da especificação OpenAPI. O tutorial também mostra como criar uma chave da API para enviar pedidos para a API.

O tutorial usa imagens de contentores pré-criadas do código de exemplo e do ESP, que estão armazenadas no Artifact Registry. Se não tiver familiaridade com os contentores, consulte o seguinte para mais informações:

• Implementar uma aplicação Web contentorizada.
• Imagens de contentores do Kubernetes.

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

Transferir o exemplo de código

Opcionalmente, transfira o exemplo de código. Neste tutorial, implementa uma imagem de contentor pré-criada, pelo que não tem de criar um contentor a partir do código de exemplo. No entanto, recomendamos que transfira o código de exemplo, que é fornecido em vários idiomas para ajudar a compreender o funcionamento da API de exemplo.

Para transferir o código de exemplo:

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

Obter o ficheiro de configuração do Kubernetes

1. Clone o repositório do GitHub que contém os ficheiros yaml usados neste tutorial para o seu computador local:

    git clone https://github.com/googlecloudplatform/endpoints-samples

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

2. Altere para o diretório que contém os ficheiros de configuração:

    cd endpoints-samples/kubernetes

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.
   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 e conseguir enviar pedidos com êxito para a API de exemplo através de um endereço IP, consulte o artigo Configurar o DNS para 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-samples/k8s.
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.

Criar credenciais para o seu serviço

Para fornecer gestão para a sua API, o ESP e o ESPv2 requerem os serviços na infraestrutura de serviços. Para chamar estes serviços, o ESP e o ESPv2 têm de usar tokens de acesso. Quando implementa o ESP ou o ESPv2 em Google Cloud ambientes, como o GKE, o Compute Engine ou o ambiente flexível do App Engine, o ESP e o ESPv2 obtêm tokens de acesso para si através do Google Cloud serviço de metadados.

Quando implementa o ESP ou o ESPv2 num ambiente nãoGoogle Cloud , como o seu computador local, um cluster do Kubernetes no local ou outro fornecedor de nuvem, tem de fornecer um ficheiro JSON de conta de serviço que contenha uma chave privada. O ESP e o ESPv2 usam a conta de serviço para gerar tokens de acesso para chamar os serviços de que precisa para gerir a sua API.

Pode usar a Google Cloud consola ou a CLI Google Cloud para criar a conta de serviço e o ficheiro de chave privada:

Consola

1. Na Google Cloud consola, abra a página Contas de serviço .

   Aceda à página Contas de serviço

2. Clique em Selecionar um projeto.
3. Selecione o projeto no qual a API foi criada e clique em Abrir.
4. Clique em + Criar conta de serviço.
5. No campo Nome da conta de serviço, introduza o nome da conta de serviço.
6. Clique em Criar.
7. Clique em Continuar.
8. Clique em Concluído.
9. Clique no endereço de email da conta de serviço recém-criada.
10. Clique em Chaves.
11. Clique em Adicionar chave e, de seguida, em Criar nova chave.

12. Clique em Criar. É transferido um ficheiro de chave JSON para o seu computador.

    Certifique-se de que armazena o ficheiro de chave em segurança, uma vez que pode ser usado para autenticar como a sua conta de serviço. Pode mover e mudar o nome deste ficheiro como quiser.

13. Clique em Fechar.

gcloud

1. Introduza o seguinte para apresentar os IDs dos seus Google Cloud projetos:

   gcloud projects list

2. Substitua PROJECT_ID no seguinte comando para definir o projeto predefinido para o projeto em que a sua API se encontra:

   gcloud config set project PROJECT_ID

   Importante: tem de criar a conta de serviço no mesmo projeto em que se encontra a sua API.

3. Certifique-se de que a CLI do Google Cloud (gcloud) está autorizada a aceder aos seus dados e serviços em Google Cloud:

   gcloud auth login

   Se tiver mais do que uma conta, certifique-se de que escolhe a conta que está no Google Cloud projeto em que a API se encontra. Se executar o comando gcloud auth list, a conta que selecionou é apresentada como a conta ativa para o projeto.

4. Para criar uma conta de serviço, execute o seguinte comando e substitua SERVICE_ACCOUNT_NAME e My Service Account pelo nome e nome a apresentar que quer usar:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
      --display-name "My Service Account"

   O comando atribui um endereço de email à conta de serviço no seguinte formato:

   SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

   Este endereço de email é necessário nos comandos subsequentes.

5. Crie um ficheiro de chave de conta de serviço:

   gcloud iam service-accounts keys create ~/service-account-creds.json \
      --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

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?

Consulte gcloud iam service-accounts para mais informações sobre os comandos.

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 ESP no Kubernetes.

A verificar as autorizações necessárias

Conceda as autorizações necessárias à conta de serviço associada ao seu cluster:

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member "serviceAccount:SERVICE_ACCOUNT" \
  --role roles/servicemanagement.serviceController

Para mais informações, consulte o artigo O que são funções e autorizações?

Fornecer ao ESP as credenciais do serviço

O ESP, que é executado num contentor, precisa de acesso às credenciais armazenadas localmente no ficheiro service-account-creds.json. Para fornecer ao ESP acesso às credenciais, cria um secret do Kubernetes e monta o secret do Kubernetes como um volume do Kubernetes.

Para criar o secret do Kubernetes e montar o volume:

1. Certifique-se de que muda o nome do ficheiro JSON para service-account-creds.json e o copia para endpoints-samples/k8s se tiver sido transferido para um diretório diferente. Desta forma, o nome corresponde às opções especificadas no esp_echo_http.yamlficheiro de manifesto de implementação.

2. Certifique-se de que está no diretório endpoints-samples/k8s.

3. Crie um segredo do Kubernetes com as credenciais da conta de serviço:

   kubectl create secret generic service-account-creds \
     --from-file=service-account-creds.json
   

   Em caso de êxito, é apresentada a seguinte mensagem: secret "service-account-creds" created

O ficheiro de manifesto de implementação que usa para implementar a API e o ESP no Kubernetes já contém o volume secreto, conforme mostrado nas duas secções seguintes do ficheiro:

volumes:
  - name: service-account-creds
    secret:
      secretName: service-account-creds

volumeMounts:
  - mountPath: /etc/nginx/creds
    name: service-account-creds
    readOnly: true

Configurar o nome do serviço e iniciar o serviço

O ESP precisa de saber o nome do seu serviço para encontrar a configuração que implementou anteriormente (através do comando gcloud endpoints services deploy).

Para configurar o nome do serviço e iniciar o serviço:

1. Abra o ficheiro do manifesto de implementação, esp_echo_http.yaml, e substitua SERVICE_NAME nas opções de arranque do ESP pelo nome do seu serviço. Este é o mesmo nome que configurou no campo host do seu documento OpenAPI. Por exemplo:

   "--service=echo-api.endpoints.example-project-12345.cloud.goog"

   containers:
     - name: esp
       image: gcr.io/endpoints-release/endpoints-runtime:1
       args: [
         "--http_port", "8080",
         "--backend", "127.0.0.1:8081",
         "--service", "SERVICE_NAME",
         "--rollout_strategy", "managed",
         "--service_account_key", "/etc/nginx/creds/service-account-creds.json",
       ]

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

   Nota: se estiver a usar o MiniKube, tem de alterar o campo type do serviço de LoadBalancer para NodePort no ficheiro de configuração.
   Nota: 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 ESP. Leia acerca das práticas recomendadas de configuração para ver mais detalhes. Quando é lançada uma nova versão do ESP, pode fazer um reinício contínuo de todos os pods para garantir que é usada a versão mais recente.

2. Inicie o serviço para implementar o serviço Endpoints no Kubernetes:

   kubectl create -f echo.yaml

   Se vir uma mensagem de erro semelhante à seguinte:

   The connection to the server localhost:8080 was refused - did you specify the right host or port?

   Isto indica que o kubectl não está configurado corretamente. Consulte o artigo Configure o kubectl para mais informações.

Para mais informações, consulte o artigo Implementar Endpoints no Kubernetes.

Obtenha o endereço IP externo do serviço

Se estiver a usar o Minikube, avance para a secção Enviar um pedido através de um endereço IP.

Depois de iniciar o serviço no contentor, pode demorar alguns minutos até que o endereço IP externo esteja pronto.

Para ver o endereço IP externo do serviço:

1. Execute o seguinte comando:

   kubectl get service

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

Depois de a API de amostra estar em execução no cluster de contentores, 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 para minikube

Os seguintes comandos usam a variável de ambiente ENDPOINTS_KEY que definiu anteriormente.

Linux ou Mac OS

NODE_PORT=`kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}'`
MINIKUBE_IP=`minikube ip`
curl --request POST \
    --header "content-type:application/json" \
    --data '{"message":"hello world"}' \
    ${MINIKUBE_IP}:${NODE_PORT}/echo?key=${ENDPOINTS_KEY}

PowerShell

$Env:NODE_PORT=$(kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}')
$Env:MINIKUBE_IP=$(minikube ip)
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://$Env:MINIKUBE_IP:$Env:NODE_PORT/echo?key=$Env:ENDPOINTS_KEY").Content

Envie o pedido para outros clusters do Kubernetes

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 para o 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