Utilizzo di Explorer API

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

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

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

Nota: se espandi Explorer API a schermo intero, puoi visualizzare la richiesta come comando curl, come richiesta HTTP e in JavaScript.

Pulsanti Fai una prova

Nella documentazione potresti vedere pulsanti Prova come il seguente:

Prova!

Quando fai clic sul pulsante, si apre Explorer API nella pagina di riferimento del metodo. In genere, vengono compilati alcuni parametri appropriati all'esempio. Tuttavia, potresti dover modificare alcuni parametri in modo che corrispondano al tuo progetto, ad esempio il valore di [PROJECT_ID].

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

Accedere a Explorer API

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

Esegui una richiesta

La maggior parte dei metodi ha alcuni parametri obbligatori e altri facoltativi. Quelli obbligatori sono contrassegnati da una barra rossa finché non vengono compilati. Puoi eseguire una richiesta dopo aver fornito i valori per tutti gli argomenti obbligatori.

Il metodo metricDescriptors.list restituisce i descrittori di tutti i tipi di metrica 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 formatoprojects/[PROJECT_ID]. Assicurati di sostituire [PROJECT_ID] con l'ID del tuo progetto.
3. Fai clic su Execute (Esegui). Per eseguire il comando, APIs Explorer richiede accesso al tuo account. Quando richiesto, seleziona un account e fai clic su Consenti. L'accesso è per un periodo di tempo limitato e limitato al metodo dell'API che stai eseguendo.

I risultati dell'invocazione del metodo vengono visualizzati in una casella con un'intestazione verde o rossa. Quando la richiesta va a buon fine, la casella contiene un'intestazione verde con il codice di stato HTTP 200. I risultati dell'invocazione sono nella finestra:

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 sezione Risolvere i problemi.

Nota: dopo aver configurato Esplora API e aver fatto clic su Esegui, l'URL della pagina cambia. Puoi aggiungere l'URL aggiornato ai preferiti. Quando vuoi eseguire di nuovo il metodo, fai clic sul preferito per aprire la pagina con il modulo già compilato con le tue selezioni precedenti.

Fornisci parametri aggiuntivi

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

Se fornisci solo il nome del progetto, ottieni tutti i descrittori delle metriche disponibili nel progetto, che sono molti. 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 formatoprojects/[PROJECT_ID]. Assicurati di sostituire [PROJECT_ID] con l'ID del tuo 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 include anche un insieme di parametri aggiuntivi che non fanno parte del metodo stesso. Per visualizzare i parametri aggiuntivi, fai clic su Mostra parametri standard:

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

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

Ad esempio, l'elenco dei descrittori per le metriche che terminano con utilization restituisce ancora molti risultati. Se vuoi conoscere solo il nome del tipo di metrica e la relativa descrizione, puoi specificare questa limitazione utilizzando il parametro fields.

Per visualizzare il risultato dell'impostazione del parametro fields:

1. Fai clic su Prova.

2. Nel parametro name, inserisci l'ID del progetto utilizzando il formatoprojects/[PROJECT_ID]. Assicurati di sostituire [PROJECT_ID] con l'ID del tuo 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.

Risoluzione dei problemi

Questa sezione descrive i problemi comuni che si verificano durante l'utilizzo di API Explorer.

Per saperne di più sull'utilizzo dell'API Cloud Monitoring, consulta la pagina Risoluzione dei problemi relativi all'API Cloud Monitoring.

Sintassi del filtro non valida

Copi un'espressione multiriga e la incolli in un campo visualizzato in Explorer API, ma Explorer API mostra un messaggio di errore.

Azione: assicurati che le stringhe siano su una singola riga.

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

Non: copiare e incollare caratteri di continuazione riga o di inizio riga.

Ad esempio, se aggiungi quanto segue al metodo timeSeries.query, Explorer API visualizza 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 progetto non valido

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

Per risolvere questa condizione, verifica che il testo [PROJECT_ID] sia stato sostituito con l'ID del tuo 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 possono causare errori o essere accettati, ma trattati come errori ortografici nel metodo dell'API:

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

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

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

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

• Stringhe tra virgolette visualizzate all'interno dei filtri. Utilizza virgolette doppie (") e non apostrofi ('). Per un esempio, consulta Fornire parametri aggiuntivi.

• Non utilizzare la codifica URL nel modulo. Se un metodo API richiede la codifica 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 maggiori informazioni, consulta Parametri standard.

Autenticazione

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

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

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