Creare una libreria client

Introduzione

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 di scoperta è consentire a Google di creare librerie client in vari linguaggi di programmazione. Questa sezione spiega come procedere per creare una libreria client personalizzata per le API di Google.

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

  1. Recupero del documento di rilevamento e creazione della superficie API
  2. Scrivere una richiesta
  3. Effettuare una chiamata e recuperare la risposta

Questi passaggi sono descritti più dettagliatamente nelle sezioni seguenti. Puoi anche consultare l'esempio di client delle API semplici nella sezione Esempi per vedere come queste istruzioni vengono mappate al codice.

Passaggio 1: recupera il documento di rilevamento

Prima di iniziare a implementare una libreria client, esistono alcuni requisiti di base che incidono sul modo in cui procedi nel percorso di sviluppo. Ad esempio, il tuo linguaggio di programmazione preferito può essere digitato o non digitato; se è digitato, potrebbe essere digitato in modo statico o dinamico. Può essere compilata o interpretata. Questi requisiti ti aiuteranno a gestire e utilizzare il documento discovery.

La prima attività di sviluppo consiste nel recuperare il documento di rilevamento. La tua strategia relativa al momento esatto in cui recuperare il documento è determinata dai requisiti identificati. Ad esempio, in un linguaggio digitato in modo statico, potresti recuperare il documento di rilevamento all'inizio del processo e poi generare codice per gestire l'API specifica descritta dal documento di rilevamento. Per un linguaggio altamente digitato, potresti generare del codice e creare una libreria compilata. Per un linguaggio digitato in modo dinamico, puoi creare lentamente le strutture di programmazione per interagire con l'API sul momento in cui viene utilizzata la piattaforma di programmazione.

Passaggio 2: scrivi una richiesta

La scrittura di una richiesta prevede due passaggi distinti:

  1. Composizione del corpo della richiesta.
  2. Creazione dell'URL della richiesta in corso...

Devi convertire il corpo della richiesta, se presente, da una rappresentazione appropriata per la lingua nel formato del cavo corretto. Ad esempio, in una libreria client Java, può esistere una classe per ogni tipo di richiesta che consente la manipolazione sicura del tipo dei dati della richiesta e può essere serializzata in JSON.

La struttura dell'URL della richiesta è una procedura leggermente più complicata.

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

/example/path/var

Nel percorso precedente, var è una variabile. Il valore di questa variabile proviene dalla sezione parameters del documento di Discovery relativo a tale metodo. Ogni nome di variabile ha un valore corrispondente nell'oggetto parameters. Nell'esempio precedente è presente un parametro denominato var nella sezione parameters e la relativa proprietà location è path, a indicare che si tratta di una variabile del percorso.

Quando presenti una richiesta, devi sostituire il valore di var nell'URL. Ad esempio, se l'utente della biblioteca effettua 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, procedi come riportato di seguito:

  1. Raccogli la proprietà rootUrl dal livello più alto del documento di rilevamento.
    Ad esempio, la proprietà rootUrl nel documento Discovery per l'API Google Cloud Service Management è:

    https://servicemanagement.googleapis.com/

  2. Raccogli servicePath dal livello superiore del documento di rilevamento.
    Ad esempio, la proprietà servicePath nel documento Discovery per l'API Google Cloud Service Management è vuota.

  3. Concatenali per ottenere:

    https://servicemanagement.googleapis.com/

  4. Acquisisci la proprietà path, espandila come modello URI e combina i risultati di tale espansione con l'URI del passaggio precedente.
    Ad esempio, nel metodo di servizio get di Google Cloud Service Management API, il valore della proprietà path è v1/services/{serviceName}. Di seguito è riportato l'URI completo del metodo:

    https://servicemanagement.googleapis.com/v1/services/{serviceName}

Per chiamare l'API Google Cloud Service Management è necessaria una chiave API. Quindi, dopo aver applicato una chiave API, l'URI completo per ottenere la definizione del servizio di API Discovery Service è:

https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY

Passaggio 3: fai una chiamata e gestisci la risposta

Dopo aver inviato la richiesta, devi deserializzare la risposta nella rappresentazione del linguaggio appropriata, occupandoti 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 di stile JSON di Google.

Esempi

Per alcuni esempi concreti di librerie client e strumenti che sono stati implementati con il servizio di individuazione delle API di Google, consulta il documento Librerie ed esempi. Inoltre, la sezione seguente fornisce un semplice esempio di una libreria client 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 Google Cloud Service Management, quindi recupera la definizione di servizio di API Discovery Service utilizzando tale interfaccia.

Avviso: il codice seguente è una versione semplificata di una libreria client tipica. Si tratta di un'implementazione incompleta che viene fornita per dimostrare alcuni aspetti della creazione di una libreria client. Il codice non è pronto per la produzione.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://servicemanagement.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)

# Step 2.a: Construct base URI
BASE_URL = discovery['rootUrl'] + 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 (service.services.get(serviceName='discovery.googleapis.com', key='API_KEY'))

I componenti chiave del client sono:

  • Passaggio 1: recupera il documento di rilevamento.
    Il documento di rilevamento per l'API Google Cloud Service Management viene recuperato e analizzato in una struttura di dati. Poiché Python è un linguaggio digitato in modo dinamico, il documento di rilevamento può essere recuperato in fase di runtime.
  • Passaggio 2.a: crea l'URI di base.
    Viene calcolato l'URI di base.
  • Passaggio 2.b: scrivi la richiesta.
    Quando un metodo viene chiamato in una raccolta, il modello di URI viene espanso con i parametri passati nel metodo e i parametri con una posizione query vengono inseriti nei parametri di ricerca dell'URL. Infine viene inviata una richiesta all'URL composto utilizzando il metodo HTTP specificato nel documento di rilevamento.
  • Passaggio 3a. Crea la piattaforma client.
    La superficie del client viene creata in modo ricorsivo in ordine decrescente sul documento discovery analizzato. Per ogni metodo nella sezione methods viene collegato un nuovo metodo all'oggetto Collection. Poiché è possibile nidificare le raccolte, cerchiamo resources e creiamo in modo ricorsivo un oggetto Collection per tutti i suoi membri, se ne viene trovato uno. Ogni collezione nidificata è anche allegata come attributo all'oggetto Collection.
  • Passaggio 3.b: utilizza il client.
    Ciò dimostra come viene utilizzata la piattaforma API creata. Prima di tutto, un oggetto di servizio viene creato dal documento Discovery, quindi la definizione del servizio di API Discovery Service viene recuperata tramite l'API Google Cloud Service Management.