Configure o gRPC do Cloud Endpoints para o Cloud Run com o ESPv2

Configure o gRPC do Cloud Endpoints para o Cloud Run com o ESPv2

OpenAPI   |  gRPC

Esta página mostra como configurar o Cloud Endpoints para o Cloud Run com um back-end gRPC. Os Endpoints usam o Extensible Service Proxy V2 (ESPv2) como um gateway de API. Para fornecer gestão de APIs para o Cloud Run, implementa o contentor ESPv2 pré-criado no Cloud Run. Em seguida, ajuda a proteger os seus serviços através do Cloud Run IAM para que o ESPv2 os possa invocar.

Com esta configuração, o ESPv2 interceta todos os pedidos aos seus serviços e realiza todas as verificações necessárias (como a autenticação) antes de invocar o serviço. Quando o serviço responde, o ESPv2 recolhe e comunica a telemetria, conforme mostrado na figura abaixo. Pode ver as métricas do seu serviço na página Endpoints > Serviços na Google Cloud consola.

Nota: no gráfico acima, o ESPv2 e o "backend" são implementados em duas instâncias separadas do Cloud Run.

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

Migrar para o ESPv2

As versões anteriores do Cloud Endpoints não suportavam gRPC no Cloud Run com o ESP. Para usar esta funcionalidade, migre para o proxy de serviço extensível V2.

Lista de tarefas

Use a seguinte lista de tarefas enquanto segue o tutorial. Todas as tarefas são necessárias para concluir este tutorial.

1. Crie um Google Cloud projeto e, se ainda não tiver implementado o seu próprio Cloud Run, implemente um serviço gRPC de back-end de exemplo. Consulte a secção Antes de começar.
2. Reserve um nome do anfitrião do Cloud Run para o serviço ESPv2. Consulte o artigo Reserve um nome do anfitrião do Cloud Run.
3. Crie um documento de configuração da API gRPC que descreva a sua API e configure as rotas para o Cloud Run. Consulte o artigo Configurar pontos finais.
4. Implemente o documento de configuração da API gRPC para criar um serviço gerido. Consulte o artigo Implementar a configuração dos Endpoints.
5. Crie uma nova imagem do Docker do ESPv2 com a configuração do serviço Endpoints. Consulte o artigo Criar uma nova imagem do ESPv2.
6. Implemente o contentor do ESPv2 no Cloud Run. Em seguida, conceda ao ESPv2 a autorização da gestão de identidade e de acesso (IAM) para invocar o seu serviço. Consulte o artigo Implementar o contentor do ESPv2.
7. Invocar um serviço. Consulte o artigo Enviar um pedido para a API.
8. Monitorize a atividade nos seus serviços. Consulte o artigo Acompanhamento da atividade da API.
9. Evite incorrer em cobranças na sua conta Google Cloud . Consulte Limpar.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• Cloud Run
• Endpoints

Para gerar uma estimativa de custos com base na sua utilização prevista, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Para configurar:

1. Na Google Cloud consola, aceda à página Gerir recursos e crie um projeto.

   Aceda à página Gerir recursos

2. Certifique-se de que a faturação está ativada para o seu projeto.

   Saiba como ativar a faturação

3. Tome nota do ID do projeto, pois é necessário mais tarde. No resto desta página, este ID do projeto é designado como ESPv2_PROJECT_ID.

4. Tome nota do número do projeto porque é necessário mais tarde. No resto desta página, este número do projeto é denominado ESPv2_PROJECT_NUMBER.

5. Transfira e instale a Google Cloud CLI.

   Transfira a CLI gcloud

6. Siga os passos no guia de início rápido do gRPC Python para instalar o gRPC e as ferramentas do gRPC.

7. Implemente o exemplo de back-end python-grpc-bookstore-server serviço do Cloud Run gRPC para utilização com este tutorial. O serviço gRPC usa a seguinte imagem de contentor:

   gcr.io/endpointsv2/python-grpc-bookstore-server:2

   Siga os passos no artigo Início rápido: implemente um contentor de exemplo pré-criado para implementar o serviço. Certifique-se de que substitui a imagem do contentor especificada nesse início rápido por gcr.io/endpointsv2/python-grpc-bookstore-server:2

   Tome nota da região e do ID do projeto onde o seu serviço está implementado. No resto desta página, este ID do projeto é designado por BACKEND_PROJECT_ID. O nome do serviço do Cloud Run implementado é denominado BACKEND_SERVICE_NAME. O respetivo nome do anfitrião do Cloud Run é denominado BACKEND_HOST_NAME.

Reservar um nome de anfitrião do Cloud Run

Tem de reservar um nome de anfitrião do Cloud Run para o serviço ESPv2 para configurar o documento OpenAPI ou a configuração do serviço gRPC. Para reservar um nome do anfitrião, implementa um contentor de exemplo no Cloud Run. Posteriormente, implementa o contentor do ESPv2 no mesmo serviço do Cloud Run.

Nota: cada serviço do Cloud Run do ESPv2 só pode ser associado a um documento OpenAPI ou a uma configuração de serviço gRPC. Reserve um novo nome de anfitrião do Cloud Run para cada documento.

1. Certifique-se de que a CLI gcloud está autorizada a aceder aos seus dados e serviços.
   1. Inicie sessão.

      gcloud auth login

   2. No novo separador do navegador apresentado, escolha uma conta com a função de Editor ou Proprietário no projeto que criou para implementar o ESPv2 no Cloud Run. Google Cloud
2. Defina a região.

   gcloud config set run/region us-central1

3. Implemente a imagem de exemplo gcr.io/cloudrun/hello no Cloud Run. Substitua ESPv2_CLOUD_RUN_SERVICE_NAME pelo nome que quer usar para o serviço.

   gcloud run deploy ESPv2_CLOUD_RUN_SERVICE_NAME \
       --image="gcr.io/cloudrun/hello" \
       --allow-unauthenticated \
       --platform managed \
       --project=ESPv2_PROJECT_ID
   

   Após a conclusão com êxito, o comando apresenta uma mensagem semelhante à seguinte:

   Service [ESPv2_CLOUD_RUN_SERVICE_NAME] revision [ESPv2_CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

   Por exemplo, se definir ESPv2_CLOUD_RUN_SERVICE_NAME como gateway:

   Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

   Neste exemplo, https://gateway-12345-uc.a.run.app é o CLOUD_RUN_SERVICE_URL e gateway-12345-uc.a.run.app é o ESPv2_CLOUD_RUN_HOSTNAME.

4. Tome nota de ESPv2_CLOUD_RUN_SERVICE_NAME e ESPv2_CLOUD_RUN_HOSTNAME. Posteriormente, implementa o ESPv2 no serviço do ESPv2_CLOUD_RUN_SERVICE_NAME Cloud Run. Especifica ESPv2_CLOUD_RUN_HOSTNAME no campo host do seu documento OpenAPI.

Configurar pontos finais

O exemplo bookstore-grpc contém os ficheiros que tem de copiar localmente e configurar.

1. Crie um ficheiro de descritor protobuf autónomo a partir do ficheiro .proto do seu serviço:
   1. Guarde uma cópia de bookstore.proto do repositório de exemplo no seu diretório de trabalho atual. Este ficheiro define a API do serviço Bookstore.
   2. Crie o seguinte diretório no seu diretório de trabalho: mkdir generated_pb2
   3. Crie o ficheiro de descritor, api_descriptor.pb, usando o compilador de buffers de protocolo protoc. Execute o seguinte comando no diretório onde guardou bookstore.proto:

      python3 -m grpc_tools.protoc \
          --include_imports \
          --include_source_info \
          --proto_path=. \
          --descriptor_set_out=api_descriptor.pb \
          --python_out=generated_pb2 \
          --grpc_python_out=generated_pb2 \
          bookstore.proto

      No comando anterior, --proto_path está definido como o diretório de trabalho atual. No seu ambiente de compilação gRPC, se usar um diretório diferente para os ficheiros de entrada .proto, altere --proto_path para que o compilador pesquise o diretório onde guardou bookstore.proto.

2. Crie um ficheiro de texto denominado api_config.yaml no seu diretório de trabalho atual (o mesmo diretório que contém bookstore.proto). Para maior conveniência, esta página refere-se ao documento de configuração da API gRPC por esse nome de ficheiro, mas pode atribuir-lhe outro nome, se preferir. Adicione o seguinte conteúdo ao ficheiro:

   # The configuration schema is defined by the service.proto file.
   # https://github.com/googleapis/googleapis/blob/master/google/api/service.proto
   
   type: google.api.Service
   config_version: 3
   name: CLOUD_RUN_HOSTNAME
   title: Cloud Endpoints + Cloud Run gRPC
   apis:
     - name: endpoints.examples.bookstore.Bookstore
   usage:
     rules:
     # ListShelves methods can be called without an API Key.
     - selector: endpoints.examples.bookstore.Bookstore.ListShelves
       allow_unregistered_calls: true
   backend:
     rules:
       - selector: "*"
         address: grpcs://BACKEND_HOST_NAME
   

   A indentação é importante para o formato YAML. Por exemplo, o campo name tem de estar ao mesmo nível que type.

3. No campo name, especifique CLOUD_RUN_HOSTNAME, a parte do nome de anfitrião do URL que foi reservada acima em Reservar um nome de anfitrião do Cloud Run. Não inclua o identificador do protocolo, como https:// ou grpcs://.

4. No campo address na secção backend.rules, substitua BACKEND_HOST_NAME pelo serviço Cloud Run gRPC Bookstore real criado em Antes de começar.

   Nota: para usar o gRPC com TLS no Cloud Run, o campo address tem de ter o esquema grpcs:// em vez de https://.

5. Tenha em atenção o valor da propriedade title no ficheiro api_config.yaml:

   title: Cloud Endpoints + Cloud Run gRPC

   O valor da propriedade title torna-se o nome do serviço Endpoints depois de implementar a configuração.

6. Guarde o documento de configuração da API gRPC.

Consulte o artigo Configurar pontos finais para mais informações.

Configure os requisitos da chave da API

Para controlar o acesso à sua API, pode configurar o Cloud Endpoints para exigir uma chave de API. Os clientes que chamam a sua API têm de fornecer uma chave da API associada ao seu projeto. Consulte o artigo Restringir o acesso à API com chaves da API para mais informações.

Se ainda não tiver uma chave da API associada ao Google Cloud projeto que está a usar neste guia de início rápido, pode adicionar uma seguindo os passos em Criar uma chave da API.

Para testar a aplicação da chave da API através de uma chave da API associada ao seu Google Cloud projeto, siga estes passos:

1. Ative o suporte de chaves da API para o seu serviço. Introduza o seguinte comando, em que:
   • CLOUD_RUN_HOSTNAME é o componente do nome do anfitrião do URL designado para o serviço ESPv2 no Cloud Run. É usado no campo host do documento OpenAPI para especificar a localização onde a API está alojada.

   gcloud services enable CLOUD_RUN_HOSTNAME

2. Abra o ficheiro de configuração do serviço gRPC do seu projeto.
3. Adicione uma secção usage ao ficheiro.
4. Para desativar o requisito de chave de API para todos os métodos, adicione uma regra allow_unregistered_calls com um seletor de carateres universais ("*") na secção usage.

   usage:
     rules:
     # Allow all methods to be called without an API key.
     - selector: "*"
       allow_unregistered_calls: true

5. Para desativar o requisito da chave da API para um método específico, defina o selector para o nome totalmente qualificado desse método em vez de um caráter universal.

   usage:
     rules:
     # Allow the ListShelves method to be called without an API key.
     - selector: "endpoints.examples.bookstore.Bookstore.ListShelves"
       allow_unregistered_calls: true

6. Depois de modificar o ficheiro de configuração do serviço, implemente a configuração atualizada no seu serviço Endpoints.

Chamar uma API através de uma chave da API

A chamada de uma API varia consoante a chamada seja feita a partir de um cliente gRPC ou de um cliente HTTP.

Clientes gRPC

Se um método requer uma chave API, os clientes gRPC têm de transmitir o valor da chave como x-api-key metadados com a chamada do método.

Python

def run(
    host, port, api_key, auth_token, timeout, use_tls, servername_override, ca_path

Java

private static final class Interceptor implements ClientInterceptor {
  private final String apiKey;
  private final String authToken;

  private static Logger LOGGER = Logger.getLogger("InfoLogging");

  private static Metadata.Key<String> API_KEY_HEADER =
      Metadata.Key.of("x-api-key", Metadata.ASCII_STRING_MARSHALLER);
  private static Metadata.Key<String> AUTHORIZATION_HEADER =
      Metadata.Key.of("authorization", Metadata.ASCII_STRING_MARSHALLER);

  public Interceptor(String apiKey, String authToken) {
    this.apiKey = apiKey;
    this.authToken = authToken;
  }

  @Override
  public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
      MethodDescriptor<ReqT,RespT> method, CallOptions callOptions, Channel next) {
    LOGGER.info("Intercepted " + method.getFullMethodName());
    ClientCall<ReqT, RespT> call = next.newCall(method, callOptions);

    call = new ForwardingClientCall.SimpleForwardingClientCall<ReqT, RespT>(call) {
      @Override
      public void start(Listener<RespT> responseListener, Metadata headers) {
        if (apiKey != null && !apiKey.isEmpty()) {
          LOGGER.info("Attaching API Key: " + apiKey);
          headers.put(API_KEY_HEADER, apiKey);
        }
        if (authToken != null && !authToken.isEmpty()) {
          System.out.println("Attaching auth token");
          headers.put(AUTHORIZATION_HEADER, "Bearer " + authToken);
        }
        super.start(responseListener, headers);
      }
    };
    return call;
  }
}

Ir

func main() {
	flag.Parse()

	// Set up a connection to the server.
	conn, err := grpc.Dial(*addr, grpc.WithInsecure())
	if err != nil {
		log.Fatalf("did not connect: %v", err)
	}
	defer conn.Close()
	c := pb.NewGreeterClient(conn)

	if *keyfile != "" {
		log.Printf("Authenticating using Google service account key in %s", *keyfile)
		keyBytes, err := ioutil.ReadFile(*keyfile)
		if err != nil {
			log.Fatalf("Unable to read service account key file %s: %v", *keyfile, err)
		}

		tokenSource, err := google.JWTAccessTokenSourceFromJSON(keyBytes, *audience)
		if err != nil {
			log.Fatalf("Error building JWT access token source: %v", err)
		}
		jwt, err := tokenSource.Token()
		if err != nil {
			log.Fatalf("Unable to generate JWT token: %v", err)
		}
		*token = jwt.AccessToken
		// NOTE: the generated JWT token has a 1h TTL.
		// Make sure to refresh the token before it expires by calling TokenSource.Token() for each outgoing requests.
		// Calls to this particular implementation of TokenSource.Token() are cheap.
	}

	ctx := context.Background()
	if *key != "" {
		log.Printf("Using API key: %s", *key)
		ctx = metadata.AppendToOutgoingContext(ctx, "x-api-key", *key)
	}
	if *token != "" {
		log.Printf("Using authentication token: %s", *token)
		ctx = metadata.AppendToOutgoingContext(ctx, "Authorization", fmt.Sprintf("Bearer %s", *token))
	}

	// Contact the server and print out its response.
	name := defaultName
	if len(flag.Args()) > 0 {
		name = flag.Arg(0)
	}
	r, err := c.SayHello(ctx, &pb.HelloRequest{Name: name})
	if err != nil {
		log.Fatalf("could not greet: %v", err)
	}
	log.Printf("Greeting: %s", r.Message)
}

Node.js

const makeGrpcRequest = (JWT_AUTH_TOKEN, API_KEY, HOST, GREETEE) => {
  // Uncomment these lines to set their values
  // const JWT_AUTH_TOKEN = 'YOUR_JWT_AUTH_TOKEN';
  // const API_KEY = 'YOUR_API_KEY';
  // const HOST = 'localhost:50051'; // The IP address of your endpoints host
  // const GREETEE = 'world';

  // Import required libraries
  const grpc = require('@grpc/grpc-js');
  const protoLoader = require('@grpc/proto-loader');
  const path = require('path');

  // Load protobuf spec for an example API
  const PROTO_PATH = path.join(__dirname, '/protos/helloworld.proto');

  const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
    keepCase: true,
    longs: String,
    enums: String,
    defaults: true,
    oneofs: true,
  });

  const protoObj = grpc.loadPackageDefinition(packageDefinition).helloworld;

  // Create a client for the protobuf spec
  const client = new protoObj.Greeter(HOST, grpc.credentials.createInsecure());

  // Build gRPC request
  const metadata = new grpc.Metadata();
  if (API_KEY) {
    metadata.add('x-api-key', API_KEY);
  } else if (JWT_AUTH_TOKEN) {
    metadata.add('authorization', `Bearer ${JWT_AUTH_TOKEN}`);
  }

  // Execute gRPC request
  client.sayHello({name: GREETEE}, metadata, (err, response) => {
    if (err) {
      console.error(err);
    }

    if (response) {
      console.log(response.message);
    }
  });
};

Clientes HTTP

Se estiver a usar a funcionalidade de transcodificação de HTTP do Cloud Endpoints para gRPC, os clientes HTTP podem enviar a chave como um parâmetro de consulta da mesma forma que o fazem para os serviços OpenAPI.

Implementação da 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.

1. Certifique-se de que está no diretório onde se encontram os ficheiros api_descriptor.pb e api_config.yaml.
2. Confirme que o projeto predefinido que a ferramenta de linha de comandos gcloud está a usar atualmente é o projeto Google Cloud no qual quer implementar a configuração do Endpoints. Valide o ID do projeto devolvido pelo seguinte comando para se certificar de que o serviço não é criado no projeto errado.

   gcloud config list project
   

   Se precisar de alterar o projeto predefinido, execute o seguinte comando:

   gcloud config set project YOUR_PROJECT_ID
   

3. Implemente o ficheiro proto descriptor e o ficheiro de configuração através da CLI do Google Cloud:

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

   À medida que cria e configura o serviço, o Service Management envia informações para o terminal. Quando a implementação estiver concluída, é apresentada uma mensagem semelhante à seguinte:

   Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

   CONFIG_ID é o ID exclusivo da configuração do serviço Endpoints criado pela implementação. Por exemplo:

   Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
   

   No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço e bookstore.endpoints.example-project.cloud.goog é o nome do serviço. O ID de configuração do serviço consiste numa indicação de data/hora seguida de um número de revisão. Se implementar novamente a configuração dos Endpoints no mesmo dia, o número de revisão é incrementado no ID de configuração do serviço.

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.

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

Consulte o artigo Implementar a configuração dos Endpoints para ver informações adicionais.

Criar uma nova imagem do ESPv2

Crie a configuração do serviço Endpoints numa nova imagem do Docker do ESPv2. Posteriormente, vai implementar esta imagem no serviço do Cloud Run reservado.

Nota:

Este passo é obrigatório.

A configuração do serviço tem de ser incorporada numa nova imagem do Docker porque o Cloud Run é um serviço de dimensionamento para zero. Isto significa que, quando não existe tráfego, todas as instâncias são eliminadas. Quando o tráfego aumenta, são criadas novas instâncias a pedido. Este tipo de criação de instância de serviço também é denominado início a frio. Consulte a documentação sobre a concorrência do Cloud Run para mais informações.

Se a imagem do Docker não tivesse a configuração do serviço incorporada, o Cloud Run teria de fazer duas chamadas API para o Google ServiceManagement no arranque a frio. Estas chamadas são contabilizadas na sua quota da API Google ServiceManagement.

Ao incorporar a configuração do serviço na imagem Docker do ESPv2, remove as duas chamadas API e evita afetar a contagem de quotas para o serviço Google ServiceManagement. Este passo também acelera a criação da nova instância de serviço e reduz a latência dos pedidos que aguardam a nova instância.

Tem de executar novamente todo este passo e reimplementar o novo contentor:

• Sempre que modifica e reimplementa a configuração do serviço Endpoints. Caso contrário, as alterações à configuração do serviço não são propagadas para o ESPv2.
• Quando é lançada uma nova versão do ESPv2. Caso contrário, a versão mais antiga do ESPv2 permanece implementada.

Para criar a configuração do serviço numa nova imagem Docker do ESPv2:

1. Transfira este script para a sua máquina local onde a CLI gcloud está instalada.

   Nota:

   Este script requer o bash. Se não estiver a usar o macOS/Linux, pode executá-lo no Cloud Shell, Compute Engine ou subsistema Windows para Linux.

2. Execute o script com o seguinte comando:

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s ESPv2_CLOUD_RUN_HOSTNAME \
       -c CONFIG_ID -p ESPv2_PROJECT_ID

   Nota:

   Este script foi concebido para criar uma pasta no diretório /tmp. Certifique-se de que tem acesso de escrita ao diretório /tmp quando executar este script.

   Se o acesso de escrita não estiver disponível para o diretório /tmp, tem de modificar o script para especificar um diretório alternativo onde tenha o acesso necessário para criar pastas.

   Para ESPv2_CLOUD_RUN_HOSTNAME, especifique o nome do anfitrião do URL que reservou acima em Reservar um nome do anfitrião do Cloud Run. Não inclua o identificador de protocolo, https://.

   Por exemplo:

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s gateway-12345-uc.a.run.app \
       -c 2019-02-01r0 -p your-project-id

3. O script usa o comando gcloud para transferir a configuração do serviço, criar a configuração do serviço numa nova imagem do ESPv2 e carregar a nova imagem para o registo de contentores do seu projeto. O script usa automaticamente a versão mais recente do ESPv2, indicada por ESPv2_VERSION no nome da imagem de saída. A imagem de saída é carregada para:

   gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_CLOUD_RUN_HOSTNAME-CONFIG_ID

   Por exemplo:

   gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"

   Nota:

   Transmita a flag -z ao script para gerar a imagem numa localização do registo diferente.

   Por exemplo, para enviar a imagem ESPv2 gerada para um centro de dados da União Europeia, transmita -z eu ao script.

Implementar o contentor do ESPv2

1. Implemente o serviço do Cloud Run do ESPv2 com a nova imagem criada acima. Substitua CLOUD_RUN_SERVICE_NAME pelo mesmo nome do serviço do Cloud Run que usou quando reservou originalmente o nome do anfitrião acima em Reservar um nome do anfitrião do Cloud Run:

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --allow-unauthenticated \
     --platform managed \
     --project=ESPv2_PROJECT_ID

   Nota:

   Se o seu serviço gRPC usar qualquer protocolo de streaming, adicione a flag --use-http2 ao comando gcloud run deploy. Atualmente, esta flag só é suportada em gcloud beta run. Adicione esta flag quando implementar o ESPv2 e os serviços do Cloud Run de back-end gRPC.

2. Se quiser configurar os Endpoints para usar opções de inicialização do ESPv2 adicionais, como ativar o CORS, pode transmitir os argumentos na variável de ambiente ESPv2_ARGS:

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
     --allow-unauthenticated \
     --platform managed \
     --project ESPv2_PROJECT_ID

   Para mais informações e exemplos sobre a definição da variável de ambiente ESPv2_ARGS, incluindo a lista de opções disponíveis e informações sobre como especificar várias opções, consulte Flags do proxy de serviço extensível V2.

3. Conceda autorização ao ESPv2 para invocar os seus serviços do Cloud Run. Execute o seguinte comando para cada serviço. No seguinte comando:
   Nota:

   Este passo não é necessário se o serviço do Cloud Run do ESPv2 for implementado sem usar a flag --service-account e o serviço de back-end BACKEND_SERVICE_NAME for implementado no projeto ESPv2_PROJECT_NUMBER.

   • Substitua BACKEND_SERVICE_NAME pelo nome do serviço do Cloud Run que está a ser invocado. Se estiver a usar o serviço criado através da implementação de `gcr.io/endpointsv2/python-grpc-bookstore-server:2`, use python-grpc-bookstore-server como este valor.
   • Substitua ESPv2_PROJECT_NUMBER pelo número do projeto que criou para o ESPv2. Uma forma de encontrar esta informação é aceder à página IAM na consola e encontrar a conta de serviço de computação predefinida, que é a conta de serviço usada na flag `member`. Google Cloud

   gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
     --member "serviceAccount:[e-mail]" \
     --role "roles/run.invoker" \
     --platform managed \
     --project BACKEND_PROJECT_ID

Para mais informações, consulte o artigo Gerir o acesso através da IAM.

Enviar pedidos para a API

Para enviar pedidos para a API de exemplo, pode usar um cliente gRPC de exemplo escrito em Python.

1. Clone o repositório Git onde o código do cliente gRPC está alojado:

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

2. Altere o diretório de trabalho:

   cd python-docs-samples/endpoints/bookstore-grpc/

3. Instale dependências:

   pip3 install virtualenv
   virtualenv env
   source env/bin/activate
   pip3 install -r requirements.txt

4. Envie um pedido para a API de exemplo:

   python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true

   Especifique o nome do anfitrião do seu serviço do Cloud Run do ESPv2 em CLOUD_RUN_HOSTNAME, sem o identificador do protocolo. Por exemplo:

   python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true

   • 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.

   • Consulte os registos de pedidos da sua API na página do explorador de registos.

     Aceda à página do Explorador de registos

Se não receber 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

1. Veja os gráficos de atividade da sua API na página Endpoints > Service na Google Cloud consola.

   Veja gráficos de atividade 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.

   Veja os registos de pedidos de pontos finais

Limpar

Para evitar incorrer em cobranças na sua Google Cloud conta pelos recursos usados nesta página, siga estes passos.

Consulte o artigo Eliminar uma API e instâncias de API para obter informações sobre como parar os serviços usados por este tutorial.

O que se segue?

• Saiba mais sobre o Cloud Run
• Saiba mais sobre a implementação da configuração dos Endpoints
• Partilhe a sua API com outro programador
• Saiba mais acerca da autenticação
• Transcodificação de HTTP/JSON para gRPC
• Saiba mais sobre as opções de apoio técnico da comunidade