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

Seu portal fornece uma API especial para sincronizar seu 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. No Console do Cloud, abra a página Contas de serviço.

    Acesse a página Contas de serviço

  2. Clique em Selecionar um projeto.

  3. Selecione o projeto e clique em Abrir.

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

  5. No campo Nome da conta de serviço, insira o nome de exibição da conta de serviço.

  6. Marque a caixa de seleção Fornecer uma nova chave privada.

  7. Em Tipo de chave, use o tipo padrão, JSON.

  8. Clique em Salvar.

  9. Uma caixa de diálogo mostra as informações da chave. Feche a caixa de diálogo para continuar.

  10. No Console do Cloud, acesse a página Endpoints > Serviços do seu projeto.

    Página Serviços do Endpoints

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

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

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

  14. 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 o SDK do Cloud (gcloud) está autorizado 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 a partir das credenciais da conta de serviço e dos escopos que o endpoint exige e fazer a solicitação para sincronizar o conteúdo, substitua [YOUR_PROJECT_ID], /path/to/service.json e [YOUR_SERVICE_NAME] pelos valores apropriados nas seguintes 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 o SDK do Cloud estiver instalado no seu 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