Como configurar o 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ê tenha:

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.

O nome do serviço de API precisa ser exclusivo no GCP. Como o Endpoints usa nomes compatíveis com o DNS para identificar serviços, recomenda-se o uso do nome de domínio ou subdomínio da API como o nome do serviço. Com essa abordagem, o nome do serviço que aparecerá na página Serviços do Endpoints corresponderá ao nome usado nas solicitações para a API. Além disso, se o nome do serviço e 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 do 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 um domínio personalizado (como example.com) ou usar um domínio gerenciado pelo Google.

Usar um domínio gerenciado pelo Google

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

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 DNS no domínio cloud.goog.

Usar um domínio personalizado

Se não quiser usar um domínio gerenciado pelo Google, use um domínio personalizado (por exemplo, myapi.mycompany.com) que tenha autorização. Antes de implantar a configuração da API, siga as etapas 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 detalhes.

  2. Compile os buffers de protocolo usando o compilador protoc da linguagem. Por exemplo:

    protoc
      --proto_path=. \
      --include_imports \
      --include_source_info \
      --descriptor_set_out=api_descriptor.pb \
      bookstore.proto
    

    No comando acima, --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.

    Caso o comando protoc para gerar seu arquivo descritor falhe, verifique se estas condições são verdadeiras:

    • Sua versão do protoc está atualizada.
    • Você especificou o --proto_path ou a forma abreviada -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 quiser que os clientes acessem o serviço gRPC usando HTTP com JSON, você precisará especificar como os dados são convertidos de HTTP com JSON em gRPC. É recomendável anotar 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. Use o arquivo api_config.yaml do exemplo Bookstore como modelo.

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

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

    name: bookstore.endpoints.example-project-12345.cloud.goog
    
  3. Digite o título exibido na página Endpoints > Serviços no Console do GCP. Por 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. Por 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

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Cloud Endpoints com gRPC
Precisa de ajuda? Acesse nossa página de suporte.