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

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]
    
  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