Alcune o tutte le informazioni in questa pagina potrebbero non essere applicabili a Trusted Cloud di S3NS. Per ulteriori dettagli, consulta la sezione Differenze rispetto a Google Cloud.

Questa pagina è stata tradotta dall'API Cloud Translation.

Creare una libreria client

Puoi utilizzare il servizio di rilevamento delle API di Google per creare una serie di strumenti diversi da utilizzare con le API di Google. Tuttavia, lo scopo principale del documento Discovery è consentire a Google di creare librerie client in vari linguaggi di programmazione. Questo documento descrive come creare una libreria client personalizzata per le API di Google.

Una libreria client stabile e completa di funzionalità è uno strumento complicato che può richiedere mesi di sviluppo. Tuttavia, le istruzioni generali per creare una semplice libreria client per le API di Google possono essere suddivise in tre semplici passaggi:

Recupero del documento di rilevamento e creazione dell'interfaccia API
Compilazione di una richiesta
Effettuare una chiamata e recuperare la risposta

Questi passaggi sono descritti in maggiore dettaglio nelle sezioni seguenti. Puoi anche dare un'occhiata all'esempio di client API semplici nella sezione Esempi per vedere come queste istruzioni vengono associate al codice.

Recupera il documento di rilevamento

Prima di iniziare a implementare una libreria client, ci sono alcuni requisiti di base che influiscono sul modo in cui procederai nel tuo percorso di sviluppo. Ad esempio, il linguaggio di programmazione scelto può essere a tipi o senza tipi; se è a tipi, può essere a tipi statici o dinamici. Può essere compilato o interpretato. Questi requisiti guideranno il tuo approccio all'utilizzo del documento Discovery.

La prima attività di sviluppo consiste nel recuperare il documento Discovery. La strategia per stabilire esattamente quando recuperare il documento è determinata dai requisiti che hai identificato. Ad esempio, in un linguaggio a tipizzazione statica, potresti recuperare il documento di rilevamento all'inizio del processo e poi generare il codice per gestire l'API specifica descritta dal documento di rilevamento. Per un linguaggio fortemente tipizzato, puoi generare del codice e creare una libreria compilata. Per un linguaggio con tipi dinamici, puoi creare in modo lazy le strutture di programmazione per interfacciarti all'API al volo durante l'utilizzo della piattaforma di programmazione.

Compilare una richiesta

La composizione di una richiesta prevede due passaggi distinti:

Compila il corpo della richiesta.
Creazione dell'URL della richiesta.

Devi convertire il corpo della richiesta, se presente, da una rappresentazione appropriata per la lingua nel formato corretto del messaggio. Ad esempio, in una libreria client Java, potrebbe essere presente una classe per ogni tipo di richiesta che consenta la manipolazione sicura dei dati della richiesta ed è serializzabile in JSON.

La costruzione dell'URL della richiesta è un processo leggermente più complicato.

La proprietà path di ogni metodo nell'API utilizza la sintassi del modello URI v04. Questa proprietà può contenere variabili, che sono racchiuse tra parentesi graffe. Ecco un esempio di proprietà path con variabili:

/example/path/var

Nel percorso riportato sopra, var è una variabile. Il valore di questa variabile proviene dalla sezione parameters del documento Discovery per quel metodo. Ogni nome di variabile ha un valore corrispondente nell'oggetto parameters. Nell'esempio riportato sopra, nella sezione parameters è presente un parametro denominato var (la cui proprietà location è path per indicare che si tratta di una variabile del percorso).

Quando effettui una richiesta, devi sostituire il valore di var nell'URL. Ad esempio, se l'utente della raccolta fa una scelta che imposta var sul valore foo, il nuovo URL sarà /example/path/foo.

Tieni inoltre presente che la proprietà path è un URI relativo. Per calcolare l'URI assoluto:

Se conosci la tua località (regione) e il documento Discovery contiene la proprietà endpoints, controlla se la tua località è presente nell'elenco endpoints. In questo caso, prendi il endpointUrl dall'elenco endpoints il cui location corrisponde al tuo.
Se nel documento Discovery non è presente una proprietà endpoints, se la tua località non è presente nell'elenco endpoints o se vuoi scegliere come target l'endpoint globale, recupera la proprietà endpoints dal livello superiore del documento Discovery.rootUrl

Ad esempio, la proprietà rootUrl nel documento di rilevamento per l'API Service Usage è:
```
https://serviceusage.s3nsapis.fr/
```
Recupera il servicePath dal livello superiore del documento Discovery. Ad esempio, la proprietà servicePath nel documento Discovery per l'API Service Usage è vuota.
Concatenali per ottenere:
```
https://serviceusage.s3nsapis.fr/
```
Recupera la proprietà path, espandila come modello URI e combina i risultati di questa espansione con l'URI del passaggio precedente. Ad esempio, nel metodo serviceusage.services.enable dell'API Servizio di utilizzo v1, il valore della proprietà path è v1/{+name}:enable. Pertanto, l'URI completo per il metodo è:
```
https://serviceusage.s3nsapis.fr/v1/{+name}:enable
```

Non è necessaria una chiave API per chiamare l'API Service Usage. Tuttavia, se l'API che stai chiamando richiede una chiave API, puoi aggiungerla alla stringa di query dell'URI:

REQUEST_URI?key=API_KEY

Effettua una chiamata e gestisci la risposta

Dopo aver inviato la richiesta, devi deserializzare la risposta nella rappresentazione del linguaggio appropriata, avendo cura di gestire le condizioni di errore che potrebbero verificarsi, sia nel trasporto HTTP sottostante sia nei messaggi di errore generati dal servizio API. Il formato degli errori è documentato nella Guida allo stile JSON di Google.

Esempi

La sezione seguente fornisce un semplice esempio di libreria client per le API.

Client API semplici

Di seguito è riportato un esempio di libreria client molto semplice scritta in Python3. Il client crea un'interfaccia per interagire con l'API Service Usage, quindi la utilizza per attivare l'API Compute Engine (compute.googleapis.com) nel progetto my-project.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://serviceusage.s3nsapis.fr/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)
location = None # Set this to your location if appropriate
use_global_endpoint = True # Set this to False if you want to target the endpoint for your location

# Step 2.a: Construct base URI
BASE_URL = None
if not use_global_endpoint and location:
  if discovery['endpoints']:
    BASE_URL = next((item['endpointUrl'] for item in discovery['endpoints'] if item['location'] == location), None)
if not BASE_URL:
  BASE_URL = discovery['rootUrl']
BASE_URL += discovery['servicePath']

class Collection(object): pass

def createNewMethod(name, method):
  # Step 2.b Compose request
  def newMethod(**kwargs):
    body = kwargs.pop('body', None)
    url = urllib.parse.urljoin(BASE_URL, uritemplate.expand(method['path'], kwargs))
    for pname, pconfig in method.get('parameters', {}).items():
      if pconfig['location'] == 'path' and pname in kwargs:
        del kwargs[pname]
    if kwargs:
      url = url + '?' + urllib.parse.urlencode(kwargs)
    return h.request(url, method=method['httpMethod'], body=body,
                     headers={'content-type': 'application/json'})

  return newMethod

# Step 3.a: Build client surface
def build(discovery, collection):
  for name, resource in discovery.get('resources', {}).items():
    setattr(collection, name, build(resource, Collection()))
  for name, method in discovery.get('methods', {}).items():
    setattr(collection, name, createNewMethod(name, method))
  return collection

# Step 3.b: Use the client
service = build(discovery, Collection())
print (serviceusage.services.enable(name='projects/my-project/services/compute.googleapis.com'))

I componenti fondamentali del client sono:

Passaggio 1: recupera il documento Discovery. Il documento di discovery per l'API Service Usage viene recuperato e analizzato in una struttura di dati. Poiché Python è un linguaggio a tipizzazione dinamica, il documento Discovery può essere recuperato in fase di esecuzione.
Passaggio 2.a: crea l'URI base. Viene calcolato l'URI di base.
Passaggio 2.b: componila richiesta. Quando viene chiamato un metodo su una raccolta, il modello di URL viene espanso con i parametri passati al metodo e i parametri con una posizione query vengono inseriti nei parametri di query dell'URL. Infine, viene inviata una richiesta all'URL composto utilizzando il metodo HTTP specificato nel documento Discovery.
Passaggio 3.a: crea la piattaforma client. L'interfaccia del client viene creata con una ricerca ricorsiva nel documento di rilevamento analizzato. Per ogni metodo nella sezione methods viene associato un nuovo metodo all'oggetto Collection. Poiché le raccolte possono essere nidificate, cerchiamo resources e, se ne viene trovato uno, costruiamo ricorsamente un oggetto Collection per tutti i relativi membri. Ogni raccolta nidificata viene anche collegata come attributo all'oggetto Collection.
Passaggio 3.b: utilizza il client. Questo dimostra come viene utilizzata la piattaforma API creata. Innanzitutto viene creato un oggetto di servizio dal documento Discovery, quindi l'API Service Usage viene utilizzata per attivare l'API Compute Engine nel progetto my-project.