Usar o API Explorer

Este guia descreve como usar o API Explorer para testar os métodos da API Monitoring. O API 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 widget do API Explorer.

O API 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 na parte superior do painel ou expandi-lo para tela cheia clicando no botão .

Botões Testar!

Por meio da documentação, você verá os botões Testar, como os exemplos a seguir:

Faça o teste!

Clicar no botão exibe o API Explorer na página de referência adequada e preenche os campos conforme apropriado para o exemplo. Você precisará editar alguns dos campos para corresponder ao seu próprio projeto, como o valor de [PROJECT_ID].

Consulte Dicas para mais informações sobre como evitar e corrigir erros.

Como acessar o API Explorer

O API Explorer é anexado à página de referência de cada método da API REST. Para encontrar o widget, acesse a página de referência de um método. Por exemplo, a página de referência de monitoring.projects.metricDescriptors.list.

Como executar uma solicitação mínima

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 mínima fornecendo apenas os argumentos necessários.

O método metricDescriptors.list retorna descritores para todos os tipos de métricas disponíveis em um projeto. O único campo obrigatório é o campo name. Para recuperar essa lista para seu projeto, forneça o nome do projeto para name, usando o formulário projects/[PROJECT_ID].

Clique no botão abaixo para testá-lo, mas, antes de clicar no botão Executar no formulário, você precisa alterar [PROJECT_ID] para o identificador do seu projeto:

Faça o teste!

Os resultados da invocação do método aparecem em uma caixa abaixo do botão Executar. Normalmente, a caixa tem um cabeçalho verde com o código de status HTTP 200, indicando que a solicitação foi bem-sucedida. Os resultados da invocação estão na caixa:

O resultado de uma invocação de método bem-sucedida.

Se o cabeçalho estiver vermelho e contiver um código de falha HTTP, a caixa conterá a mensagem de erro. Consulte Dicas para ver algumas dicas sobre como resolver erros.

Como fornecer parâmetros adicionais

A lista de parâmetros que você vê depende do método ao qual o widget do API Explorer está anexado. O método metricDescriptors.list tem mais do que apenas 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. É possível usar o parâmetro opcional filter para restringir a recuperação a um conjunto menor.

Por exemplo, preencha os seguintes campos na página metricsDescriptor.list. Substitua o código do projeto por [PROJECT_ID], mas forneça o outro valor conforme mostrado:

  • nome: projects/[PROJECT_ID]
  • filter: metric.type=ends_with("utilization")

A execução dessa solicitação retorna apenas os descritores dos tipos de métricas cujos nomes terminam com utilization.

Faça o teste!

Como usar campos para limitar ainda mais a saída

Por padrão, o conjunto de parâmetros que o API Explorer mostra corresponde aos parâmetros do método associado. No entanto, o widget do API Explorer também tem um conjunto de campos adicionais que não estão disponíveis por meio do próprio método.

Esses parâmetros ficam ocultos no botão Mostrar parâmetros padrão, que aparece acima da seção Autenticação:

Botão

Clique nesse botão para expor os parâmetros adicionais do widget. Clique em Ocultar parâmetros padrão para ocultá-los.

O mais útil desses parâmetros padrão é o parâmetro fields, que permite selecionar os campos na saída retornada que você quer ver. Isso é muito útil no painel do API Explorer, em que a saída é exibida em uma caixa. Geralmente, há muitas saídas para percorrer.

Por exemplo, listar os descritores para métricas que terminam com utilization ainda retorna muitas informações. Se você só tiver interesse no nome do tipo da métrica e na descrição, use o campo fields para especificar apenas esses campos.

Para ver a diferença, preencha os seguintes campos na página metricsDescriptor.list. Substitua o código do projeto por [PROJECT_ID], mas forneça os outros valores conforme mostrado:

  • name, como antes: projects/[PROJECT_ID]
  • filter, como antes: metric.type=ends_with("utilization")
  • fields: metricDescriptors.type,metricDescriptors.description

A execução dessa solicitação retorna apenas o type (nome abreviado) de cada métrica e seu description. O seguinte faz parte da saída:

Faça o teste!

Dicas

Lembre-se de alterar [PROJECT_ID]

Não se esqueça de substituir [PROJECT_ID] pelo código do projeto. Se você esquecer, terá o seguinte resultado:

Mensagem de erro quando você se esquecer de alterar PROJECT_ID.

Problemas com os valores

Veja alguns problemas a serem observados ao usar os formulários do API Explorer. Esses erros podem causar erros ou ser aceitos, mas são tratados como erros de ortografia no método da API:

  • Não use aspas em valores de campo de qualquer tipo.
  • Não se esqueça de usar aspas nas strings que aparecem dentro de filtros. Use aspas duplas (") e não apóstrofos ('). Consulte Como fornecer parâmetros adicionais para ver um exemplo.
  • Não use barras invertidas ou codificação de URL em campos de formulário. Se necessário, a codificação de URL é executada nos valores de campo quando você executa o método.
  • Observe o valor na caixa de resultado depois de executar a chamada. É possível notar o problema lá.
  • Convém fornecer um valor para o campo pageSize, como 2. Isso limita a quantidade de dados retornados à medida que você depura sua chamada de API.

Adicione URLs aos favoritos para depuração

Depois de receber a saída que você quer, adicione o URL do API Explorer aos favoritos. Para executar o método novamente, cole o URL no navegador. Você verá o formulário já preenchido com seus valores. Faça as alterações necessárias nos parâmetros e clique em Executar para executar o método novamente.

Autenticação

Há uma seção de Autenticação na página do API Explorer, acima do botão Executar. Normalmente, não é necessário alterar nada aqui.

O mecanismo de autenticação padrão é Google OAuth 2.0.

Há também um botão Mostrar escopos na seção Autenticação. Isso mostra quais escopos do Compute Engine estão disponíveis. Por padrão, todos os escopos disponíveis estão ativados.

Consulte Controle de acesso para mais informações sobre esses conceitos.

Resolver problemas

Se você ainda tiver problemas, consulte Solução de problemas da API Monitoring.