Utilizzo di Explorer API

Questa guida descrive come utilizzare Explorer API per provare i metodi dell'API Cloud Monitoring. Explorer API è un widget collegato Pagina di riferimento dell'API REST per un metodo. Ha l'aspetto di un riquadro con il titolo Prova questa API. Il seguente screenshot mostra il riquadro così com'è 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 e 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 oppure espandi il widget a schermo intero facendo clic sul pulsante .

Fai una prova! pulsanti

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. Generalmente, vengono completati alcuni parametri appropriati all'esempio. Tuttavia, potresti dover modificare alcuni parametri affinché corrispondano ai tuoi progetto, come il valore di [PROJECT_ID].

Per informazioni su come evitare e correggere gli errori, vedi Risolvere i 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 descrittori per tutti i valori disponibili di metriche di 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 API che utilizzi in esecuzione.

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 della chiamata sono contenuti 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 sezione Risolvere i problemi.

Fornisci parametri aggiuntivi

L'elenco dei parametri visualizzati dipende dal metodo utilizzato Il widget Explorer API è collegato. 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 nel 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, l'insieme di parametri mostrato da Explorer API corrisponde i parametri del metodo associato. Tuttavia, il widget Explorer API ha anche un insieme di parametri aggiuntivi che non fanno parte del metodo stesso. A visualizzare i parametri aggiuntivi, fai clic su Mostra parametri standard:

Mostra 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 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 il parametro fields. ha 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'uso dell'API Cloud Monitoring, consulta Risoluzione dei problemi dell'API Cloud Monitoring.

Sintassi del filtro non valida

Devi copiare un'espressione multiriga e incollarla in un campo della 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 alla timeSeries.query , poi 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 API 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 riesce o restituisce valori imprevisti, seleziona tutte e 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 riguarda un metodo API in cui inserisci i contenuti in formato JSON, anziché completare i singoli parametri del modulo. Poiché il valore di filter è una stringa, la sottostringa k8s_cluster è protetto da barre rovesciate:

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

Vengono restituiti troppi dati

Per limitare il numero di risultati restituiti, inserisci un valore, ad esempio 2, nel parametro pageSize. 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 individuare gli ambiti API necessari per il metodo, fai clic su Mostra ambiti. Per impostazione predefinita, sono concessi tutti gli ambiti necessari.

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