Présentation
Vous pouvez utiliser le service de découverte des API Google pour créer divers 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. Cette section explique comment créer une bibliothèque cliente personnalisée pour les API Google.
Une bibliothèque cliente stable et complète 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ération du document de découverte et création de la surface de l'API...
- Composer 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 examiner l'exemple de client API simple dans la section "Exemples" pour voir comment ces instructions correspondent au code.
Étape 1: Récupérez le document de découverte
Avant de commencer à implémenter une bibliothèque cliente, vous devez respecter certaines exigences de base qui vous aideront à poursuivre votre développement. Par exemple, le langage de programmation de votre choix peut être typé ou non typé. S'il est saisi, il peut l'être de manière statique ou dynamique. Elle peut être compilée ou interprétée. Ces exigences vous guideront dans votre utilisation du 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 déterminer exactement à quel moment récupérer le document est déterminée par les exigences que vous avez définies. Par exemple, dans un langage 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 le document de découverte. Pour un langage très typé, vous pouvez générer du code et créer une bibliothèque compilée. Pour un langage de type dynamique, vous pouvez construire de manière différée les structures de programmation pour une interface à la volée avec l'API lorsque la surface de programmation est utilisée.
Étape 2: Rédigez une requête
La composition d'une requête comporte deux étapes distinctes:
- Composition du corps de la requête
- Construire l'URL de la requête.
Vous devez convertir le corps de la requête, le cas échéant, d'une représentation adaptée au langage au bon format de fil. Par exemple, dans une bibliothèque cliente Java, il existe 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 en JSON.
La construction de l'URL de requête est un processus un peu plus complexe.
La propriété path de chaque méthode dans l'API utilise la syntaxe URI Template v04. Cette propriété peut contenir des variables, qui sont entourées d'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. L'exemple ci-dessus contient 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 effectuez une requête, vous devez remplacer la valeur de var dans l'URL. Par exemple, si l'utilisateur de la bibliothèque fait un choix qui 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:
Récupérez la propriété
rootUrlà partir du premier niveau du document de découverte.
Par exemple, la propriétérootUrldu document de découverte pour l'API Google Cloud Service Management est:https://servicemanagement.googleapis.com/Récupérez le
servicePathà partir du premier niveau du document de découverte.
Par exemple, la propriétéservicePathdu document de découverte pour l'API Google Cloud Service Management est vide.Concaténez-les ensemble pour obtenir:
https://servicemanagement.googleapis.com/Récupérez la propriété
path, développez-la en tant que modèle d'URI, puis associez les résultats de cette expansion à l'URI de l'étape précédente.
Par exemple, dans la méthode de servicegetde l'API Google Cloud Service Management, la valeur de la propriétépathestv1/services/{serviceName}. Ainsi, l'URI complet de la méthode est le suivant:https://servicemanagement.googleapis.com/v1/services/{serviceName}
Une clé API est requise pour appeler l'API Google Cloud Service Management. Ainsi, après avoir appliqué une clé API, l'URI complet permettant d'obtenir la définition du service de détection d'API est le suivant:
https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY
Étape 3: Passez un appel et gérez la réponse
Une fois la requête envoyée, vous devez désérialiser la réponse dans la langue appropriée, en veillant à gérer les conditions d'erreur qui peuvent se produire (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 indiqué dans le guide de style Google JSON.
Examples
Pour obtenir des exemples concrets de bibliothèques et d'outils clients mis en œuvre à l'aide du service de découverte des API Google, consultez le document Bibliothèques et exemples. De plus, la section suivante donne un exemple simple de bibliothèque cliente d'API.
Client 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 Google Cloud Service Management, puis obtient la définition de service du service API Discovery à l'aide de cette interface.
Avertissement: Le code ci-dessous est une version beaucoup plus simple d'une bibliothèque cliente standard. Il s'agit d'une implémentation incomplète fournie pour illustrer certains aspects de la création d'une bibliothèque cliente. Ce code n'est pas prêt pour la production.
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'))
Les principaux composants du client sont les suivants:
- Étape 1 : Récupérez le document de découverte.
Le document de découverte de l'API Google Cloud Service Management est récupéré et analysé dans une structure de données. Python étant un langage de type dynamique, le document de découverte peut être récupéré au moment de l'exécution. - Étape 2.a : Créez l'URI de base.
L'URI de base est calculé. - Étape 2.b : Rédigez 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 ceux dont l'emplacement estquerysont placés dans les paramètres de requête de l'URL. Enfin, une requête est envoyée à l'URL composée via la méthode HTTP spécifiée dans le document de découverte. - Étape 3.a : Créez la surface client.
La surface du client est construite en descendant de manière récursive sur le document Discovery analysé. Pour chaque méthode de la sectionmethods, une nouvelle méthode est associée à l'objetCollection. Comme les collections peuvent être imbriquées, nous recherchonsresourceset créons de manière récursive un objetCollectionpour tous ses membres s'il en trouve. Chaque collection imbriquée est également associée en tant qu'attribut à l'objetCollection. - Étape 3.b: Utilisez le client.
Cela montre comment la surface d'API créée est utilisée. Pour commencer, un objet de service est créé à partir du document de découverte, puis la définition du service du service API Discovery est récupérée via l'API Google Cloud Service Management.