Configuração do Cloud Endpoints

Nesta página, descrevemos os arquivos de configuração necessários para criar um serviço gRPC gerenciado pelo Endpoints.

Pré-requisitos

Como ponto de partida, nesta página presume-se que você:

Como escolher o nome do serviço

O nome configurado no arquivo YAML de configuração da gRPC API é utilizado pelo Cloud Endpoints como o nome do serviço.

No Google Cloud, o nome do serviço da API precisa ser exclusivo. Como o Endpoints usa nomes compatíveis com o DNS para identificar serviços, recomendamos que você use o nome de domínio ou de subdomínio da API como o nome do serviço. Com essa abordagem, o nome do serviço que aparece na página Serviços do Endpoints corresponde ao nome usado nas solicitações para a API. Além disso, se o nome do serviço e o nome do domínio forem os mesmos, será possível criar um portal do Cloud Endpoints para os usuários da API. O Endpoints tem os seguintes requisitos para o nome de serviço:

  • O comprimento máximo do nome do domínio é de 253 caracteres.
  • O nome de domínio precisa começar com uma letra minúscula.
  • Cada seção no nome de domínio, delimitada por pontos, apresenta os seguintes requisitos:
    • Precisa começar com uma letra minúscula.
    • Não pode terminar com um traço.
    • Os outros caracteres podem ser letras minúsculas, números ou traços.
    • O comprimento máximo é de 63 caracteres.

É possível registrar seu próprio domínio personalizado, como example.com, ou usar um domínio gerenciado pelo Google.

Usar um domínio gerenciado pelo Google

O Google é proprietário do domínio cloud.goog e o gerencia. Se você quiser usar um domínio gerenciado pelo Google, use o ID do projeto do Google Cloud como parte do nome do serviço. Como projetos do Google Cloud têm um ID exclusivo globalmente, esse requisito garante que você tenha um nome de serviço exclusivo. Se você quiser usar o domínio cloud.goog, o nome do serviço deverá estar no formato abaixo, em que YOUR_API_NAME é o nome da API e YOUR_PROJECT_ID é o ID do projeto do Google Cloud:

YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog`

Para usar esse domínio como o nome de domínio da API, leia Como configurar o DNS no domínio cloud.goog.

Usar um domínio personalizado

Se você não quer usar um domínio gerenciado pelo Google, saiba que é possível usar um domínio personalizado (myapi.mycompany.com, por exemplo), desde que você tenha autorização. Antes de implantar a configuração da API, siga as etapas abordadas em Verificar a propriedade do domínio.

Como configurar o buffer do protocolo

  1. Crie um arquivo .proto para seu serviço. Leia o Guia do desenvolvedor
    para saber os detalhes.

  2. Compile os buffers de protocolo usando o compilador protoc da linguagem. 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 ambiente da versão do gRPC, caso você use um diretório diferente para arquivos de entrada .proto, mude --proto_path para que o compilador pesquise o diretório em que salvou o arquivo .proto.

    Se o comando protoc para gerar o arquivo descritor falhar, verifique se:

    • sua versão protoc está atualizada;
    • você especificou o --proto_path ou o formato abreviado -I para os diretórios raiz dos arquivos .proto importados. Para mais informações, veja a documentação dos buffers de protocolo (em inglês);
    • você especificou --include_imports.

    Se você quiser que seus clientes acessem o serviço gRPC usando HTTP com JSON, especifique como os dados serão convertidos de HTTP com JSON para gRPC. Recomendamos que você anote as APIs definidas no arquivo .proto. Leia Como transcodificar HTTP/JSON em gRPC para mais informações.

Como configurar o arquivo de configuração do serviço gRPC

Você precisa criar um arquivo YAML de configuração do serviço gRPC. Você especifica o nome do serviço e as restrições de uso, como a exigência de uma chave de API nesse arquivo. Você pode usar o arquivo api_config.yaml da amostra do Bookstore como modelo.

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

  2. Digite o nome do seu serviço no campo name. Exemplo:

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

  3. Digite o título que é exibido na página Endpoints > Services no Console do Google Cloud. Exemplo:

    title: Bookstore gRPC API

  4. Digite o nome da API no campo apis:name. O texto digitado precisa corresponder exatamente ao nome da API totalmente qualificado do arquivo .proto. Exemplo:

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

  5. Configure o restante do arquivo. 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 Regras e seletores para mais informações.

A seguir

Amostras extras do gRPC