Introduzione
Questo documento è destinato agli sviluppatori che intendono scrivere librerie client, plug-in IDE e altri strumenti per interagire con le API di Google. Il servizio di individuazione delle API di Google ti consente di eseguire tutte le operazioni sopra riportate esponendo i metadati leggibili dalle macchine su altre API di Google tramite una semplice API. Questa guida fornisce una panoramica di ciascuna sezione del documento di rilevamento e suggerimenti utili su come utilizzarlo.
Tutte le chiamate all'API sono richieste REST non autenticate basate su JSON che utilizzano SSL, ovvero gli URL iniziano con https.
Se non hai familiarità con i concetti del servizio di rilevamento delle API di Google, leggi Guida introduttiva prima di iniziare la programmazione.
Formato del documento di rilevamento
Questa sezione fornisce una panoramica del documento di rilevamento.
Tutti gli esempi seguenti utilizzano il documento di rilevamento dell'API Google Cloud Service Management. Puoi caricare il documento Discovery per l'API Google Cloud Service Management eseguendo questa richiesta GET:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1Il formato di un documento di rilevamento include informazioni che rientrano in sei categorie principali:
- Descrizione di base dell'API.
- Informazioni di autenticazione per l'API.
- Dettagli su risorse e schemi che descrivono i dati dell'API.
- Dettagli sui metodi dell'API.
- Informazioni sulle funzionalità personalizzate supportate dall'API.
- Documentazione integrata che descrive gli elementi chiave dell'API.
Ciascuna di queste sezioni del documento di Discovery è descritta di seguito. Consulta la documentazione di riferimento per ulteriori dettagli su ogni proprietà.
Descrizione di base dell'API
Il documento discovery contiene una serie di proprietà specifiche dell'API:
"kind": "discovery#restDescription", "name": "servicemanagement", "version": "v1", "title": "Service Management API", "description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.", "protocol": "rest", "rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live", "servicePath": "",
Queste proprietà a livello di API includono dettagli su una determinata versione di un'API, tra cui name, version, title e description. protocol ha sempre un valore fisso di rest, poiché il servizio di rilevamento delle API supporta solo i metodi RESTful per accedere alle API.
Il campo servicePath indica il prefisso del percorso per questa versione API specifica.
Autenticazione
La sezione auth contiene dettagli sugli ambiti di autenticazione OAuth 2.0 per l'API. Per scoprire di più su come utilizzare gli ambiti con OAuth 2.0, consulta l'articolo Utilizzare OAuth 2.0 per accedere alle API di Google.
La sezione auth contiene una sezione nidificata oauth2 e scopes. La sezione scopes è una mappatura di coppie chiave-valore dal valore dell'ambito a ulteriori dettagli sull'ambito:
"auth": {
"oauth2": {
"scopes": {
"https://www.googleapis.com/auth/cloud-platform.read-only": {
"description": "View your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management.readonly": {
"description": "View your Google API service configuration"
},
"https://www.googleapis.com/auth/cloud-platform": {
"description": "View and manage your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management": {
"description": "Manage your Google API service configuration"
}
}
}
}
La sezione auth definisce solo gli ambiti di una specifica API. Per sapere come questi ambiti vengono associati a un metodo API, consulta la sezione Metodi riportata di seguito.
Risorse e schemi
Le operazioni di un'API agiscono su oggetti dati chiamati resources. Il documento di rilevamento si basa sul concetto di risorse. Ogni documento di rilevamento ha una sezione resources di primo livello che raggruppa tutte le risorse associate all'API. Ad esempio, l'API Google Cloud Service Management ha una risorsa services e una risorsa operations nel livello resources di primo livello, la risorsa services ha tre risorse secondarie, configs, rollouts e consumers:
"resources": {
"services": {
// Methods and sub-resources associated with the services resource
"configs": {
// Methods and sub-resources associated with the services.configs resource
},
"rollouts": {
// Methods and sub-resources associated with the services.rollouts resource
},
"consumers": {
// Methods and sub-resources associated with the services.consumers resource
}
},
"operations": {
// Methods and sub-resources associated with the operations resource
}
}
All'interno di ogni sezione delle risorse sono elencati i metodi associati. Ad esempio, l'API Google Cloud Service Management ha tre metodi associati alla risorsa services.rollouts: get, list e create.
Gli schemi indicano l'aspetto delle risorse in un'API. Ogni documento di rilevamento ha una sezione schemas di primo livello, che contiene una coppia nome/valore di ID schema nell'oggetto. Gli ID schema sono univoci per ciascuna API e vengono utilizzati per identificare in modo univoco lo schema nella sezione methods del documento di rilevamento:
"schemas": {
"Rollout": {
// JSON Schema of the Rollout resource.
}
}
API Discovery Service utilizza JSON Schema bozza-03 per le sue rappresentazioni di schema. Ecco uno snippet dello schema JSON per la risorsa URL, insieme a una risorsa di risposta effettiva:
| Implementazione dello schema JSON della risorsa: | Risposta effettiva della risorsa di implementazione: |
{
"Rollout": {
"id": "Rollout",
"type": "object",
"description": "...",
"properties": {
"serviceName": {
"type": "string",
"description": "..."
},
"rolloutId": {
"type": "string",
"description": "..."
},
"status": {
"type": "string",
"enum": [
"ROLLOUT_STATUS_UNSPECIFIED",
"IN_PROGRESS",
"SUCCESS",
"CANCELLED",
"FAILED",
"PENDING",
"FAILED_ROLLED_BACK"
],
"enumDescriptions": [
...
],
"description": "..."
},
"trafficPercentStrategy": {
"$ref": "TrafficPercentStrategy",
"description": "..."
},
"deleteServiceStrategy": { ... },
"createTime": { ... },
"createdBy": { ... }
}
}
}
|
{
"serviceName": "discovery.googleapis.com",
"rolloutId": "2020-01-01R0",
"status": "SUCCESS",
"trafficPercentStrategy":{
"precentages":{
"2019-12-01R0": 70.00,
"2019-11-01R0": 30.00
}
}
}
|
I campi in grassetto mostrano la mappatura tra lo schema JSON e la risposta effettiva.
Gli schemi possono contenere riferimenti anche ad altri schemi. Se stai creando una libreria client, questo può aiutarti a modellare in modo efficace gli oggetti di un'API nelle classi del modello di dati. Nell'esempio Rollout riportato sopra, la proprietà trafficPercentStrategy è in realtà un riferimento a uno schema con ID TrafficPercentStrategy. Se osservi la sezione schemas, troverai lo schema TrafficPercentStrategy. Il valore di questo schema può essere sostituito con la proprietà trafficPercentStrategy nella risorsa Rollout (tieni presente che la sintassi $ref deriva dalla specifica schema JSON).
I metodi possono fare riferimento anche agli schemi quando indicano i rispettivi corpi di richiesta e di risposta. Per ulteriori dettagli, consulta la sezione Metodi.
Metodi
Il principio del documento di rilevamento è basato su metodi. I metodi sono operazioni che possono essere eseguite su un'API. Troverai la sezione methods in diverse aree del documento di rilevamento, tra cui il livello superiore (che chiamiamo metodi a livello API) o il livello resources.
"methods": {
// API-level methods
}
"resources": {
"resource1": {
"methods": {
// resource-level methods
}
"resources": {
"nestedResource": {
"methods": {
// methods can even be found in nested-resources
}
}
}
}
}
Mentre un'API potrebbe avere metodi a livello di API, una risorsa deve avere una sezione methods.
Ogni sezione methods è una mappatura di coppie chiave-valore dal nome del metodo ad altri dettagli relativi. L'esempio seguente documenta tre metodi: get, list e create:
"methods": {
"get": { //details about the "get" method },
"list": { //details about the "list" method },
"create": { //details about the "create" method }
}
Infine, nella sezione di ogni metodo sono descritte in dettaglio le varie proprietà relative al metodo. Ecco un esempio del metodo get:
"get": {
"id": "servicemanagement.services.rollouts.get",
"path": "v1/services/{serviceName}/rollouts/{rolloutId}",
"flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
"httpMethod": "GET",
"description": "Gets a service configuration rollout.",
"response": { "$ref": "Rollout" },
"parameters": { // parameters related to the method },
"parameterOrder": [ // parameter order related to the method ],
"scopes": [ // OAuth 2.0 scopes applicable to this method ],
"mediaUpload": { // optional media upload information },
},
Questa sezione contiene dettagli generali sul metodo, ad esempio un metodo ID univoco per identificare il metodo, il metodo httpMethod da utilizzare e path del metodo (per informazioni dettagliate su come utilizzare la proprietà path per calcolare l'URL completo del metodo, consulta la sezione Scrivere una richiesta). Oltre a queste proprietà generali del metodo, esistono alcune proprietà che collegano il metodo ad altre sezioni nel documento di rilevamento:
Mirini con ingrandimento
La sezione auth definita in precedenza in questa documentazione contiene informazioni su tutti gli ambiti supportati da una determinata API. Se un metodo supporta uno di questi ambiti, avrà un array di ambiti. È presente una voce in questo array per ogni ambito supportato dal metodo. Ad esempio, la sezione scopes del metodo get dell'API Google Cloud Service Management ha il seguente aspetto:
"scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/cloud-platform.read-only", "https://www.googleapis.com/auth/service.management", "https://www.googleapis.com/auth/service.management.readonly" ]
Tieni presente che la scelta di un ambito di autenticazione da utilizzare nella tua applicazione dipende da vari fattori, ad esempio quali metodi vengono chiamati e quali parametri vengono inviati insieme al metodo. Pertanto, la scelta dell'ambito da utilizzare spetta allo sviluppatore. Il rilevamento rileva solo gli ambiti validi per un metodo.
Richiesta e risposta
Se il metodo ha un corpo della richiesta o di risposta, questi vengono documentati rispettivamente nelle sezioni request o response. Nell'esempio get sopra, il metodo ha un corpo response:
"response": {
"$ref": "Rollout"
}
La sintassi riportata sopra indica che il corpo della risposta è definito da uno schema JSON con un ID Rollout. Questo schema è disponibile nella sezione degli schemi di primo livello. Sia il corpo della richiesta sia il corpo della risposta utilizzano la sintassi $ref per fare riferimento agli schemi.
Parametri
Se un metodo ha parametri che devono essere specificati dall'utente, questi parametri sono documentati nella sezione parameters a livello di metodo. Questa sezione contiene una mappatura chiave/valore del nome del parametro a ulteriori dettagli sul parametro:
"parameters": {
"serviceName": {
"type": "string",
"description": "Required. The name of the service.",
"required": true,
"location": "path"
},
"rolloutId": { ... }
},
"parameterOrder": [
"serviceName",
"rolloutId"
]
Nell'esempio precedente, i parametri per il metodo get sono due:serviceName e rolloutId. I parametri possono essere inseriti in path o nell'URL query; la proprietà location indica dove la libreria client deve inserire il parametro.
Esistono molte altre proprietà che descrivono il parametro, tra cui i dati del parametro type (utili per le lingue altamente digitate), se il parametro è required e se il parametro è un'enumerazione. Consulta la Guida di riferimento per ulteriori dettagli sulle proprietà.
Ordine dei parametri
Le librerie client hanno a disposizione vari modi per strutturare le interfacce. Un modo è avere un metodo con ciascun parametro API nella firma del metodo. Tuttavia, poiché JSON è un formato non ordinato, è difficile sapere in modo programmatico come ordinare i parametri nella firma del metodo. L'array parameterOrder fornisce un ordine fisso di parametri per le richieste. L'array elenca il nome di ciascun parametro in ordine di significatività; può contenere parametri di percorso o di query, ma tutti i parametri nell'array sono obbligatori. Nell'esempio precedente, una firma del metodo Java potrebbe avere il seguente aspetto:
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);Il primo valore nell'array parameterOrder, serviceName, è anche il primo elemento nella firma del metodo. Se ci sono altri parametri nell'array di parameterOrder, seguono il parametro serviceName. Poiché l'array parameterOrder contiene solo i parametri richiesti, è buona norma includere un modo per consentire agli utenti di specificare anche i parametri facoltativi. L'esempio precedente utilizza la mappa optionalParameters.
Caricamento elementi multimediali
Se un metodo supporta il caricamento di contenuti multimediali come immagini, audio o video, la posizione e i protocolli supportati per il caricamento di tali contenuti multimediali sono documentati nella sezione mediaUpload. Questa sezione contiene dettagli sui protocolli di caricamento supportati e i tipi di contenuti multimediali che possono essere caricati:
"supportsMediaUpload": true,
"mediaUpload": {
"accept": [
"image/*"
],
"maxSize": "10MB",
"protocols": {
"simple": {
"multipart": true,
"path": "/upload/storage/v1beta1/b/{bucket}/o"
},
"resumable": {
"multipart": true,
"path": "/resumable/upload/storage/v1beta1/b/{bucket}/o"
}
}
}
Nell'esempio precedente, la proprietà supportsMediaUpload è un valore booleano che determina se il metodo supporta il caricamento di contenuti multimediali. Se il valore è true, la sezione mediaUpload documenta i tipi di contenuti multimediali che possono essere caricati.
La proprietà accept è un elenco di intervalli multimediali che determinano quali tipi MIME possono essere caricati. L'endpoint mostrato nell'esempio precedente accetterà qualsiasi formato dell'immagine.
La proprietà maxSize ha le dimensioni massime di un file caricato. Il valore è una stringa in unità di MB, GB o TB. Nell'esempio precedente, i caricamenti sono limitati a una dimensione massima di 10 MB. Tieni presente che questo valore non riflette la quota di spazio di archiviazione rimanente del singolo utente per quell'API, quindi, anche se il caricamento è inferiore a maxSize, la libreria client deve essere comunque pronta a gestire un caricamento non riuscito a causa dello spazio insufficiente.
Nella sezione protocols sono elencati i protocolli di caricamento supportati da un metodo. Il protocollo simple si limita a pubblicare i contenuti multimediali sull'endpoint specificato in una singola richiesta HTTP. Il protocollo resumable implica che l'endpoint fornito nell'URI path supporti il protocollo di caricamento ripristinabile. Se la proprietà multipart è true, l'endpoint accetta caricamenti con più parti, il che significa che sia la richiesta JSON che il contenuto multimediale possono essere aggregati in un corpo mutlipart/related e inviati insieme. Tieni presente che entrambi i protocolli simple e resumable potrebbero supportare i caricamenti a più parti.
La proprietà path è un modello URI e deve essere espansa proprio come la proprietà path per il metodo, come descritto nella sezione Scrivere una richiesta.
Download di contenuti multimediali
Il supporto del download di contenuti multimediali come immagini, audio o video indica il metodo supportsMediaDownload:
"supportsMediaDownload": true,
Quando scarichi contenuti multimediali, devi impostare il parametro di ricerca alt su media nell'URL della richiesta.
Se la proprietà useMediaDownloadService del metodo API è true, inserisci /download prima di servicePath per evitare un reindirizzamento. Ad esempio, il percorso di download è /download/youtube/v3/captions/{id} se la concatenazione di servicePath e path è /youtube/v3/captions/{id}. Ti consigliamo di creare un URL di download multimediale con /download anche quando useMediaDownloadService è falso.
Parametri comuni
Il documento di rilevamento di primo livello contiene una proprietà parameters. Questa sezione è simile alla sezione dei parametri per ogni metodo, ma può essere applicata a qualsiasi metodo nell'API.
Ad esempio, i metodi get, insert o list dell'API Google Cloud Service Management possono includere un parametro prettyPrint nei parametri della richiesta, che formattano la risposta per tutti questi metodi in un formato leggibile. Ecco un elenco dei parametri più comuni:
| Parametro | Significato | Note | Applicabilità |
|---|---|---|---|
access_token |
Token OAuth 2.0 per l'utente corrente. |
|
|
alt |
Formato dei dati per la risposta. |
|
|
callback |
Funzione di callback. |
| |
fields |
Selettore che specifica un sottoinsieme di campi da includere nella risposta. |
|
|
key |
chiave API. (Obbligatorio*) |
|
|
prettyPrint |
Restituisce la risposta con identazioni e interruzioni di riga. |
|
|
quotaUser |
Musica alternativa a userIp. |
|
|
userIp |
Indirizzo IP dell'utente finale per il quale viene effettuata la chiamata API. |
|
Funzionalità
In alcuni casi le API supportano funzionalità personalizzate che non rientrano nell'ambito del resto del documento di rilevamento. che vengono raccolti nell'array features. L'array di caratteristiche contiene un'etichetta stringa per ogni caratteristica speciale supportata dall'API. dataWrapper è attualmente l'unica funzionalità supportata, ma in futuro potrebbero essere supportate altre funzionalità.
"features": dataWrapper
La funzionalità dataWrapper indica che tutte le richieste e le risposte dell'API sono aggregate in un oggetto JSON data. Questa è una funzionalità delle API di Google meno recenti, ma verrà ritirata in futuro. Le seguenti API supportano la funzionalità dataWrapper: Moderatore v1 e Traduttore v2.
Come sviluppatore di una libreria client, se un'API supporta la funzionalità "dataWrapper" devi fare quanto segue:
- Per le richieste: esegui il wrapping della risorsa di richiesta in un oggetto JSON
data. - Alle risposte: trova la risorsa all'interno di un oggetto JSON
data.
Gli schemi nel documento di rilevamento non contengono il wrapper dati, quindi devi aggiungerli e rimuoverli esplicitamente. Ad esempio, supponiamo che esista un'API con una risorsa denominata "Foo" che ha il seguente aspetto:
{
"id": 1,
"foo": "bar"
}
Prima di inserire questa risorsa utilizzando l'API, devi aggregarla in un elemento dati:
{
"data": {
"id": 1,
"foo": "bar"
}
}
mentre quando ricevi una risposta dall'API contiene anche il wrapper dati:
{
"data": {
"id": 1,
"foo": "bar"
}
}
Per ottenere la risorsa definita dallo schema, devi rimuovere il wrapper dati:
{
"id": 1,
"foo": "bar"
}
Documentazione in linea
Ogni documento di rilevamento è annotato con una serie di campi description che forniscono documentazione in linea per l'API. I campi description sono disponibili per i seguenti elementi API:
- API stessa
- Ambiti OAuth
- Schemi di risorse
- Metodi API
- Parametri del metodo
- Valori accettati per determinati parametri
Questi campi sono particolarmente utili se vuoi utilizzare il servizio di rilevamento delle API di Google per generare documentazione leggibile da parte di una libreria client, ad esempio JavaDoc.