Utilizzo di Explorer API

Questa guida descrive come utilizzare Explorer API per provare i metodi dell'API Cloud Monitoring. L'Explorer API è un widget collegato alla pagina di riferimento dell'API REST per un metodo. Viene visualizzato sotto forma di riquadro con il titolo Prova questa API. Lo screenshot seguente mostra il riquadro come viene visualizzato per un metodo con un solo parametro, name:

Il widget Explorer API.

Explorer API è un ottimo modo per provare i metodi nell'API Cloud Monitoring senza dover scrivere codice. Il widget presenta un modulo con i parametri per ciascun metodo. Compila il modulo, fai clic sul pulsante Esegui e guarda i risultati.

Puoi anche nascondere il widget facendo clic sul pulsante oppure espanderlo a schermo intero facendo clic sul pulsante .

Pulsanti Prova!

Nella documentazione, potresti vedere pulsanti Prova! come i seguenti:

Prova!

Quando fai clic sul pulsante, si apre Explorer API nella pagina di riferimento del metodo. In genere vengono completati alcuni parametri appropriati all'esempio; tuttavia, potrebbe essere necessario modificarli in modo che corrispondano al progetto, ad esempio il valore per [PROJECT_ID].

Per informazioni su come evitare e correggere gli errori, consulta la sezione Risoluzione dei problemi.

Accedere a Explorer API

Explorer API è collegato alla pagina di riferimento per ogni metodo API REST. Per trovare il widget, consulta la pagina di riferimento per un metodo, ad esempio consulta la pagina metricDescriptors.list.

Esegui una richiesta

La maggior parte dei metodi prevede alcuni parametri obbligatori e alcuni facoltativi. Quelli obbligatori sono contrassegnati con una barra rossa fino a quando non vengono riempiti. Puoi eseguire una richiesta dopo aver fornito i valori per tutti gli argomenti richiesti.

Il metodo metricDescriptors.list restituisce i descrittori per tutti i tipi di metriche disponibili in un progetto. L'unico parametro obbligatorio è il parametro name.

Per eseguire il metodo metricDescriptors.list:

  1. Fai clic su Prova!
  2. Nel parametro name, inserisci l'ID del progetto utilizzando il formato projects/[PROJECT_ID]. Assicurati di sostituire [PROJECT_ID] con l'ID del progetto.
  3. Fai clic su Execute (Esegui). Per eseguire il comando, Explorer API richiede l'accesso al tuo account. Quando richiesto, seleziona un account e fai clic su Consenti. L'accesso è per un periodo di tempo limitato ed è limitato al metodo API che stai eseguendo.

I risultati della chiamata al metodo vengono visualizzati in una casella con un'intestazione verde o rossa. Quando la richiesta ha esito positivo, la casella ha un'intestazione verde contenente il codice di stato HTTP 200. I risultati della chiamata sono riportati nella casella:

Il risultato di una chiamata al metodo riuscita.

Quando l'intestazione è rossa, contiene un codice di errore HTTP e la casella contiene il messaggio di errore. Per informazioni sulla risoluzione degli errori, consulta la pagina Risolvere i problemi.

Fornisci parametri aggiuntivi

L'elenco dei parametri visualizzato dipende dal metodo a cui è collegato il widget Explorer API. Ad esempio, il metodo metricDescriptors.list ha più del parametro name, ma name è l'unico parametro obbligatorio.

Quando fornisci solo il nome del progetto, ottieni tutti i descrittori delle metriche disponibili nel tuo progetto, molti dei quali disponibili. Per limitare il recupero a un insieme più piccolo, utilizza il parametro filter.

Ad esempio, per elencare solo i tipi di metriche il cui nome termina con utilization, procedi nel seguente modo:

  1. Fai clic su Prova!

  2. Nel parametro name, inserisci l'ID del progetto utilizzando il formato projects/[PROJECT_ID]. Assicurati di sostituire [PROJECT_ID] con l'ID del progetto.

  3. Assicurati che il parametro filter abbia il valore metric.type=ends_with("utilization")

  4. Fai clic su Esegui e completa le finestre di dialogo di autorizzazione.

Parametri standard

Per impostazione predefinita, l'insieme di parametri mostrato da Explorer API corrisponde ai parametri del metodo associato. Tuttavia, il widget Explorer API ha anche un insieme di parametri aggiuntivi che non fanno parte del metodo stesso. Per visualizzare i parametri aggiuntivi, fai clic su Mostra parametri standard:

Pulsante di attivazione/disattivazione dei parametri standard.

Per nascondere i parametri aggiuntivi dalla visualizzazione, fai clic su Nascondi parametri standard.

Il parametro standard più utile è il parametro fields. Questo parametro consente di selezionare i campi che vuoi visualizzare nell'output restituito.

Ad esempio, elencare i descrittori per le metriche che terminano con utilization restituisce comunque molti risultati. Se vuoi conoscere solo il nome del tipo di metrica e la relativa descrizione, puoi specificare questa restrizione utilizzando il parametro fields.

Per vedere il risultato dell'impostazione del parametro fields, procedi nel seguente modo:

  1. Fai clic su Prova!

  2. Nel parametro name, inserisci l'ID del progetto utilizzando il formato projects/[PROJECT_ID]. Assicurati di sostituire [PROJECT_ID] con l'ID del progetto.

  3. Assicurati che il parametro filter abbia il valore metric.type=ends_with("utilization")

  4. Fai clic su Mostra parametri standard e verifica che il parametro fields abbia il valore metricDescriptors.type,metricDescriptors.description.

  5. Fai clic su Esegui e completa le finestre di dialogo di autorizzazione.

L'esecuzione di questa richiesta restituisce solo il type (nome breve) di ogni metrica e il relativo description.

Risolvere i problemi

Questa sezione descrive i problemi comuni quando si utilizza Explorer API.

Per ulteriori informazioni sull'utilizzo dell'API Cloud Monitoring, consulta Risoluzione dei problemi dell'API Cloud Monitoring.

Sintassi del filtro non valida

Copia un'espressione su più righe e incollala in un campo visualizzato in Explorer API, ma Explorer API mostra un messaggio di errore.

Azione: assicurati che le stringhe siano su un'unica riga.

"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"

Non: copia e incolla i caratteri di continuazione di riga o di nuova riga.

Ad esempio, se aggiungi quanto segue al metodo timeSeries.query, Explorer API mostra il messaggio di errore Select an underlined section to see more details:

"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count
          | within 5m"

Identificatore di progetto non valido

Se l'identificatore del progetto non è valido, la richiesta API non va a buon fine e viene restituito un errore HTTP 400.

Per risolvere questa condizione, verifica che il testo [PROJECT_ID] sia stato sostituito con l'ID del progetto.

Valori del modulo non validi

Se la richiesta API non va a buon fine o restituisce valori imprevisti, controlla tutti i parametri del modulo.

I parametri di Explorer API richiedono una formattazione specifica. Gli errori di formattazione potrebbero causare errori oppure potrebbero essere accettati, ma essere trattati come errori di ortografia nel metodo API:

  • Non utilizzare virgolette per i valori dei parametri di alcun tipo.

  • Non utilizzare barre rovesciate, tranne quando devi proteggere una sottostringa.

    Ad esempio, il seguente esempio riguarda un metodo API in cui inserisci i contenuti come JSON, anziché completare i singoli parametri del modulo. Poiché il valore di filter è una stringa, la sottostringa k8s_cluster è protetta da barre rovesciate:

    {
      "resourceNames": [...],
      "filter": "resource.type = \"k8s_cluster\""
    }
  • Stringhe delle virgolette visualizzate all'interno dei filtri. Utilizza le virgolette doppie (") e non gli apostrofi ('). Per un esempio, vedi Fornire parametri aggiuntivi.
  • Non utilizzare la codifica degli URL nel modulo. Se un metodo API richiede la codifica degli URL, il widget esegue la conversione quando esegui il metodo.

Vengono restituiti troppi dati

Per limitare il numero di risultati restituiti, inserisci un valore nel parametro pageSize, ad esempio 2. Il parametro pageSize definisce il numero massimo di risultati restituiti ed è disponibile per la maggior parte dei metodi API.

Per selezionare campi specifici da restituire, utilizza il parametro fields. Per ulteriori informazioni, consulta Parametri standard.

Autenticazione

È presente una sezione Credenziali nella pagina Explorer API. Ti consigliamo di lasciare in questi campi i valori predefiniti. Il meccanismo di autenticazione predefinito è Google OAuth 2.0.

Per scoprire quali ambiti API sono necessari per il metodo, fai clic su Mostra ambiti. Per impostazione predefinita, sono concessi tutti gli ambiti necessari.

Per ulteriori informazioni su questi concetti, vedi Controllare l'accesso con Identity and Access Management.