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ê:
- um projeto do Google Cloud;
- conhecimento básico sobre como configurar um serviço da API gRPC;
- instalado o gRPC e as ferramentas dele. Lida Primeiros passos com o gRPC para mais detalhes.
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, que é delimitada por pontos, tem o seguinte
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íniocloud.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
Crie um arquivo
.proto
para seu serviço. Leia o Guia do desenvolvedor
para saber os detalhes.Compilar os buffers de protocolo usando o Compilador
protoc
(link em inglês) para seu idioma. 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.- sua versão
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.
Salve uma cópia de
api_config.yaml
.Digite o nome do seu serviço no campo
name
. Exemplo:name: bookstore.endpoints.example-project-12345.cloud.goog
Digite o título exibido na página Endpoints > Serviços no no console do Google Cloud. Exemplo:
title: Bookstore gRPC API
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
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
- Como implantar a configuração do Endpoints
- Implantar o back-end da API
- Como configurar a autenticação
Amostras extras do gRPC
- Versão Java da amostra do Bookstore
A amostra
getting-started-grpc
está disponível no GitHub nas seguintes linguagens: