Il est possible qu'une partie ou l'ensemble des informations de cette page ne s'appliquent pas au Cloud de confiance S3NS.

Créer une bibliothèque cliente

Le service de découverte des API Google vous permet de créer différents outils à utiliser avec les API Google. Cependant, l'objectif principal du document de découverte est de permettre à Google de créer des bibliothèques clientes dans différents langages de programmation. Ce document explique comment créer une bibliothèque cliente personnalisée pour les API Google.

Une bibliothèque cliente stable et dotée de fonctionnalités complètes est un outil complexe dont le développement peut prendre des mois. Toutefois, les instructions générales permettant de créer une bibliothèque cliente simple pour les API Google peuvent être divisées en trois étapes simples :

Récupérer le document de découverte et créer la surface de l'API
Rédiger une requête
Passer un appel et récupérer la réponse

Ces étapes sont décrites plus en détail dans les sections suivantes. Vous pouvez également consulter l'exemple Client d'API simple dans la section "Exemples" pour voir comment ces instructions sont mappées au code.

Récupérer le document de découverte

Avant de commencer à implémenter une bibliothèque cliente, certaines exigences de base s'appliquent à la façon dont vous allez procéder au développement. Par exemple, le langage de programmation de votre choix peut être saisi ou non. Dans le premier cas, il peut être saisi de manière statique ou dynamique. Il peut être compilé ou interprété. Ces exigences vous guideront dans votre approche pour utiliser le document de découverte.

La première tâche de développement consiste à récupérer le document de découverte. Votre stratégie pour connaître le moment exact où le document doit être récupéré est déterminée par les exigences que vous avez identifiées. Par exemple, dans un langage saisi de type statique, vous pouvez récupérer le document de découverte au début du processus, puis générer du code pour gérer l'API spécifique décrite dans ce document. Pour un langage fortement typé, vous pouvez générer du code et créer une bibliothèque compilée. Pour un langage saisi de manière dynamique, vous pouvez créer tardivement les structures de programmation permettant de communiquer avec l'API instantanément lorsque la surface de programmation est utilisée.

Rédiger une requête

La rédaction d'une requête comprend deux étapes distinctes :

Rédaction du corps de la requête
Création de l'URL de la requête

Vous devez convertir le corps de la requête d'une représentation propre au langage au format de transmission approprié, le cas échéant. Par exemple, dans une bibliothèque cliente Java, il peut y avoir une classe pour chaque type de requête qui permet une manipulation sécurisée des données de la requête et qui est sérialisable au format JSON.

La construction de l'URL de la requête est un processus légèrement plus complexe.

La propriété path de chaque méthode de l'API utilise la syntaxe du modèle d'URI v04. Cette propriété peut contenir des variables placées entre accolades. Voici un exemple de propriété path avec des variables :

/example/path/var

Dans le chemin ci-dessus, var est une variable. La valeur de cette variable provient de la section parameters du document de découverte pour cette méthode. Chaque nom de variable a une valeur correspondante dans l'objet parameters. Dans l'exemple ci-dessus, il existe un paramètre nommé var dans la section parameters (et sa propriété location est path) pour indiquer qu'il s'agit d'une variable de chemin.

Lorsque vous envoyez une requête, vous devez remplacer la valeur de var dans l'URL. Par exemple, si l'utilisateur de la bibliothèque définit var sur la valeur foo, la nouvelle URL sera /example/path/foo.

Notez également que la propriété path est un URI relatif. Pour calculer l'URI absolu, procédez comme suit :

Si vous connaissez votre emplacement (région) et que le document de découverte contient la propriété endpoints, vérifiez si votre emplacement est présent dans la liste endpoints. Si tel est le cas, récupérez l'URL endpointUrl dans la liste endpoints dont l'emplacement (location) correspond au vôtre.
Si le document de découverte ne contient pas de propriété endpoints, si votre emplacement ne figure pas dans la liste endpoints ou si vous souhaitez cibler le point de terminaison mondial, récupérez la propriété rootUrl depuis le niveau supérieur du document de découverte.

Par exemple, la propriété rootUrl du document de découverte pour l' API Service Usage est la suivante:
```
https://serviceusage.s3nsapis.fr/
```
Récupérez la propriété servicePath depuis le niveau supérieur du document de découverte. Par exemple, la propriété servicePath du document de découverte de l'API Service Usage est vide.
Concaténez-les pour obtenir ce qui suit :
```
https://serviceusage.s3nsapis.fr/
```
Récupérez la propriété path, développez-la en tant que modèle d'URI et combinez les résultats de cette expansion avec l'URI de l'étape précédente. Par exemple, dans la méthode serviceusage.services.enable de l'API Service Usage v1, la valeur de la propriété path est v1/{+name}:enable. Ainsi, l'URI complet de la méthode est le suivant :
```
https://serviceusage.s3nsapis.fr/v1/{+name}:enable
```

Vous n'avez pas besoin d'une clé API pour appeler l'API Service Usage. Toutefois, si l'API que vous appelez nécessite une clé API, vous pouvez l'ajouter à la chaîne de requête de l'URI:

REQUEST_URI?key=API_KEY

Passer un appel et traiter la réponse

Après avoir envoyé la requête, vous devez désérialiser la réponse dans la représentation linguistique appropriée, en prenant soin de gérer les conditions d'erreur susceptibles de survenir, à la fois dans le transport HTTP sous-jacent et dans les messages d'erreur générés par le service d'API. Le format des erreurs est documenté dans le guide de style JSON de Google.

Exemples

La section suivante présente un exemple simple de bibliothèque cliente pour les API.

Client d'API simple

Vous trouverez ci-dessous un exemple de bibliothèque cliente très simple écrite en Python3. Le client crée une interface pour interagir avec l'API Service Usage, puis utilise cette interface pour activer l'API Compute Engine (compute.googleapis.com) dans le projet 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'))

Les principaux composants du client sont les suivants :

Étape 1 : Récupérer le document de découverte. Le document de découverte pour l'API Service Usage est récupéré et analysé dans une structure de données. Python étant un langage saisi de manière dynamique, le document de découverte peut être récupéré au moment de l'exécution.
Étape 2.a : Créer l'URI de base. L'URI de base est calculé.
Étape 2.b : Rédiger la requête. Lorsqu'une méthode est appelée sur une collection, le modèle d'URI est développé avec les paramètres transmis à la méthode, et les paramètres dont l'emplacement est query sont placés dans les paramètres de requête de l'URL. Enfin, une requête est envoyée à l'URL composée à l'aide de la méthode HTTP spécifiée dans le document de découverte.
Étape 3.a : Créer la surface du client. La surface du client est créée en descendant de manière récursive sur le document de découverte analysé. Pour chaque méthode de la section methods, une nouvelle méthode est associée à l'objet Collection. Comme les collections peuvent être imbriquées, nous recherchons resources et créons un objet Collection de manière récursive pour tous ses membres, le cas échéant. Chaque collection imbriquée est également associée en tant qu'attribut à l'objet Collection.
Étape 3.b : Utiliser le client. Cela montre comment la surface d'API compilée est utilisée. Un objet de service est d'abord créé à partir du document de découverte, puis l'API Service Usage permet d'activer l'API Compute Engine dans le projet my-project.