Configurar o Cloud Endpoints

Esta página descreve os ficheiros de configuração necessários para criar um serviço gRPC gerido pelos Endpoints.

Pré-requisitos

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

Escolher o nome do serviço

O Cloud Endpoints usa o nome que configura no ficheiro YAML de configuração da API gRPC como o nome do seu serviço.

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

  • The maximum length of the domain name is 253 characters.
  • The domain name must start with a lowercase letter.
  • Each section in the domain name, which is delimited by dots, has the following requirements:
    • Must start with a lowercase letter.
    • Must not end with a dash.
    • The remaining characters can be lowercase letters, numbers, or dashes.
    • The maximum length is 63 characters.

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

Utilize um domínio gerido pela Google

A Google é proprietária e gere o domínio cloud.goog. Se quiser usar um domínio gerido pela Google, tem de usar o ID do projeto como parte do nome do serviço. Google Cloud Uma vez que Google Cloud os projetos têm um ID do projeto exclusivo a nível global, este requisito garante que tem um nome de serviço exclusivo. Se quiser usar o domínio cloud.goog, o nome do serviço tem de estar no formato, em que YOUR_API_NAME é o nome da sua API e YOUR_PROJECT_ID é o ID do seu projetoGoogle Cloud :

YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog`

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

Use um domínio personalizado

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

Configurar o buffer de protocolo

  1. Crie um ficheiro .proto para o seu serviço. Leia o guia do programador
    para ver detalhes.

  2. Compile os buffers de protocolo usando o compilador protoc para o seu idioma. Por exemplo:

    protoc
  --proto_path=. \
  --include_imports \
  --include_source_info \
  --descriptor_set_out=api_descriptor.pb \
  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 o ficheiro .proto.

    Se o comando protoc para gerar o ficheiro de descritor falhar, certifique-se de que:

    • A versão do protoc está atualizada.
    • Especificou --proto_path ou a respetiva forma abreviada -I para os diretórios raiz dos ficheiros .proto importados. Pode saber mais na documentação sobre buffers do protocolo.
    • Especificou --include_imports.

    Se quiser que os seus clientes acedam ao seu serviço gRPC através de HTTP com JSON, tem de especificar como os dados são traduzidos de HTTP com JSON para gRPC. Recomendamos que anote as APIs definidas no seu ficheiro .proto. Leia o artigo Transcodificação de HTTP/JSON para gRPC para mais informações.

Configurar o ficheiro de configuração do serviço gRPC

Tem de criar um ficheiro YAML de configuração do serviço gRPC. Especifica o nome do serviço e as restrições de utilização, como exigir uma chave de API neste ficheiro. Pode usar o ficheiro api_config.yaml do exemplo da livraria como modelo.

  1. Guarde uma cópia de api_config.yaml.

  2. Introduza o nome do seu serviço no campo name. Por exemplo:

    name: bookstore.endpoints.example-project-12345.cloud.goog

  3. Introduza o título apresentado na página Endpoints > Services na consola Google Cloud . Por exemplo:

    title: Bookstore gRPC API

  4. Introduza o nome da API no campo apis:name. O texto que introduz tem de corresponder exatamente ao nome da API totalmente qualificado do seu ficheiro .proto. Por exemplo:

    apis:
  - name: endpoints.examples.bookstore.Bookstore

  5. Configure o resto do ficheiro. Por exemplo:

    #
# API usage restrictions.
#
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true

    Leia o artigo Regras e seletores para mais informações.

O que se segue?

Exemplos gRPC adicionais