L'API Discovery fornisce un elenco di API di Google per il recupero di un campo "Discovery documento" metadati per ogni API.
Questo documento è rivolto agli sviluppatori che desiderano scrivere librerie client, plug-in IDE e e altri strumenti per interagire con le API di Google.
Sfondo del servizio di scoperta
Concetti
Il servizio di rilevamento delle API di Google si basa su due concetti di base:
- Directory API: un elenco di tutte le API supportate dalla API Discovery Service. Ogni voce della directory mostra i dettagli di un'API supportata, tra cui il nome, una breve descrizione della funzionalità e un link alla documentazione. Un'API può avere più voci di directory, una per ciascuna delle sue versioni supportate.
- Documento di rilevamento: una descrizione leggibile da macchina di una determinata API. Il documento di rilevamento descrive la piattaforma per una determinata versione di un'API. La documento fornisce i dettagli su come accedere ai vari metodi di ciascuna API tramite RESTful HTTP chiamate. Un documento Discovery include descrizioni dei dati e dei metodi associati all'API, nonché informazioni sugli ambiti OAuth disponibili e descrizioni di schemi, metodi, parametri e valori dei parametri disponibili.
Modello dati
Una risorsa è una singola entità di dati con un identificatore univoco. Il servizio di rilevamento delle API di Google opera su due tipi di risorse, in base ai concetti precedenti.
Elenco di directory API: un elenco di API
Ogni voce della directory contiene una coppia nome/versione dell'API con le seguenti informazioni:
- Informazioni di identificazione e descrizione: nome, versione, titolo e descrizione.
- Informazioni sulla documentazione: icone e un link alla documentazione.
- Informazioni sullo stato, incluse le etichette di stato, e un'indicazione su se si tratta o meno della versione preferita dell'API.
-
Link al documento di rilevamento: l'URI del documento di rilevamento per questa API
(fornito come URL completo, ad esempio
https://serviceusage.googleapis.com/$discovery/rest?version=v1).
Risorsa documento di rilevamento: una descrizione leggibile da computer di una determinata API
Oltre alle informazioni fornite nella Directory API, un documento di Discovery include anche:
- Schemi, ovvero un elenco di schemi di risorse API che descrivono i dati a cui hanno accesso in ogni API; gli schemi del servizio di rilevamento delle API di Google si basano su schema JSON.
- Metodi, incluso un elenco di metodi dell'API e parametri disponibili per ciascuno .
- Ambiti OAuth, che identifica l'elenco di ambiti OAuth disponibili per questo tramite Google Cloud CLI o tramite l'API Compute Engine.
- Documentazione in linea, che fornisce brevi descrizioni di schemi, metodi, parametri e valori dei parametri disponibili.
La singola raccolta di directory è il contenitore concettuale della risorsa Directory delle singole API e delle risorse del documento di scoperta per ogni API supportata.
Operazioni
Puoi invocare due metodi diversi su raccolte e risorse nel servizio di scoperta delle API di Google, come descritto nella tabella seguente.
| Operazione | Descrizione | Mappature REST HTTP |
|---|---|---|
| list | Elenca tutte le API supportate. | GET nell'URI della risorsa della directory. |
Stile di chiamata
REST
Le operazioni di Discovery Service delle API Google supportate mappano direttamente al verbo GET HTTP REST, come descritto in Operazioni.
Il formato specifico per gli URI del servizio di rilevamento API di Google è:
https://API/$discovery/rest?version=VERSION
dove API è l'identificatore di una risorsa Discovery Document e VERSION è l'identificatore della versione specifica dell'API.
Ecco un paio di esempi di come funziona nel servizio di rilevamento delle API di Google.
Elenca tutte le API supportate da Google APIs Discovery Service:
GET https://discovery.googleapis.com/discovery/v1/apis
Ottieni il documento di rilevamento per l'API Service Usage, versione 1:
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1