L'API Discovery fornisce un elenco delle API di Google per il recupero di un "documento di rilevamento" leggibile dal computer per ciascuna API.
Questo documento è destinato agli sviluppatori che desiderano scrivere librerie client, plug-in IDE e altri strumenti per interagire con le API di Google.
Sfondo servizio di rilevamento
Concetti
Il servizio di rilevamento delle API di Google si basa su due concetti di base:
- Directory delle API: elenco di tutte le API supportate dal servizio di individuazione delle API. Ogni voce di directory mostra i dettagli di un'API supportata, inclusi il relativo nome, una breve descrizione delle operazioni e un link alla documentazione. Un'API può avere più voci Directory, una per ogni versione supportata.
- Documento di rilevamento: una descrizione leggibile da macchina di una determinata API. Il documento di rilevamento descrive la superficie di una determinata versione di un'API. Il documento fornisce dettagli su come accedere ai vari metodi di ciascuna API tramite chiamate HTTP RESTful. Un documento di rilevamento include le descrizioni dei dati e dei metodi associati all'API, informazioni sugli ambiti OAuth disponibili e descrizioni di schemi, metodi, parametri e valori dei parametri disponibili.
Modello dei dati
Una risorsa è una singola entità dati con un identificatore univoco. Il servizio di individuazione delle API di Google opera su due tipi di risorse, in base ai concetti sopra indicati.
Elenco API: un elenco di API.
Ogni voce di directory contiene una coppia name/version dell'API con le seguenti informazioni:
- Informazioni su identificazione e descrizione: nome, versione, titolo e descrizione.
- Informazioni sulla documentazione: icone e un link alla documentazione.
- Informazioni sullo stato, incluse etichette dello stato, e un'indicazione per verificare se si tratta o meno della versione preferita dell'API.
- Link al documento di rilevamento, l'URI del documento di rilevamento per questa API (indicato come un URL completo, ad esempio https://servicemanagement.googleapis.com/$discovery/rest?version=v1).
Risorsa del documento di rilevamento: una descrizione leggibile da macchina di una determinata API
Oltre alle informazioni fornite nella directory delle API, un documento di rilevamento include anche:
- Schemi, che sono un elenco di schemi di risorse dell'API che descrivono i dati a cui hai accesso in ciascuna API. Gli schemi del servizio di individuazione delle API di Google si basano sullo schema JSON.
- Metodi, incluso un elenco di metodi API e parametri disponibili per ciascun metodo.
- Ambiti OAuth: identifica l'elenco degli ambiti OAuth disponibili per questa API.
- Documentazione integrata che fornisce brevi descrizioni di schemi, metodi, parametri e valori dei parametri disponibili.
La singola raccolta directory è il container concettuale della singola risorsa directory delle API e le risorse del documento di rilevamento per ogni API supportata.
Ulteriori dettagli sulla risorsa dell'API Directory e sul documento di rilevamento sono disponibili nei documenti Utilizzo dell'API e di Riferimento.
Operazioni
Nel servizio Discovery API di Google puoi richiamare due diversi metodi su raccolte e risorse, come descritto nella tabella seguente.
| Operazione | Descrizione | Mappature HTTP REST |
|---|---|---|
| list | Elenca tutte le API supportate. | GET sull'URI della risorsa directory. |
Stile chiamata
REST
Le operazioni del servizio di rilevamento delle API di Google supportate vengono mappate direttamente al verbo HTTP REST GET, come descritto nella sezione Operazioni.
Il formato specifico per gli URI del servizio di rilevamento delle API di Google è:
https://discovery.googleapis.com/discovery/v1/apis?parameters
dove api è l'identificatore di una risorsa del documento di rilevamento, mentre version è l'identificatore della versione specifica dell'API, mentre _parameters_ sono i parametri da applicare alla query. Per maggiori dettagli, consulta il riepilogo dei parametri di ricerca nella documentazione di riferimento.
I dettagli sull'insieme completo di URI utilizzati per ogni operazione supportata nell'API sono riassunti nel documento Google API Discovery Service Reference.
Ecco un paio di esempi di come funziona nel servizio di individuazione delle API di Google.
Elenca tutte le API supportate dal servizio di individuazione API di Google:
GET https://discovery.googleapis.com/discovery/v1/apis
Scarica il documento Discovery per l'API Google Cloud Service Management, versione 1:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1