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. Create a self-contained protobuf descriptor file from your service .proto file:
   1. Save a copy of bookstore.proto from the example repository to your current working directory. This file defines the Bookstore service's API.
   2. Create the following directory under your working directory: mkdir generated_pb2
   3. Create the descriptor file, api_descriptor.pb, by using the protoc protocol buffers compiler. Run the following command in the directory where you saved 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

      In the preceding command, --proto_path is set to the current working directory. In your gRPC build environment, if you use a different directory for .proto input files, change --proto_path so the compiler searches the directory where you saved bookstore.proto.

2. Create a text file called api_config.yaml in your current working directory (the same directory that contains bookstore.proto). For convenience, this page refers to the gRPC API configuration document by that file name, but you can name it something else if you prefer. Add the following contents to the file:

   # 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
   

   Indentation is important for yaml format. For example the name field must be at the same level as type.

3. In the name field, specify CLOUD_RUN_HOSTNAME, the hostname portion of the URL that was reserved above in Reserving a Cloud Run hostname. Don't include the protocol identifier, such as https:// or grpcs://.

4. In the address field in the backend.rules section, replace BACKEND_HOST_NAME with the actual gRPC Bookstore Cloud Run service created in Before you begin.

   Note: To use gRPC with TLS on Cloud Run, the address field must have the scheme grpcs:// instead of https://.

5. Note the value of the title property in the api_config.yaml file:

   title: Cloud Endpoints + Cloud Run gRPC

   The value of the title property becomes the name of the Endpoints service after you deploy the configuration.

6. Save your gRPC API configuration document.

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

To send requests to the sample API, you can use a sample gRPC client written in Python.

1. Clone the git repo where the gRPC client code is hosted:

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

2. Change your working directory:

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

3. Install dependencies:

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

4. Send a request to the sample API:

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

   Specify the hostname of your ESPv2 Cloud Run service in CLOUD_RUN_HOSTNAME, without the protocol identifier. For example:

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

   • Look at the activity graphs for your API in the Endpoints > Services page.

     Go to the Endpoints Services page

     It may take a few moments for the request to be reflected in the graphs.

   • Look at the request logs for your API in the Logs Explorer page.

     Go to the Logs Explorer page

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