Usar o Explorador de APIs

Este guia descreve como usar o Explorador de APIs para experimentar os métodos da API Cloud Monitoring. O Explorador de APIs é um widget anexado à página de referência da API REST para um método. Aparece como um painel com o título Experimentar esta API. A captura de ecrã seguinte mostra o painel tal como aparece para um método com apenas um parâmetro, name:

O Explorador de APIs é uma excelente forma de experimentar métodos na API Cloud Monitoring sem ter de escrever 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 pode ocultar o widget clicando no botão ou expandir o widget para ecrã inteiro clicando no botão .

Nota: se expandir o APIs Explorer para o modo de ecrã inteiro, pode ver o pedido como um comando curl, como um pedido HTTP e em JavaScript.

Botões Experimentar!

Na documentação, pode ver botões Experimentar! como os seguintes:

Experimentar!

Quando clica no botão, o APIs Explorer é aberto na página de referência do método. Normalmente, alguns parâmetros adequados ao exemplo são preenchidos; no entanto, pode ter de editar alguns dos parâmetros para corresponderem ao seu próprio projeto, como o valor de [PROJECT_ID].

Para obter informações sobre como evitar e corrigir erros, consulte o artigo Resolva problemas.

Aceda ao Explorador de APIs

O APIs Explorer está 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, consulte metricDescriptors.list.

Executar um pedido

A maioria dos métodos tem alguns parâmetros obrigatórios e outros opcionais. Os campos obrigatórios estão marcados com uma barra vermelha até serem preenchidos. Pode executar um pedido depois de fornecer valores para todos os argumentos obrigatórios.

O método metricDescriptors.list devolve descritores para todos os tipos de métricas disponíveis num projeto. O único parâmetro obrigatório é o parâmetro name.

Para executar o método metricDescriptors.list, faça o seguinte:

1. Clique em Experimentar!
2. No parâmetro name, introduza o ID do seu projeto no formato projects/[PROJECT_ID]. Certifique-se de que substitui [PROJECT_ID] pelo ID do seu projeto.
3. Clique em Executar. Para executar o comando, o APIs Explorer requer acesso à sua conta. Quando lhe for pedido, selecione uma conta e clique em Permitir. O acesso é por um período limitado e restrito ao método da API que está a executar.

Os resultados da invocação do método são apresentados numa caixa com um cabeçalho verde ou vermelho. Quando o pedido é bem-sucedido, a caixa tem um cabeçalho verde com o código de estado HTTP 200. Os resultados da invocação estão na caixa:

Quando o cabeçalho está a vermelho, contém um código de falha HTTP e a caixa contém a mensagem de erro. Para obter informações sobre a resolução de erros, consulte a secção Resolução de problemas.

Nota: depois de configurar o APIs Explorer e, em seguida, clicar em Executar, o URL da página é alterado. Pode adicionar o URL atualizado aos marcadores. Quando quiser executar o método novamente, clique no marcador para abrir a página com o formulário já preenchido com as suas seleções anteriores.

Forneça parâmetros adicionais

A lista de parâmetros apresentada 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.

Quando fornece apenas o nome do projeto, recebe todos os descritores de métricas disponíveis no seu projeto, e existem muitos. Para restringir a obtenção a um conjunto mais pequeno, use o parâmetro filter.

Por exemplo, para listar apenas os tipos de métricas cujo nome termina com utilization, faça o seguinte:

1. Clique em Experimentar!

2. No parâmetro name, introduza o ID do seu projeto no formato projects/[PROJECT_ID]. Certifique-se de que substitui [PROJECT_ID] pelo ID do seu projeto.

3. Certifique-se de que o parâmetro filter tem o valor metric.type=ends_with("utilization")

4. Clique em Executar e conclua as caixas de diálogo de autorização.

Parâmetros padrão

Por predefinição, o conjunto de parâmetros que o Explorador de APIs mostra corresponde aos parâmetros do método associado. No entanto, o widget APIs Explorer também tem um conjunto de parâmetros adicionais que não fazem parte do próprio método. Para apresentar os parâmetros adicionais, clique em Mostrar parâmetros padrão:

Para ocultar os parâmetros adicionais da apresentação, clique em Ocultar parâmetros padrão.

O parâmetro padrão mais útil é o parâmetro fields. Este parâmetro permite-lhe selecionar os campos no resultado devolvido que quer ver.

Por exemplo, listar os descritores de métricas que terminam com utilization continua a devolver muitos resultados. Se quiser saber apenas o nome do tipo de métrica e a respetiva descrição, pode especificar esta restrição através do parâmetro fields.

Para ver o resultado da definição do parâmetro fields, faça o seguinte:

1. Clique em Experimentar!

2. No parâmetro name, introduza o ID do seu projeto no formato projects/[PROJECT_ID]. Certifique-se de que substitui [PROJECT_ID] pelo ID do seu projeto.

3. Certifique-se de que o parâmetro filter tem o valor metric.type=ends_with("utilization")

4. Clique em Mostrar parâmetros padrão e verifique se o parâmetro fields tem o valor metricDescriptors.type,metricDescriptors.description

5. Clique em Executar e conclua as caixas de diálogo de autorização.

A execução deste pedido devolve apenas o type (nome abreviado) de cada métrica e o respetivo description.

Resolver problemas

Esta secção descreve problemas comuns ao usar o Explorador de APIs.

Para mais informações sobre a utilização da API Cloud Monitoring, consulte o artigo Resolução de problemas da API Cloud Monitoring.

Sintaxe de filtro inválida

Copia uma expressão de várias linhas e cola-a num campo apresentado no Explorador de APIs, mas o Explorador de APIs apresenta uma mensagem de erro.

Faça o seguinte: certifique-se de que as strings estão numa única linha.

"query": "sum by (instance_name) (rate({\"compute.googleapis.com/instance/disk/read_bytes_count\", monitored_resource=\"gce_instance\"}[5m]))"

Não: copie e cole carateres de continuação de linha ou de nova linha.

Por exemplo, se adicionar o seguinte ao método timeSeries.query, o APIs Explorer apresenta a mensagem de erro Select an underlined section to see more details:

"query": "sum by (instance_name) (
                   rate(
                      {\"compute.googleapis.com/instance/disk/read_bytes_count\",
                          monitored_resource=\"gce_instance\"
                     }[5m]
                  )
               )"

Identificador do projeto inválido

Se o identificador do projeto for inválido, o pedido API falha com um erro HTTP 400.

Para resolver esta condição, verifique se o texto [PROJECT_ID] foi substituído pelo ID do seu projeto.

Valores de formulário inválidos

Se o seu pedido de API falhar ou devolver valores inesperados, verifique todos os parâmetros do formulário.

Os parâmetros do APIs Explorer requerem uma formatação específica. Os erros de formatação podem causar erros ou podem ser aceites, mas são tratados como erros ortográficos no método da API:

• Não use aspas em torno dos valores de parâmetros de qualquer tipo.

• Não use barras invertidas, exceto quando precisar de proteger uma substring.

  Por exemplo, o seguinte exemplo destina-se a um método de API em que introduz o conteúdo como JSON, em vez de preencher parâmetros de formulário individuais. Uma vez que o valor de filter é uma string, a substring, k8s_cluster, está protegida por barras invertidas:

    {
      "resourceNames": [...],
      "filter": "resource.type = \"k8s_cluster\""
    }

• Cadeias de carateres com aspas que aparecem dentro de filtros. Use aspas duplas (") e não apóstrofos ('). Para ver um exemplo, consulte a secção Forneça parâmetros adicionais.

• Não use a codificação de URL no formulário. Se um método de API requer codificação de URL, o widget faz a conversão quando executa o método.

São devolvidos demasiados dados

Para limitar o número de resultados devolvidos, no parâmetro pageSize, introduza um valor, como 2. O parâmetro pageSize define o número máximo de resultados devolvidos e está disponível para a maioria dos métodos da API.

Para selecionar campos específicos a devolver, use o parâmetro fields. Para mais informações, consulte o artigo Parâmetros padrão.

Autenticação

Existe uma secção Credenciais na página do Explorador de APIs. Recomendamos que deixe estes campos com os valores predefinidos. O mecanismo de autenticação predefinido é o Google OAuth 2.0.

Para saber os âmbitos da API necessários para o método, clique em Mostrar âmbitos. Por predefinição, todos os âmbitos necessários são concedidos.

Para mais informações acerca destes conceitos, consulte o artigo Controle o acesso com a gestão de identidades e acessos.