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 opérations ci-dessus en exposant des métadonnées exploitables par ordinateur concernant d'autres API Google via une API simple. Ce guide présente les différentes sections du document de découverte, ainsi que des conseils utiles sur l'utilisation du document.
Tous les appels passés à l'API sont des requêtes REST non authentifiées basées sur JSON qui utilisent SSL. En d'autres termes, les URL commencent par https.
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 Service Usage.
Vous pouvez charger le document de découverte pour l'API Service Usage en exécutant la requête GET suivante:
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1
Le format d'un document de découverte comprend des informations qui entrent dans six catégories principales :
- Description de base de l'API
- Informations d'authentification de l'API
- Informations sur les ressources et les schémas décrivant les données de l'API
- Informations sur les méthodes de l'API
- Informations sur toutes les fonctionnalités personnalisées compatibles avec l'API
- Documentation intégrée décrivant les éléments clés de l'API
Ces sections du document de découverte sont décrites ci-dessous.
Description de base de l'API
Le document de découverte contient un ensemble de propriétés spécifiques à l'API : Ces propriétés n'apparaissent pas nécessairement dans cet ordre ni dans la même section du document de découverte:
"id": "serviceusage:v1", "canonicalName": "Service Usage", "revision": "20240331", "servicePath": "", "baseUrl": "https://serviceusage.googleapis.com/", "kind": "discovery#restDescription", "description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.", "ownerDomain": "google.com", "version_module": true, "version": "v1", "fullyEncodeReservedExpansion": true, "name": "serviceusage", "title": "Service Usage API", "discoveryVersion": "v1", "rootUrl": "https://serviceusage.googleapis.com/", "protocol": "rest"
Ces propriétés au niveau de l'API incluent des informations sur une version particulière d'une API, y compris name, version, title et description. La propriété protocol a toujours une valeur fixe de rest, car le service de découverte des API n'accepte que les méthodes RESTful pour accéder aux API.
Le champ servicePath indique le préfixe de chemin d'accès pour cette version d'API particulière.
Authentification
La section auth contient des informations sur les champs d'application d'authentification OAuth 2.0 pour l'API. Pour en savoir plus sur l'utilisation des champs d'application avec OAuth 2.0, consultez la page Utiliser OAuth 2.0 pour accéder aux API Google.
La section auth contient une section oauth2 et scopes imbriquée. La section scopes est un mappage clé/valeur entre la valeur du champ d'application et les informations plus détaillées concernant le champ d'application :
"auth": { "oauth2": { "scopes": { "https://www.googleapis.com/auth/cloud-platform": { "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account." }, "https://www.googleapis.com/auth/cloud-platform.read-only": { "description": "View your data across Google Cloud services and see the email address of your Google Account" }, "https://www.googleapis.com/auth/service.management": { "description": "Manage your Google API service configuration" } } } }
La section auth définit uniquement les champs d'application d'une API particulière. Pour savoir comment ces champs d'application sont associés à une méthode API, consultez la section Méthodes ci-dessous.
Ressources et schémas
Les opérations d'une API agissent sur des objets de données appelés resources. Le document de découverte repose sur le concept de ressources. Chaque document de découverte comporte une section resources de premier niveau qui regroupe toutes les ressources associées à l'API. Par exemple, l'API Service Usage dispose d'une ressource services et d'une ressource operations sous le niveau resources de premier niveau:
"resources": { "services": { // Methods associated with the services resource } "operations": { // Methods associated with the operations resource } }
Dans chaque section de ressource, vous trouverez les méthodes associées à cette ressource. Par exemple, l'API Service Usage est associée à six méthodes associées à la ressource services: get, enable, disable, batchGet, batchEnable et list.
Les schémas vous indiquent à quoi ressemblent les ressources d'une API. Chaque document de découverte possède une section schemas de premier niveau, qui contient une paire nom/valeur d'ID de schéma pour un 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 : Par exemple, voici quelques schémas du document de découverte de l'API Service Usage:
"schemas": { "Method": { // JSON schema of the Method resource }, "Authentication": { // JSON schema of the Authentication resource }, "RubySettings": { // JSON schema of the RubySettings resource }, "EnableServiceResponse": { // JSON schema of the EnableServiceResponse resource } }
Le service de découverte des API utilise le schéma JSON draft-03 pour ses représentations de schémas. Voici un extrait du schéma JSON pour la ressource EnableServiceResponse, ainsi que le GoogleApiServiceusagev1Service auquel il fait référence. À côté de ces schémas se trouve une partie d'une réponse réelle pour une requête visant à activer l'API Pub/Sub (pubsub.googleapis.com).
Schéma JSON de la ressource EnableServiceResponse : |
Réponse réelle pour l'activation d'un service: |
"EnableServiceResponse": { "id": "EnableServiceResponse", "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.", "properties": { "service": { "description": "The new state of the service after enabling.", "$ref": "GoogleApiServiceusageV1Service" } }, "type": "object" }, "GoogleApiServiceusageV1Service": { "description": "A service that is available for use by the consumer.", "properties": { "config": { "$ref": "GoogleApiServiceusageV1ServiceConfig", "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method." }, "name": { "type": "string", "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com" }, " |
"response": { "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse", "service": { "name": "projects/232342569935/services/pubsub.googleapis.com", "config": { "name": "pubsub.googleapis.com", "title": "Cloud Pub/Sub API", "documentation": { "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n" }, "quota": {}, "authentication": {}, "usage": { "requirements": [ "serviceusage.googleapis.com/tos/cloud" ] }, "monitoring": {} }, " |
Les champs en gras montrent le mappage entre le schéma JSON et la réponse réelle.
Comme illustré dans cet exemple, les schémas peuvent 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 EnableServiceResponse ci-dessus, la propriété service est une référence à un schéma ayant l'ID GoogleApiServiceusageV1Service, un autre schéma du document de découverte de l'API Service Usage. Vous pouvez remplacer la propriété GoogleApiServiceusageV1Service de la ressource EnableServiceResponse par la valeur du schéma GoogleApiServiceusageV1Service (notez que la syntaxe $ref provient de la spécification du schéma JSON).
Les méthodes peuvent également faire référence à des schémas lorsqu'elles indiquent les corps de requête et de réponse associés. Pour en savoir plus, consultez la section Méthodes.
Méthodes
Les méthodes constituent le cœur du document de découverte. Elles correspondent aux opérations pouvant être effectuées sur une API. Vous trouverez la section methods dans différentes parties du document de découverte, y compris au niveau supérieur (aussi appelées 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 } } } } }
Alors qu'une API peut avoir des méthodes au niveau de l'API, une ressource doit comporter une section methods.
Chaque section methods est un mappage clé-valeur entre le nom de la méthode et d'autres informations concernant cette méthode. L'exemple ci-dessous décrit trois méthodes (get, enable et disable) :
"methods": { "get": { //details about the "get" method }, "enable": { //details about the "enable" method }, "disable": { //details about the "disable" method } }
Enfin, la section dédiée à chaque méthode détaille ses différentes propriétés. Voici un exemple de méthode enable :
"enable": { "path": "v1/{+name}:enable", "request": { "$ref": "EnableServiceRequest" }, "parameterOrder": [ "name" ], "id": "serviceusage.services.enable", "response": { "$ref": "Operation" }, "description": "Enable a service so that it can be used with a project.", "httpMethod": "POST", "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable", "scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/service.management" ], "parameters": { "name": { "location": "path", "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.", "required": true, "type": "string", "pattern": "^[^/]+/[^/]+/services/[^/]+$" } } },
Cette section contient des informations générales sur la méthode, telles qu'un ID unique pour identifier la méthode, la méthode HTTP (httpMethod) à utiliser et le chemin d'accès (path) à 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 Rédiger une requête. Outre ces propriétés générales de méthode, plusieurs propriétés permettent d'associer la méthode à d'autres sections du document de découverte :
Champs d'application
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 est compatible avec l'un de ces champs d'application, elle contiendra un tableau de champs d'application. Ce tableau contient une entrée pour chaque champ d'application accepté par la méthode.
Notez que le choix d'un champ d'application d'authentification à utiliser dans votre application dépend de différents facteurs, tels que les méthodes appelées et les paramètres envoyés avec la méthode. Par conséquent, le choix du champ d'application à utiliser est du ressort du développeur. Le document de découverte n'indique que les champs d'application valides pour une méthode.
Requête et réponse
Si la méthode comporte un corps de requête ou de réponse, celui-ci est documenté respectivement dans la section request ou response. Par exemple, pour la méthode enable, le contenu de la section request indique que la requête de la méthode est définie par un schéma JSON avec l'ID EnableServiceRequest. Ce schéma est disponible dans la section des schémas de premier niveau.
Paramètres
Si une méthode comporte des paramètres devant être spécifiés par l'utilisateur, ceux-ci sont documentés dans la section parameters au niveau de la méthode. Cette section contient un mappage clé-valeur entre le nom du paramètre et des informations plus détaillées concernant ce paramètre.
Par exemple, la méthode enable comporte un paramètre : name.
Les paramètres peuvent être placés dans path ou dans la requête d'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 le type des données du paramètre (utile pour les langages fortement typés), si le paramètre est required et s'il s'agit d'une énumération. Pour en savoir plus sur ces propriétés, consultez la documentation de référence de cette API.
Ordre des paramètres
Les bibliothèques clientes peuvent structurer leurs interfaces de différentes façons. L'une d'elles consiste à disposer d'une méthode avec chaque paramètre d'API dans la signature de la méthode. Cependant, comme JSON est un format non ordonné, il est difficile de savoir comment classer les paramètres dans la signature de la méthode de manière programmatique. Le tableau parameterOrder fournit un ordre fixe des paramètres pour l'exécution de requêtes. Le tableau répertorie le nom de chaque paramètre par ordre d'importance. Il peut contenir des paramètres de chemin d'accès ou de requête, mais chaque paramètre du tableau est obligatoire.
Importation de contenu multimédia
Si une méthode permet d'importer des contenus multimédias, tels que des images, des enregistrements audio ou des vidéos, l'emplacement et les protocoles acceptés pour l'importation de ces contenus sont documentés dans la section mediaUpload. Cette section contient des informations sur les protocoles d'importation compatibles et sur les types de contenus multimédias pouvant être importés.
La méthode enable ne contient pas de section mediaUpload. Toutefois, une section mediaUpload type peut se présenter comme suit:
"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 est compatible avec l'importation de contenus multimédias. Si la valeur est "true", la section mediaUpload documente les types de contenus multimédias pouvant être importés.
La propriété accept est une liste de plages de médias qui déterminent les types MIME acceptables pour l'importation. Le point de terminaison affiché dans l'exemple ci-dessus accepte n'importe quel format d'image.
La propriété maxSize indique la taille maximale d'une importation. La valeur est une chaîne exprimée en Mo, Go ou To. Dans l'exemple ci-dessus, la taille maximale des importations est de 10 Mo.
Notez que cette valeur ne reflète pas le quota de stockage restant d'un utilisateur individuel 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 échoue en raison d'un espace insuffisant.
La section protocols répertorie les protocoles d'importation compatibles avec une méthode. Le protocole simple envoie simplement la publication POST du média au point de terminaison donné dans une seule requête HTTP. Le protocole resumable implique que le point de terminaison indiqué dans l'URI path soit compatible avec le protocole d'importation avec reprise. Si la propriété multipart est définie sur 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 en plusieurs parties/associé et envoyés ensemble. Notez que les protocoles simple et resumable peuvent accepter les importations en plusieurs parties.
La propriété path est un modèle d'URI et doit être développée de la même façon que la propriété path de la méthode, comme indiqué dans la section Rédiger une requête.
Téléchargement de contenu multimédia
Si une méthode permet de télécharger des contenus multimédias, tels que des images, des enregistrements audio ou des vidéos, le paramètre supportsMediaDownload l'indique :
"supportsMediaDownload": true,
Lors du téléchargement de contenus multimédias, 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 de path est /youtube/v3/captions/{id}. Il est recommandé de créer l'URL de téléchargement de contenu multimédia avec /download, même si useMediaDownloadService est défini sur "false".
Paramètres courants
Le document de découverte de premier niveau contient une propriété parameters. Cette section est semblable à la section des paramètres pour 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 et list de l'API Service Usage peuvent inclure un paramètre prettyPrint dans les paramètres de requête, ce qui entraînera la mise en forme de la réponse pour toutes ces méthodes dans un format lisible par l'humain. Voici une liste des paramètres courants :
| Paramètre | Signification | Remarques | Applicabilité |
|---|---|---|---|
access_token |
Jeton OAuth 2.0 pour l'utilisateur actuel. |
|
|
alt |
Format des données de 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 (REQUISE) |
|
|
prettyPrint |
Renvoie une réponse avec des indentations 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é. |
|
Documentation intégrée
Chaque document de découverte 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 la méthode
- Valeurs acceptées 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 par l'humain pour une bibliothèque cliente (par exemple, JavaDoc).