Questo documento è rivolto agli sviluppatori che vogliono scrivere librerie client, plug-in IDE e altri strumenti per interagire con le API di Google. Il servizio di rilevamento delle API di Google ti consente di eseguire tutte le operazioni elencate sopra esponendo metadati leggibili dalla macchina su altre API di Google tramite una semplice API. Questa guida fornisce una panoramica di ogni sezione del documento Discovery, nonché suggerimenti utili su come utilizzarlo.
Tutte le chiamate all'API sono richieste REST non autenticate basate su JSON che utilizzano SSL. In altre parole, gli URL iniziano con https.
Formato del documento di rilevamento
Questa sezione fornisce una panoramica del documento Discovery.
Tutti gli esempi riportati di seguito utilizzano il documento di rilevamento dell'API Service Usage.
Puoi caricare il
documento di rilevamento
per l'API Service Usage eseguendo questa richiesta GET:
GET https://serviceusage.s3nsapis.fr/$discovery/rest?version=v1
Il 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 delle risorse e dello schema che descrivono i dati dell'API.
- Dettagli sui metodi dell'API.
- Informazioni su eventuali funzionalità personalizzate supportate dall'API.
- Documentazione in linea che descrive gli elementi chiave dell'API.
Ognuna di queste sezioni del documento discovery è descritta di seguito.
Descrizione API di base
Il documento Discovery contiene un insieme di proprietà specifiche dell'API. Queste proprietà non necessariamente vengono visualizzate in questo ordine o nella stessa sezione del documento di discovery:
"id": "serviceusage:v1", "canonicalName": "Service Usage", "revision": "20240331", "servicePath": "", "baseUrl": "https://serviceusage.s3nsapis.fr/", "kind": "discovery#restDescription", "description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.", "ownerDomain": "google.com", "version_module": true, "version": "v1", "fullyEncodeReservedExpansion": true, "name": "serviceusage", "title": "Service Usage API", "discoveryVersion": "v1", "rootUrl": "https://serviceusage.s3nsapis.fr/", "protocol": "rest"
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 determinata versione dell'API.
Autenticazione
La sezione auth contiene i dettagli sugli ambiti di autenticazione OAuth 2.0 per l'API. Per approfondire 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 oauth2 e scopes nidificata. La sezione scopes è una mappatura chiave/valore dal valore dell'ambito a ulteriori dettagli sull'ambito:
"auth": { "oauth2": { "scopes": { "https://www.googleapis.com/auth/cloud-platform": { "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account." }, "https://www.googleapis.com/auth/cloud-platform.read-only": { "description": "View your data across Google Cloud services and see the email address of your Google Account" }, "https://www.googleapis.com/auth/service.management": { "description": "Manage your Google API service configuration" } } } }
La sezione auth definisce solo gli ambiti per una determinata API. Per scoprire come questi ambiti vengono associati a un metodo dell'API, consulta la sezione Metodi 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 contiene una sezione di primo livello
resources che raggruppa tutte le risorse associate all'API. Ad esempio, l'API Service Usage ha una risorsa services e una risorsa operations in resources di primo livello:
"resources": { "services": { // Methods associated with the services resource } "operations": { // Methods associated with the operations resource } }
All'interno di ogni sezione delle risorse sono presenti i metodi associati alla risorsa. Ad esempio,
l'API Service Usage ha sei metodi associati alla risorsa services: get, enable, disable, batchGet,
batchEnable e list.
Gli schemi indicano la struttura delle risorse di un'API. Ogni documento Discovery ha una
sezione schemas di primo livello, che contiene una coppia nome/valore dell'ID schema per
l'oggetto. Gli ID schema sono univoci per ogni API e vengono utilizzati per identificare in modo univoco lo schema nella
methods sezione del documento Discovery. Ad esempio, ecco alcuni degli schemi nel documento di scoperta dell'API Service Usage:
"schemas": { "Method": { // JSON schema of the Method resource }, "Authentication": { // JSON schema of the Authentication resource }, "RubySettings": { // JSON schema of the RubySettings resource }, "EnableServiceResponse": { // JSON schema of the EnableServiceResponse resource } }
Il servizio di rilevamento delle API utilizza JSON
Schema draft-03 per le sue rappresentazioni dello schema. Di seguito è riportato uno snippet dello schema JSON per la risorsa EnableServiceResponse, insieme al GoogleApiServiceusagev1Service a cui fa riferimento. Accanto a questi schemi è presente una
parte di una risposta effettiva per una richiesta di abilitazione dell'API Pub/Sub
(pubsub.googleapis.com).
Schema JSON della risorsa EnableServiceResponse: |
Risposta effettiva per l'attivazione di un servizio: |
"EnableServiceResponse": { "id": "EnableServiceResponse", "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.", "properties": { "service": { "description": "The new state of the service after enabling.", "$ref": "GoogleApiServiceusageV1Service" } }, "type": "object" }, "GoogleApiServiceusageV1Service": { "description": "A service that is available for use by the consumer.", "properties": { "config": { "$ref": "GoogleApiServiceusageV1ServiceConfig", "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method." }, "name": { "type": "string", "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com" }, " |
"response": { "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse", "service": { "name": "projects/232342569935/services/pubsub.googleapis.com", "config": { "name": "pubsub.googleapis.com", "title": "Cloud Pub/Sub API", "documentation": { "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n" }, "quota": {}, "authentication": {}, "usage": { "requirements": [ "serviceusage.googleapis.com/tos/cloud" ] }, "monitoring": {} }, " |
I campi in grassetto mostrano la mappatura tra lo schema JSON e la risposta effettiva.
Come mostrato in questo esempio, gli schemi possono contenere riferimenti 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 tuo modello di dati. Nell'esempio EnableServiceResponse riportato sopra, la proprietà service è un riferimento a uno schema con ID GoogleApiServiceusageV1Service, un altro schema nel documento di rilevamento dell'API Service Usage. Puoi sostituire la proprietà GoogleApiServiceusageV1Service nella risorsa EnableServiceResponse con il valore dello schema GoogleApiServiceusageV1Service (tieni presente che la sintassi $ref proviene dalla specifica JSON Schema).
I metodi possono anche fare riferimento agli schemi quando indicano i relativi corpi di richiesta e risposta. Per ulteriori dettagli, consulta la sezione Metodi.
Metodi
Il nucleo del documento di rilevamento si basa sui metodi. I metodi sono le operazioni che possono essere eseguite su un'API. La sezione methods si trova in varie aree del
documento di rilevamento, ad esempio a livello superiore (chiamati metodi a livello di API) o
a livello di resources.
"methods": { // API-level methods } "resources": { "resource1": { "methods": { // resource-level methods } "resources": { "nestedResource": { "methods": { // methods can even be found in nested-resources } } } } }
Sebbene un'API possa avere metodi a livello di API, una risorsa deve avere una sezione
methods.
Ogni sezione methods è una mappa chiave-valore dal nome del metodo ad altri dettagli su quel metodo. L'esempio riportato di seguito illustra tre metodi: get, enable
e disable:
"methods": { "get": { //details about the "get" method }, "enable": { //details about the "enable" method }, "disable": { //details about the "disable" method } }
Infine, la sezione di ogni metodo descrive in dettaglio le varie proprietà del metodo. Ecco un
esempio del metodo enable:
"enable": { "path": "v1/{+name}:enable", "request": { "$ref": "EnableServiceRequest" }, "parameterOrder": [ "name" ], "id": "serviceusage.services.enable", "response": { "$ref": "Operation" }, "description": "Enable a service so that it can be used with a project.", "httpMethod": "POST", "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable", "scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/service.management" ], "parameters": { "name": { "location": "path", "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.", "required": true, "type": "string", "pattern": "^[^/]+/[^/]+/services/[^/]+$" } } },
Questa sezione contiene dettagli generali del metodo, ad esempio un ID univoco per identificare il metodo, il httpMethod da utilizzare e il path del metodo (per dettagli su come utilizzare la proprietà path per calcolare l'URL completo del metodo, consulta la sezione Componi una richiesta). Oltre a queste proprietà metodi generali, esistono alcune proprietà che collegano il metodo ad altre sezioni del documento Discovery:
Ambiti
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. Questo array contiene una voce per ogni ambito supportato dal metodo.
Tieni presente che la scelta di un ambito di autenticazione da utilizzare nella tua applicazione dipende da vari fattori, ad esempio i metodi chiamati e i parametri inviati insieme al metodo. Pertanto, la decisione su quale ambito utilizzare è lasciata allo sviluppatore. Discovery mostra solo i documenti per i quali gli scopi sono validi per un metodo.
Richiesta e risposta
Se il metodo ha un corpo della richiesta o della risposta, questi sono documentati rispettivamente nelle sezioni request
o response. Ad esempio, per il metodo enable, i contenuti della sezione request indicano che la richiesta del metodo è definita da uno schema JSON con un ID EnableServiceRequest. Questo schema è disponibile nella sezione degli schemi di primo livello.
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 con ulteriori dettagli sul parametro.
Ad esempio, esiste un parametro per il metodo enable: name.
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, inclusi i dati del parametro
type (utili per i linguaggi fortemente tipizzati), se il parametro è
required e se è un enum. Per ulteriori dettagli su queste proprietà, consulta la documentazione di riferimento
di questa API.
Ordine dei parametri
Esistono molti modi per strutturare le interfacce delle librerie client. Un modo è avere un metodo con ogni parametro dell'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 dei parametri per effettuare richieste. L'array elenca il nome di ogni parametro in ordine di importanza. Può contenere parametri di percorso o di query, ma ogni parametro dell'array è obbligatorio.
Caricamento di contenuti 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 questi contenuti sono documentati nella sezione mediaUpload. Questa sezione contiene dettagli sui protocolli di caricamento supportati e informazioni sui tipi di contenuti multimediali che possono essere caricati.
Il metodo enable non contiene una sezione mediaUpload. Tuttavia, una
sezione mediaUpload tipica potrebbe avere il seguente aspetto:
"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 descrive i tipi di contenuti multimediali che possono essere caricati.
La proprietà accept è un elenco di intervalli multimediali che determinano quali tipi di mime sono accettabili per il caricamento. L'endpoint mostrato nell'esempio precedente accetta qualsiasi formato di immagine.
La proprietà maxSize ha la dimensione massima di un caricamento. Il valore è una stringa in unità di MB, GB o TB. Nell'esempio riportato sopra, 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 di un singolo utente per quell'API, pertanto anche se il caricamento è inferiore a maxSize, la libreria client deve essere comunque preparata a gestire un caricamento che non va a buon fine a causa di spazio insufficiente.
La sezione protocols elenca i protocolli di caricamento supportati da un metodo. Il
protocollo simple esegue semplicemente il POST dei contenuti multimediali all'endpoint specificato in una singola
richiesta HTTP. Il protocollo resumable presuppone che l'endpoint specificato nell'URI path supporti il protocollo di caricamento supportato. Se la proprietà multipart è true, l'endpoint accetta caricamenti multiparte, il che significa che sia la richiesta JSON sia i contenuti multimediali possono essere raggruppati in un corpo multipart/related e inviati insieme. Tieni presente che entrambi i protocolli simple e resumable potrebbero supportare i caricamenti suddivisi in più parti.
La proprietà path è un modello di URI e deve essere espansa come la proprietà path per il metodo, come descritto nella sezione Componi una richiesta.
Download di contenuti multimediali
Se un metodo supporta il download di contenuti multimediali, come immagini, audio o video, lo indica
il parametro supportsMediaDownload:
"supportsMediaDownload": true,
Quando scarichi contenuti multimediali, devi impostare il parametro di query 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}. È consigliato di creare l'URL di download dei contenuti multimediali con /download anche quando useMediaDownloadService è false.
Parametri comuni
Il documento discovery di primo livello contiene una proprietà parameters. Questa sezione è simile alla sezione dei parametri per ogni metodo, ma questi parametri possono essere applicati a qualsiasi metodo dell'API.
Ad esempio, i metodi get e list dell'API Service Usage possono avere un parametro prettyPrint nei parametri di richiesta, che formatta la risposta per tutti questi metodi in un formato leggibile da un utente. Ecco un elenco di parametri 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 rientri e a capo. |
|
|
quotaUser |
Alternativa a userIp. |
|
|
userIp |
Indirizzo IP dell'utente finale per cui viene effettuata la chiamata all'API. |
|
Documentazione in linea
Ogni documento di rilevamento è annotato con una serie di campi description che forniscono la documentazione in linea per l'API. I campi description sono disponibili per
i seguenti elementi dell'API:
- L'API stessa
- ambiti OAuth
- Schemi delle risorse
- Metodi API
- Parametri del metodo
- Valori accettabili per determinati parametri
Questi campi sono particolarmente utili se vuoi utilizzare il servizio di rilevamento delle API di Google per generare documentazione di facile lettura per una libreria client, ad esempio JavaDoc.