Gerenciar escopos de métricas usando a API

Neste documento, descrevemos como usar os métodos de escopo de métricas na API Cloud Monitoring para gerenciar o escopo de métricas de um projeto do Google Cloud. Esta página é destinada a desenvolvedores e administradores de sistemas.

Para conectar uma conta da AWS ao escopo de métricas de um projeto do Google Cloud, use o Console do Google Cloud. Para mais informações, consulte Visualizar métricas para contas da AWS.

Antes de começar

  • Se você não conhece os termos escopo de métricas e projeto de escopo, consulte Escopos de métricas.

  • Verifique se o papel de gerenciamento de identidade e acesso (IAM, na sigla em inglês) no projeto de escopo permite modificar o escopo das métricas do projeto.

  • Para cada projeto que você quiser adicionar como um projeto monitorado, verifique se o papel do IAM permite que você modifique o escopo das métricas do projeto. Para informações sobre os papéis do IAM necessários, consulte Configurações do escopo das métricas.

  • Os métodos de escopo das métricas da API Cloud Monitoring que recuperam informações são síncronos; No entanto, as APIs que alteram o estado são assíncronas. Para informações sobre como determinar quando um método assíncrono é concluído e como determinar o status dele, consulte Métodos de API assíncrona.

Parâmetros do comando curl

É possível invocar as APIs de escopos de métricas diretamente. Nesta página, fornecemos exemplos de comandos que usam curl. Cada comando curl inclui um conjunto de argumentos seguido pelo URL de um recurso de API:

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

Os exemplos desta página dependem das seguintes variáveis de ambiente:

  • TOKEN: armazena o token de autenticação.
  • SCOPING_PROJECT_ID_OR_NUMBER: armazena o ID ou o número do projeto em um projeto de escopo de um escopo de métricas.
  • MONITORED_PROJECT_ID_OR_NUMBER: armazena o ID ou número de um projeto que será adicionado ou removido de um escopo de métricas.

Talvez você também precise especificar outros argumentos para elementos diferentes, como o tipo da solicitação HTTP. Por exemplo, -X DELETE. Como a solicitação padrão é GET, os exemplos não fazem essa especificação.

Para informações sobre a configuração necessária para os exemplos, consulte a configuração do comando curl.

Acessar um escopo de métricas

Para informações sobre um escopo de métricas, envie uma solicitação GET para o endpoint locations.global.metricsScopes.get:

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

Quando bem-sucedida, a resposta é um objeto MetricsScope.

Esse método não faz com que uma entrada seja gravada nos registros de auditoria do projeto de escopo. Para registrar essas ações no registro de auditoria, ative a Leitura de dados para a API Cloud Resource Manager. Para mais informações, consulte Como configurar registros de auditoria de acesso a dados.

Listar todos os escopos de métricas que incluem um projeto

Para uma lista de escopos de métricas que podem ver as métricas de um projeto, envie uma solicitação GET para o endpoint locations.global.metricsScopes.listMetricsScopesByMonitoredProject e inclua a consulta. que especifica o projeto.

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

Quando bem-sucedida, a resposta é uma matriz de objetos MetricsScope.

Esse método não faz com que uma entrada seja gravada nos registros de auditoria do projeto de escopo. Para registrar essas ações no registro de auditoria, ative a Leitura de dados para a API Cloud Resource Manager. Para mais informações, consulte Como configurar registros de auditoria de acesso a dados.

Adicionar um projeto a um escopo de métricas

Para adicionar um projeto do Google Cloud a um escopo de métricas, envie uma solicitação POST para o endpoint locations.global.metricsScopes.projects.create. No exemplo a seguir, o projeto identificado pela variável de ambiente MONITORED_PROJECT_ID_OR_NUMBER é adicionado como projeto monitorado:

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

A resposta desse método assíncrono é um objeto Operation.

Os aplicativos que chamam esse método precisam pesquisar o endpoint operation.get até que o valor do campo Operation.done seja true. Quando o campo Operation.done está definido como false, isso indica que a operação está em andamento. Para mais informações, consulte Comandos de API assíncronas.

Veja a seguir um exemplo de resposta ao adicionar um projeto monitorado:

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "GCP",
    "providerAccountId": "...",
    ...
  }
}

Na resposta anterior, o campo Operation.done está definido como true. Esse valor indica que o comando foi concluído. Como o comando foi concluído com sucesso, o campo Operation.response está definido e o valor é um objeto MonitoredProject. O campo response.name inclui o identificador do projeto de escopo e do projeto monitorado. O campo providerAccountId lista o nome do projeto monitorado.

Invocar esse método resulta em uma entrada nos registros de auditoria do projeto do escopo. Se você usar o Console do Cloud para adicionar um projeto a um escopo de métricas, essa ação não será gravada nos registros de auditoria. O Console do Cloud não invoca esse método de API.

Remover um projeto do escopo de métricas

Para remover um projeto do Google Cloud de um escopo de métricas, envie uma solicitação DELETE para o endpoint locations.global.metricsScopes.projects.delete:

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

A resposta a esse método assíncrono é um objeto Operation.

Os aplicativos que chamam esse método precisam pesquisar o endpoint operation.get até que o valor do campo Operation.done seja true. Quando o campo Operation.done está definido como false, isso indica que a operação está em andamento. Para mais informações, consulte Comandos de API assíncronas.

Veja a seguir um exemplo de resposta quando a remoção de um projeto monitorado é bem-sucedida:

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Na resposta anterior, o campo Operation.done está definido como true. Esse valor indica que o comando foi concluído. Como o comando foi concluído com sucesso, o campo Operation.response está definido e contém um campo @type.

Invocar esse método resulta em uma entrada nos registros de auditoria do projeto do escopo. Se você usar o Console do Cloud para remover um projeto de um escopo de métricas, essa ação não será gravada nos registros de auditoria. O Console do Cloud não invoca esse método de API.

Métodos de API assíncronos

Todos os métodos de escopo de métricas da API Cloud Monitoring que alteram o estado do sistema, por exemplo, o comando para adicionar um projeto de métricas a um escopo de métricas, são assíncronos. Para esses comandos, a resposta ao comando é um objeto Operation.

Os aplicativos que chamam um método de API assíncrono devem pesquisar o endpoint operation.get até que o valor do campo Operation.done seja true:

  • Quando done é false, a operação está em andamento.

    Para atualizar as informações de status, envie uma solicitação GET para o endpoint operation.get:

    curl -H "Authorization: Bearer ${TOKEN}" \
    https://monitoring.googleapis.com/v1/${OPERATION_NAME}
    

    No comando anterior, OPERATION_NAME é uma variável de ambiente que armazena o valor do campo Operation.name.

  • Quando done é true, a operação é concluída e o campo error ou response está definido:

    • error: quando definida, a operação assíncrona falha. O valor desse campo é um objeto Status que contém um código de erro do gRPC e uma mensagem de erro.
    • response: quando definido, a operação assíncrona é concluída e o valor reflete o resultado.

Configuração do comando curl

Nesta seção, descrevemos a configuração usada para criar os comandos curl neste documento.

Defina essas variáveis de ambiente para simplificar a criação de comandos curl:

  1. Crie a variável de ambiente para armazenar o ID ou o número do projeto de escopo:

    SCOPING_PROJECT_ID_OR_NUMBER=a-sample-project
    
  2. Opcional. Se você planeja adicionar ou remover projetos monitorados, configure a variável de ambiente com o ID ou o número do projeto monitorado:

    MONITORED_PROJECT_ID_OR_NUMBER=a-monitored-project
    
  3. Faça a autenticação no SDK do Cloud:

    gcloud auth login
    
  4. Opcional. Para evitar a necessidade de especificar o código do projeto com cada comando gcloud, defina o código do projeto como padrão usando o SDK do Cloud:

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}
    
  5. Crie um token de autorização e capture-o em uma variável de ambiente:

    TOKEN=`gcloud auth print-access-token`
    

    Os tokens são válidos por um tempo limitado. Se os comandos que funcionaram informarem repentinamente que você não está autenticado, emita esse comando novamente.

  6. Para verificar se você recebeu um token de acesso, faça o echo da variável TOKEN:

    echo ${TOKEN}
    ya29.GluiBj8o....