Utilizzo di Explorer API

Questa guida descrive come utilizzare Explorer API per provare i metodi dell'API Cloud Monitoring. Explorer API è un widget collegato 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 così come appare 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 ogni metodo. Compila il modulo, fai clic sul pulsante Esegui e visualizza i risultati.

Puoi anche nascondere il widget facendo clic sul pulsante close o espandere il widget a schermo intero facendo clic sul pulsante fullscreen.

Pulsanti Prova

Nella documentazione potresti visualizzare pulsanti Prova come il seguente:

Quando fai clic sul pulsante, si apre Explorer API nella pagina di riferimento del metodo. In genere, alcuni parametri appropriati per l'esempio vengono compilati; 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, vedi Risoluzione dei problemi.

Accedere a Explorer API

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

Eseguire una richiesta

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

Per eseguire il metodo metricDescriptors.list:

1. Fai clic su Prova.
2. Nel parametro name, inserisci l'ID del tuo progetto utilizzando il formato projects/[PROJECT_ID]. Assicurati di sostituire [PROJECT_ID] con l'ID del tuo progetto.
3. Fai clic su Esegui. Per eseguire il comando, APIs Explorer richiede l'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 API che stai eseguendo.

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

Quando l'intestazione è rossa, contiene un codice di errore HTTP e la casella contiene il messaggio di errore. Per informazioni sulla risoluzione degli errori, vedi Risoluzione dei problemi.

Fornisci parametri aggiuntivi

L'elenco dei parametri visualizzati dipende dal metodo a cui è collegato il widget APIs Explorer. 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 tuo 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 tuo progetto utilizzando il formato projects/[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, il set di parametri mostrato da Explorer API corrisponde ai parametri del metodo associato. Tuttavia, il widget Explorer API dispone anche di 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 ti consente di selezionare i campi nell'output restituito che vuoi visualizzare.

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 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 tuo progetto utilizzando il formato projects/[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 durante l'utilizzo di Explorer API.

Sintassi del filtro non valida

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

Azione: assicurati che le stringhe si trovino su una sola riga.

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

Non: copiare e incollare 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": "sum by (instance_name) (
                   rate(
                      {\"compute.googleapis.com/instance/disk/read_bytes_count\",
                          monitored_resource=\"gce_instance\"
                     }[5m]
                  )
               )"

Identificatore 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 questo problema, 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 APIs Explorer richiedono una formattazione specifica. Gli errori di formattazione potrebbero causare errori o potrebbero essere accettati, ma trattati come errori ortografici nel metodo API:

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

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

  Ad esempio, il seguente campione riguarda un metodo API in cui inserisci i contenuti in formato JSON, anziché compilare 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 tra 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 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, nel parametro pageSize, inserisci un valore, 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.