Présentation
Ce document est destiné aux développeurs qui souhaitent écrire des bibliothèques clientes, des plug-ins IDE et d'autres outils pour interagir avec les API Google. Le service de découverte des API Google vous permet d'effectuer toutes les actions ci-dessus en exposant des métadonnées lisibles par l'ordinateur concernant d'autres API Google via une API simple. Ce guide présente chaque section du document de découverte, ainsi que des conseils utiles sur l'utilisation de ce document.
Tous les appels d'API sont des requêtes REST non authentifiées basées sur JSON et utilisant le protocole SSL (autrement dit, les URL commencent par https).
Si vous ne connaissez pas les concepts du service de découverte des API Google, consultez la page Premiers pas avant de commencer à coder.
Format du document de découverte
Cette section présente le document de découverte.
Tous les exemples ci-dessous utilisent le document de découverte de l'API Google Cloud Service Management. Vous pouvez charger le document de découverte de l'API Google Cloud Service Management en exécutant la requête GET suivante:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1Le format d'un document de découverte inclut les informations suivantes:
- Description de base de l'API.
- Informations d'authentification pour l'API.
- Détails des ressources et du schéma décrivant les données de l'API.
- Détails sur les méthodes d'API.
- Informations sur les fonctionnalités personnalisées compatibles avec l'API.
- Documentation intégrée décrivant les principaux éléments de l'API
Chacune de ces sections est décrite ci-dessous. Pour en savoir plus sur chaque propriété, consultez la documentation de référence.
Description de base de l'API
Le document de découverte contient un ensemble de propriétés spécifiques à l'API:
"kind": "discovery#restDescription", "name": "servicemanagement", "version": "v1", "title": "Service Management API", "description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.", "protocol": "rest", "rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live", "servicePath": "",
Ces propriétés au niveau de l'API incluent des détails sur une version particulière d'une API, y compris name, version, title et description. protocol a toujours une valeur fixe de rest, car le service de découverte d'API n'accepte que les méthodes RESTful pour accéder aux API.
Le champ servicePath indique le préfixe de chemin pour cette version d'API particulière.
Authentification
La section auth contient des détails sur les champs d'application d'authentification OAuth 2.0 pour l'API. Pour en savoir plus sur l'utilisation des habilitations avec OAuth 2.0, consultez Utiliser OAuth 2.0 pour accéder aux API Google.
La section auth contient des sections imbriquées oauth2 et scopes. La section scopes est une correspondance clé/valeur de la valeur du champ d'application avec plus de détails sur le champ d'application:
"auth": {
"oauth2": {
"scopes": {
"https://www.googleapis.com/auth/cloud-platform.read-only": {
"description": "View your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management.readonly": {
"description": "View your Google API service configuration"
},
"https://www.googleapis.com/auth/cloud-platform": {
"description": "View and manage your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management": {
"description": "Manage your Google API service configuration"
}
}
}
}
La section auth ne définit que les champs d'application d'une API particulière. Pour découvrir comment ces habilitations sont associées à une méthode API, consultez la section Méthodes ci-dessous.
Ressources et schémas
Les opérations d'une API agissent sur les objets de données appelés resources. Le document de découverte repose sur le concept de ressources. Chaque document Discovery comporte une section resources de premier niveau qui regroupe toutes les ressources associées à l'API. Par exemple, l'API Google Cloud Service Management dispose d'une ressource services et d'une ressource operations dans l'organisation racine resources, la ressource services comprend trois sous-ressources, configs, rollouts et consumers:
"resources": {
"services": {
// Methods and sub-resources associated with the services resource
"configs": {
// Methods and sub-resources associated with the services.configs resource
},
"rollouts": {
// Methods and sub-resources associated with the services.rollouts resource
},
"consumers": {
// Methods and sub-resources associated with the services.consumers resource
}
},
"operations": {
// Methods and sub-resources associated with the operations resource
}
}
Dans chaque section de ressource se trouvent les méthodes associées à cette ressource. Par exemple, l'API Google Cloud Service Management dispose de trois méthodes associées à la ressource services.rollouts: get, list et create.
Les schémas vous permettent de voir à quoi ressemblent les ressources d'une API. Chaque document Discovery comporte une section schemas de premier niveau, qui contient une paire nom/valeur de l'ID de schéma à laquelle renvoyer l'objet. Les ID de schéma sont uniques pour chaque API et permettent d'identifier le schéma de manière unique dans la section methods du document de découverte:
"schemas": {
"Rollout": {
// JSON Schema of the Rollout resource.
}
}
Le service de découverte d'API utilise le schéma JSON-03 pour ses représentations de schéma. Voici un extrait de schéma JSON pour la ressource URL, ainsi qu'une ressource de réponse réelle:
| Déployer le schéma JSON de la ressource : | Réponse réelle concernant la ressource de déploiement: |
{
"Rollout": {
"id": "Rollout",
"type": "object",
"description": "...",
"properties": {
"serviceName": {
"type": "string",
"description": "..."
},
"rolloutId": {
"type": "string",
"description": "..."
},
"status": {
"type": "string",
"enum": [
"ROLLOUT_STATUS_UNSPECIFIED",
"IN_PROGRESS",
"SUCCESS",
"CANCELLED",
"FAILED",
"PENDING",
"FAILED_ROLLED_BACK"
],
"enumDescriptions": [
...
],
"description": "..."
},
"trafficPercentStrategy": {
"$ref": "TrafficPercentStrategy",
"description": "..."
},
"deleteServiceStrategy": { ... },
"createTime": { ... },
"createdBy": { ... }
}
}
}
|
{
"serviceName": "discovery.googleapis.com",
"rolloutId": "2020-01-01R0",
"status": "SUCCESS",
"trafficPercentStrategy":{
"precentages":{
"2019-12-01R0": 70.00,
"2019-11-01R0": 30.00
}
}
}
|
Les champs en gras indiquent le mappage entre le schéma JSON et la réponse réelle.
Les schémas peuvent également contenir des références à d'autres schémas. Si vous créez une bibliothèque cliente, cela peut vous aider à modéliser efficacement les objets d'une API dans vos classes de modèle de données. Dans l'exemple Rollout ci-dessus, la propriété trafficPercentStrategy est en réalité une référence à un schéma avec l'ID TrafficPercentStrategy. Dans la section schemas, vous trouverez le schéma TrafficPercentStrategy. La valeur de ce schéma peut être remplacée par la propriété trafficPercentStrategy dans la ressource Rollout (la syntaxe $ref provient de la spécification de schéma JSON).
Les méthodes peuvent également référencer des schémas lorsqu'elles indiquent leurs corps de requête et de réponse. Pour en savoir plus, consultez la section Méthodes.
Méthodes
Le cœur du document de découverte repose sur des méthodes. Les méthodes sont les opérations pouvant être effectuées sur une API. Vous trouverez la section methods dans différentes sections du document de découverte, y compris au niveau supérieur (méthodes au niveau de l'API) ou au niveau resources.
"methods": {
// API-level methods
}
"resources": {
"resource1": {
"methods": {
// resource-level methods
}
"resources": {
"nestedResource": {
"methods": {
// methods can even be found in nested-resources
}
}
}
}
}
Bien qu'une API peut avoir des méthodes au niveau de l'API, une ressource doit avoir une section methods.
Chaque section methods est un mappage clé/valeur du nom de la méthode à d'autres détails sur cette méthode. L'exemple ci-dessous documente trois méthodes, get, list et create :
"methods": {
"get": { //details about the "get" method },
"list": { //details about the "list" method },
"create": { //details about the "create" method }
}
Enfin, chaque section de la méthode détaille plusieurs propriétés la concernant. Voici un exemple de la méthode get:
"get": {
"id": "servicemanagement.services.rollouts.get",
"path": "v1/services/{serviceName}/rollouts/{rolloutId}",
"flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
"httpMethod": "GET",
"description": "Gets a service configuration rollout.",
"response": { "$ref": "Rollout" },
"parameters": { // parameters related to the method },
"parameterOrder": [ // parameter order related to the method ],
"scopes": [ // OAuth 2.0 scopes applicable to this method ],
"mediaUpload": { // optional media upload information },
},
Cette section contient des détails généraux sur la méthode, tels qu'un ID unique permettant d'identifier la méthode, le httpMethod à utiliser et le path de la méthode (pour en savoir plus sur l'utilisation de la propriété path pour calculer l'URL complète de la méthode, consultez la section Saisir une requête). En plus de ces propriétés de méthode générale, d'autres propriétés permettent d'associer la méthode à d'autres sections du document de découverte:
Niveaux d'accès
La section auth définie précédemment dans cette documentation contient des informations sur tous les champs d'application compatibles avec une API spécifique. Si une méthode accepte l'un de ces champs d'application, elle est associée à un tableau de champs d'application. Il existe une entrée dans ce tableau pour chaque champ d'application compatible avec la méthode. Par exemple, la section scopes de la méthode get de l'API Google Cloud Service Management se présente comme suit:
"scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/cloud-platform.read-only", "https://www.googleapis.com/auth/service.management", "https://www.googleapis.com/auth/service.management.readonly" ]
Notez que le choix du champ d'application d'authentification à utiliser dans votre application dépend de plusieurs facteurs, tels que les méthodes appelées et les paramètres envoyés avec la méthode. Par conséquent, il appartient au développeur de décider du champ d'application à utiliser. Discovery ne consigne que les champs d'application valides pour une méthode.
Demande et réponse
Si la méthode comporte un corps de requête ou de réponse, ils sont décrits dans les sections request ou response, respectivement. Dans l'exemple get ci-dessus, la méthode a un corps response:
"response": {
"$ref": "Rollout"
}
La syntaxe ci-dessus indique que le corps de la réponse est défini par un schéma JSON dont l'ID est Rollout. Ce schéma se trouve dans la section "Schémas de premier niveau". Les corps de requête et de réponse utilisent la syntaxe $ref pour faire référence à des schémas.
Paramètres
Si une méthode comporte des paramètres devant être spécifiés par l'utilisateur, ceux-ci sont indiqués dans la section parameters au niveau de la méthode. Cette section contient un mappage clé/valeur du nom du paramètre avec des informations plus détaillées sur ce paramètre:
"parameters": {
"serviceName": {
"type": "string",
"description": "Required. The name of the service.",
"required": true,
"location": "path"
},
"rolloutId": { ... }
},
"parameterOrder": [
"serviceName",
"rolloutId"
]
Dans l'exemple ci-dessus, il y a deux paramètres pour la méthode get : serviceName et rolloutId. Les paramètres peuvent être placés dans path ou dans l'URL query. La propriété location indique où la bibliothèque cliente doit placer le paramètre.
De nombreuses autres propriétés décrivent le paramètre, y compris les données de paramètre type (utiles pour les langues fortement saisies), si le paramètre est required et s'il s'agit d'une énumération. Pour en savoir plus sur les propriétés, consultez le Guide de référence.
Ordre des paramètres
Il existe de nombreuses façons pour les bibliothèques clientes de structurer leurs interfaces. Une méthode consiste à avoir une méthode avec chaque paramètre d'API dans la signature de la méthode. Toutefois, le format JSON étant non ordonné, il est difficile de savoir programmer les paramètres de la signature de méthode par programmation. Le tableau parameterOrder permet de trier les paramètres de manière fixe pour les requêtes. Le tableau liste le nom de chaque paramètre par ordre de priorité. Il peut contenir des paramètres de chemin ou de requête, mais chaque paramètre du tableau est obligatoire. Dans l'exemple ci-dessus, une signature de méthode Java peut se présenter comme suit:
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);La première valeur du tableau parameterOrder, serviceName, est également le premier élément de la signature de la méthode. S'il y avait d'autres paramètres dans le tableau parameterOrder, ils se trouveraient après le paramètre serviceName. Étant donné que le tableau parameterOrder ne contient que les paramètres requis, il est recommandé d'inclure également un moyen pour les utilisateurs de spécifier également des paramètres facultatifs. L'exemple ci-dessus effectue cette opération avec la carte optionalParameters.
Importation de contenus multimédias
Si une méthode permet d'importer des médias, tels que des images, de l'audio ou de la vidéo, l'emplacement et les protocoles compatibles avec l'importation de ces éléments sont indiqués dans la section mediaUpload. Cette section détaille les protocoles d'importation compatibles et présente les types de contenus pouvant être importés:
"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"
}
}
}
Dans l'exemple ci-dessus, la propriété supportsMediaUpload est une valeur booléenne qui détermine si la méthode accepte l'importation de contenus multimédias. Si la valeur est "true", la section mediaUpload indique les types de médias pouvant être importés.
La propriété accept est une liste de plages multimédias qui déterminent les types MIME pouvant être importés. Le point de terminaison de l'exemple ci-dessus accepte n'importe quel format d'image.
La propriété maxSize a la taille maximale d'une importation. La valeur correspond à une chaîne en Mo, Go ou To. Dans l'exemple ci-dessus, les importations sont limitées à 10 Mo. Notez que cette valeur ne reflète pas le quota de stockage restant d'un utilisateur pour cette API. Par conséquent, même si l'importation est inférieure à maxSize, la bibliothèque cliente doit toujours être prête à gérer une importation qui a échoué en raison d'un espace insuffisant.
La section protocols liste les protocoles d'importation compatibles avec une méthode. Le protocole simple consiste simplement à POST du contenu multimédia sur le point de terminaison donné dans une seule requête HTTP. Le protocole resumable implique que le point de terminaison indiqué dans l'URI path est compatible avec le protocole d'importation avec reprise. Si la propriété multipart est true, le point de terminaison accepte les importations en plusieurs parties, ce qui signifie que la requête JSON et le contenu multimédia peuvent être encapsulés dans un corps mutlipart/related et envoyés ensemble. Notez que les protocoles simple et resumable peuvent tous deux accepter les importations en plusieurs parties.
La propriété path est un modèle d'URI et doit être remplacée par la propriété path pour la méthode, comme indiqué dans la section Saisir une requête.
Téléchargement de contenus multimédias
Si une méthode accepte le téléchargement de contenus multimédias, tels que des images, de l'audio ou des vidéos, cela est indiqué par le paramètre supportsMediaDownload:
"supportsMediaDownload": true,
Lorsque vous téléchargez du contenu multimédia, vous devez définir le paramètre de requête alt sur media dans l'URL de la requête.
Si la propriété useMediaDownloadService de la méthode API est true, insérez /download avant servicePath pour éviter une redirection. Par exemple, le chemin de téléchargement est /download/youtube/v3/captions/{id} si la concaténation de servicePath et path est /youtube/v3/captions/{id}. Il est recommandé de créer l'URL de téléchargement multimédia avec /download, même si useMediaDownloadService est défini sur "false".
Paramètres courants
Le document de niveau supérieur contient une propriété parameters. Cette section est semblable à la section "Paramètres" de chaque méthode, mais ces paramètres peuvent être appliqués à n'importe quelle méthode de l'API.
Par exemple, les méthodes "get", "insert" ou "list" de l'API Google Cloud Service Management peuvent inclure un paramètre prettyPrint dans les paramètres de requête, ce qui permet de formater la réponse pour toutes ces méthodes dans un format lisible. Voici une liste de paramètres courants:
| Parameter | Signification | Remarques | Applicabilité |
|---|---|---|---|
access_token |
Jeton OAuth 2.0 pour l'utilisateur actuel. |
|
|
alt |
Format des données pour la réponse. |
|
|
callback |
Fonction de rappel. |
| |
fields |
Sélecteur permettant de spécifier un sous-ensemble de champs à inclure dans la réponse. |
|
|
key |
Clé API (OBLIGATOIRE*) |
|
|
prettyPrint |
Renvoie une réponse avec des identifiants et des sauts de ligne. |
|
|
quotaUser |
Alternative à userIp |
|
|
userIp |
Adresse IP de l'utilisateur final pour le compte duquel l'appel d'API est effectué. |
|
Fonctionnalités
Dans certains cas, les API proposent des fonctionnalités personnalisées qui sortent du cadre du reste du document de découverte. Ils sont collectés dans le tableau features. Le tableau de caractéristiques contient une étiquette de chaîne pour chaque caractéristique spéciale compatible avec l'API. Actuellement, dataWrapper est la seule fonctionnalité compatible, mais d'autres pourront l'être à l'avenir.
"features": dataWrapper
La fonctionnalité dataWrapper indique que toutes les requêtes et les réponses de l'API sont encapsulées dans un objet JSON data. Cette fonctionnalité est disponible dans les anciennes API Google, mais elle sera bientôt abandonnée. Les API suivantes sont compatibles avec la fonctionnalité dataWrapper: Moderator v1 et Translate v2.
En tant que développeur de bibliothèques clientes, si une API est compatible avec la fonctionnalité "&Wrapper" :
- Pour les requêtes: encapsulez la ressource de requête dans un objet JSON
data. - En réponse: trouvez la ressource dans un objet JSON
data.
Les schémas du document de découverte ne contiennent pas le wrapper de données. Vous devez donc les ajouter et les supprimer explicitement. Par exemple, supposons qu'il existe une API avec une ressource nommée "Foo" qui ressemble à ceci:
{
"id": 1,
"foo": "bar"
}
Avant d'insérer cette ressource à l'aide de l'API, vous devez l'encapsuler dans un élément de données:
{
"data": {
"id": 1,
"foo": "bar"
}
}
En revanche, lorsque vous recevez une réponse de l'API, elle contient également le wrapper de données:
{
"data": {
"id": 1,
"foo": "bar"
}
}
Pour obtenir la ressource définie par le schéma, vous devez supprimer le wrapper de données:
{
"id": 1,
"foo": "bar"
}
Documentation intégrée
Chaque document Discovery est annoté avec un certain nombre de champs description qui fournissent une documentation intégrée pour l'API. Les champs description sont disponibles pour les éléments d'API suivants:
- API elle-même
- Champs d'application OAuth
- Schémas de ressources
- Méthodes d'API
- Paramètres de méthode
- Valeurs acceptables pour certains paramètres
Ces champs sont particulièrement utiles si vous souhaitez utiliser le service de découverte des API Google pour générer une documentation lisible pour une bibliothèque cliente, par exemple JavaDoc.