Neste guia, descrevemos como usar o APIs Explorer para testar os métodos da API Cloud Monitoring. O APIs Explorer é um widget anexado à página de referência da API REST de um método. Ele aparece como um painel com o título Testar esta API. A captura de tela a seguir mostra o painel como ele aparece para um método com apenas um parâmetro, name:
O APIs Explorer é uma excelente maneira de testar métodos na API Monitoring sem precisar escrever nenhum código. O widget apresenta um formulário que mostra os parâmetros de cada método. Preencha o formulário, clique no botão Executar e veja os resultados.
Também é possível ocultar o widget clicando no botão close ou expandi-lo para tela cheia clicando no botão fullscreen.
Botões Testar!
Na documentação, você pode ver botões Testar, como os seguintes:
Faça o teste!Quando você clica no botão, o APIs Explorer na página de referência do método é aberto. Normalmente, alguns parâmetros adequados para o exemplo são preenchidos. No entanto, talvez seja necessário editar alguns dos parâmetros para que correspondam ao seu próprio projeto, como o valor de [PROJECT_ID].
Para informações sobre como evitar e corrigir erros, consulte Solução de problemas.
Acessar o APIs Explorer
O APIs Explorer é anexado à página de referência de cada método da API REST. Para encontrar o widget, consulte a página de referência de um método, por exemplo, metricDescriptors.list.
Executar uma solicitação
A maioria dos métodos tem alguns parâmetros obrigatórios e outros opcionais. Os obrigatórios são marcados com uma barra vermelha até serem preenchidos. É possível executar uma solicitação depois de fornecer valores para todos os argumentos necessários.
O métodometricDescriptors.list retorna descritores para todos os tipos de métricas disponíveis em um projeto. O único parâmetro obrigatório é o name.
Para executar o método metricDescriptors.list, faça o seguinte:
- Clique em Faça um teste.
- No parâmetro name, insira o ID do projeto usando o formato
projects/[PROJECT_ID]. Não esqueça de substituir [PROJECT_ID] pelo ID do projeto. - Clique em Execute. Para executar o comando, o APIs Explorer requer acesso à sua conta. Quando solicitado, selecione uma conta e clique em Permitir. O acesso é por um período limitado e restrito ao método de API que você está executando.
Os resultados da invocação do método são exibidos em uma caixa com um cabeçalho verde ou
vermelho. Quando a solicitação for bem-sucedida, a caixa terá um cabeçalho verde com o código de status HTTP
200. Os resultados da invocação estão na caixa:
Quando o cabeçalho está vermelho, ele contém um código de falha HTTP e a caixa contém a mensagem de erro. Para mais informações sobre como resolver erros, consulte Solução de problemas.
Fornecer parâmetros adicionais
A lista de parâmetros que você vê depende do método ao qual o widget do APIs Explorer está anexado. Por exemplo, o método metricDescriptors.list tem mais do que o parâmetro name, mas name é o único parâmetro obrigatório.
Ao fornecer apenas o nome do projeto, você recebe todos os descritores de métrica disponíveis no projeto, e há muitos deles. Para restringir a recuperação a um conjunto menor, use o parâmetro filter.
Por exemplo, para listar somente os tipos de métricas com nome terminado em
utilization, faça o seguinte:
Clique em Faça um teste.
No parâmetro name, insira o ID do projeto usando o formato
projects/[PROJECT_ID]. Não esqueça de substituir [PROJECT_ID] pelo ID do projeto.Verifique se o parâmetro filter tem o valor
metric.type=ends_with("utilization")Clique em Executar e preencha as caixas de diálogo de autorização.
Parâmetros padrão
Por padrão, o conjunto de parâmetros que o APIs Explorer mostra corresponde aos parâmetros do método associado. No entanto, o widget do APIs Explorer também tem um conjunto de parâmetros extras que não fazem parte do próprio método. Para exibir os parâmetros extras, clique em Mostrar parâmetros padrão:
Para ocultar os parâmetros extras da exibição, clique em Ocultar parâmetros padrão.
O parâmetro padrão mais útil é o fields. Esse parâmetro permite selecionar os campos na saída retornada que você quer ver.
Por exemplo, listar os descritores das métricas que terminam com utilization ainda retorna muitos resultados. Se você quiser saber apenas o nome do tipo de métrica e a respectiva descrição, especifique essa restrição usando o parâmetro fields.
Para ver o resultado da configuração do parâmetro fields, faça o seguinte:
Clique em Faça um teste.
No parâmetro name, insira o ID do projeto usando o formato
projects/[PROJECT_ID]. Não esqueça de substituir [PROJECT_ID] pelo ID do projeto.Verifique se o parâmetro filter tem o valor
metric.type=ends_with("utilization")Clique em Mostrar parâmetros padrão e verifique se o parâmetro fields tem o valor
metricDescriptors.type,metricDescriptors.description.Clique em Executar e preencha as caixas de diálogo de autorização.
A execução dessa solicitação retorna apenas o type (nome abreviado) de cada métrica e seu description.
Resolver problemas
Esta seção descreve problemas comuns ao usar o APIs Explorer.
Para mais informações sobre como usar a API Cloud Monitoring, consulte Solução de problemas da API Cloud Monitoring.Sintaxe de filtro inválida
Você copia uma expressão de várias linhas e cola em um campo mostrado no APIs Explorer, mas elas exibem uma mensagem de erro.
Recomendação: verifique se as strings estão em uma única linha.
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"
O que não fazer: copie e cole a continuação de linha ou os caracteres de nova linha.
Por exemplo, se você adicionar o seguinte ao método timeSeries.query, as APIs Explorer exibirão a mensagem de erro Select an underlined section to see more details:
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count
| within 5m"
Identificador de projeto inválido
Se o identificador do projeto for inválido, a solicitação de API falhará com um erro HTTP 400.
Para resolver essa condição, verifique se o texto [PROJECT_ID] foi substituído pelo ID do projeto.
Valores de formulário inválidos
Se a solicitação de API falhar ou retornar valores inesperados, verifique todos os parâmetros do formulário.
Os parâmetros do APIs Explorer exigem uma formatação específica. Erros de formatação podem causar erros ou podem ser aceitos, mas são tratados como erros de ortografia no método da API:
- Não use aspas em valores de parâmetro de qualquer tipo.
Não use barras invertidas, exceto quando for necessário proteger uma substring.
O exemplo a seguir é para um método de API em que você insere o conteúdo como JSON, em vez de preencher parâmetros individuais de formulário. Como o valor de
filteré uma string, a substringk8s_clusteré protegida por barras invertidas:
{
"resourceNames": [...],
"filter": "resource.type = \"k8s_cluster\""
}
- Strings de aspas que aparecem dentro dos filtros. Use aspas duplas (
"), e não apóstrofos ('). Por exemplo, consulte Fornecer parâmetros adicionais.
- Não use codificação de URL no formulário. Se um método de API exigir codificação de URL, o widget executará a conversão quando você executar o método.
Muitos dados foram retornados
Para limitar o número de resultados retornados, insira um valor como 2 no parâmetro pageSize. O parâmetro pageSize define o número máximo
de resultados retornados e está disponível para a maioria dos métodos de API.
Para selecionar campos específicos a serem retornados, use o parâmetro fields. Para mais informações, consulte Parâmetros padrão.
Authentication
Há uma seção Credenciais na página do APIs Explorer. Recomendamos que você mantenha esses campos nos valores padrão. O mecanismo de autenticação padrão é o Google OAuth 2.0.
Para descobrir quais escopos da API são necessários para o método, clique em Mostrar escopos. Por padrão, todos os escopos necessários são concedidos.
Para mais informações sobre esses conceitos, consulte Controlar o acesso com o Identity and Access Management.