Como sincronizar a documentação personalizada por meio de uma API

OpenAPI | gRPC

A partir de 21 de março de 2022, o Portal do Cloud Endpoints vai ser descontinuado. O Portal do Cloud Endpoints não estará mais disponível após 21 de março de 2023. O tráfego da API gerenciado pelo Cloud Endpoints não é afetado por essa mudança. Para mais informações, consulte Descontinuação de recursos.

O portal fornece uma API especial para sincronizar o conteúdo personalizado. Para chamar essa API:

1. Sincronize seu conteúdo personalizado manualmente pelo menos uma vez.
2. Crie uma conta de serviço com a autorização e a chave apropriadas.
3. Faça a solicitação HTTP para sincronizar o conteúdo.

Neste documento, fornecemos instruções para criar uma conta de serviço e exemplos de como fazer a solicitação por meio do Python ou da linha de comando.

Como criar uma conta de serviço autorizada

Para usar uma API para sincronizar o conteúdo personalizado, você precisa de uma conta de serviço com a autorização e a chave apropriadas. Para criar a conta de serviço, conceder a ela o papel adequado e conseguir o arquivo de chave necessário, siga estas instruções:

Console

1. Crie uma conta de serviço:

   1. No Console do Google Cloud, acesse a página Contas de serviço.

      Acesse Contas de serviço

   2. Selecione o projeto em que a API foi configurada para uso.

   3. Clique em + Criar conta de serviço.

   4. No campo Nome da conta de serviço, insira um nome. O console do Google Cloud preenche o campo ID da conta de serviço com base nesse nome.

   5. Opcional: preencha o campo Descrição da conta de serviço.

   6. Clique em Criar e continuar.

   7. Clique em Concluído para terminar a criação da conta de serviço.

      Não feche a janela do navegador. Você vai usá-la na próxima etapa.

2. Faça o download de uma chave JSON para a conta de serviço que você acabou de criar:

   1. No console do Google Cloud, clique no endereço de e-mail da conta de serviço que você criou.
   2. Clique em Chaves.
   3. Clique em Adicionar chave e em Criar nova chave.

   4. Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.

      Armazene o arquivo de chave com segurança, porque ele pode ser usado para autenticar como sua conta de serviço. Mova e renomeie esse arquivo como quiser.

   5. Clique em Fechar.

3. No console do Google Cloud, acesse a página Endpoints > Serviços do seu projeto.

   Página Serviços do Endpoints

4. Clique no nome da API que receberá a sincronização de conteúdo personalizado para alterar as respectivas permissões de acesso.

5. Se o painel lateral "Permissões" não estiver aberto, clique em + Permissões.

6. Para conceder à conta de serviço criada acesso à API, insira o endereço de e-mail dela no campo Adicionar membros.

7. Na lista suspensa Selecionar um papel, clique em Service Management e selecione Editor de configuração do serviço referente à conta.

Parabéns! Você criou a conta de serviço, fez o download da sua chave privada em um arquivo JSON e atribuiu o devido papel à conta de serviço.

gcloud

1. Insira o seguinte comando para exibir os IDs dos seus projetos do Google Cloud:

   gcloud projects list
   

2. Substitua [YOUR_PROJECT_ID] no comando a seguir para definir o projeto que contém sua API como padrão:

   gcloud config set project [YOUR_PROJECT_ID]
   

   Importante: é preciso criar a conta de serviço no mesmo projeto em que está a API.

3. Verifique se a Google Cloud CLI (gcloud) está autorizada a acessar seus dados e serviços no Google Cloud:

   gcloud auth login
   

   Se você tiver mais de uma conta, escolha a que está no projeto do Google Cloud e que contém a API. Se você executar gcloud auth list, a conta selecionada será mostrada como a ativa para o projeto.

4. Para criar uma conta de serviço, execute o comando a seguir e substitua [SERVICE_ACCOUNT_NAME] e [Service Account to Sync Custom Content] pelos nome e nome de exibição que você quer usar:

   gcloud iam service-accounts create [SERVICE_ACCOUNT_NAME] \
     --display-name "[Service Account to Sync Custom Content]"
   

   O comando atribui um endereço de e-mail para a conta de serviço no seguinte formato:

   [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
   

   Esse endereço de e-mail é necessário nos comandos subsequentes.

5. Crie um arquivo de chave da conta de serviço, substituindo [KEY_FILE] pelo nome do arquivo da chave:

   gcloud iam service-accounts keys create ~/[KEY_FILE] \
     --iam-account [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
   

6. Para conceder à conta de serviço o acesso à API com o conteúdo personalizado, execute o seguinte comando, substituindo [YOUR_SERVICE_NAME] pelo nome da API com o conteúdo personalizado:

   gcloud endpoints services add-iam-policy-binding [SERVICE-NAME] \
         --member=serviceAccount:[SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com \
         --role roles/servicemanagement.configEditor
   

Como enviar uma solicitação para sincronizar o conteúdo personalizado

Nos exemplos a seguir, mostramos como fazer uma solicitação para sincronizar o conteúdo personalizado. A solicitação será semelhante a:

 POST https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content/

Substitua [YOUR_PROJECT_ID] e [YOUR_SERVICE_NAME] pelos valores apropriados. Quando a solicitação é concluída com sucesso, a resposta inclui o código de status HTTP 200.

Nos próximos exemplos, mostramos como conseguir um token de acesso dos servidores de autorização do Google e usá-lo para fazer a solicitação ao endpoint do portal por meio do Python ou da linha de comando:

Python

1. Instale as bibliotecas necessárias do Python:

       pip install --upgrade google-auth

2. Para criar um objeto Credentials com as credenciais da conta de serviço e os escopos exigidos pelo endpoint e fazer a solicitação de sincronização do conteúdo, substitua [YOUR_PROJECT_ID], /path/to/service.json e [YOUR_SERVICE_NAME] pelos valores apropriados no seguinte script:

   from google.oauth2 import service_account
   from google.auth.transport.requests import AuthorizedSession
   
   SCOPES = ["https://www.googleapis.com/auth/service.management.readonly"]
   SERVICE_ACCOUNT_FILE = "/path/to/service.json"
   PROJECT_ID = "[YOUR_PROJECT_ID]"
   SERVICE_NAME = "[YOUR_SERVICE_NAME]"
   
   credentials = service_account.Credentials.from_service_account_file(
      SERVICE_ACCOUNT_FILE, scopes=SCOPES)
   authed_session = AuthorizedSession(credentials)
   endpoint =
   "https://endpointsportal.%s.cloud.goog/api/v1/%s/custom-content" % (PROJECT_ID, SERVICE_NAME)
   result = authed_session.post(endpoint)
   print result

Linha de comando

1. Abra o Cloud Shell ou uma janela do terminal se você tiver a CLI gcloud instalada no computador Linux.
2. Para autenticar-se na conta de serviço, substitua [KEY_FILE] abaixo pelo caminho do arquivo da chave da conta de serviço e execute o comando:

   gcloud auth activate-service-account --key-file [KEY_FILE]

3. Receba um token de autorização usando a conta de serviço:

   ACCESS_TOKEN=$(gcloud auth print-access-token)

4. Ao chamar a API, passe o valor do token como token do portador em um cabeçalho de autorização. Substitua [YOUR_PROJECT_ID] e [YOUR_SERVICE_NAME] pelos valores apropriados:

   curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \
   https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content