L'API Discovery fournit la liste des API Google permettant de récupérer pour chaque API un document de découverte et de métadonnées lisible par un ordinateur.
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.
Contexte du service de découverte
concepts
Le service de découverte des API Google repose sur deux concepts de base:
- Répertoire des API: liste de toutes les API compatibles avec le service de découverte d'API Chaque entrée d'annuaire contient des informations sur une API compatible, y compris son nom, une brève description de son fonctionnement et un lien de documentation. Une API peut comporter plusieurs entrées d'annuaire, une pour chacune des versions compatibles.
- Document de découverte: description d'une API lisible par l'ordinateur. Le document de découverte décrit la surface associée à une version particulière d'une API. Ce document explique comment accéder aux différentes méthodes de chaque API via des appels HTTP RESTful. Un document de découverte inclut des descriptions des données et des méthodes associées à l'API, ainsi que des informations sur les champs d'application OAuth disponibles, ainsi que des descriptions des schémas, des méthodes, des paramètres et des valeurs de paramètres disponibles.
Modèle de données
Une ressource est une entité de données individuelle dotée d'un identifiant unique. Le service de découverte des API Google fonctionne sur deux types de ressources basées sur les concepts ci-dessus.
Liste des API : liste des API
Chaque entrée d'annuaire contient une paire name/version d'API contenant les informations suivantes:
- Informations d'identification et de description: nom, version, titre et description.
- Informations sur la documentation : icônes et lien vers la documentation.
- Informations d'état, y compris les libellés d'état, et indication indiquant s'il s'agit ou non de la version préférée de l'API.
- Lien du document de découverte : URI du document de découverte pour cette API (indiqué sous la forme d'une URL complète, par exemple https://servicemanagement.googleapis.com/$discovery/rest?version=v1).
Ressource de document de découverte : description d'une API lisible par l'ordinateur
En plus des informations fournies dans l'annuaire des API, le document Discovery inclut les éléments suivants:
- Schémas : liste de schémas de ressources d'API qui décrivent les données auxquelles vous avez accès dans chaque API. Les schémas du service de découverte des API Google sont basés sur le schéma JSON.
- Méthodes, y compris la liste des méthodes d'API et les paramètres disponibles pour chaque méthode
- Champs d'application OAuth : identifie la liste des champs d'application OAuth disponibles pour cette API.
- La documentation intégrée fournit de brèves descriptions des schémas, méthodes, paramètres et valeurs des paramètres disponibles.
La collection unique d'annuaire est le conteneur conceptuel de la ressource unique Annuaire des API et des ressources du document de découverte pour chaque API compatible.
Pour en savoir plus sur la ressource Annuaire des API et le document de découverte, consultez les pages Utiliser l'API et Documentation de référence.
Opérations
Vous pouvez appeler deux méthodes différentes pour les collections et les ressources dans le service de découverte des API Google, comme décrit dans le tableau suivant.
| Operations | Description | Mappages HTTP REST |
|---|---|---|
| list | Répertorie toutes les API compatibles. | GET sur l'URI de la ressource d'annuaire. |
Style d'appel
REST
Les opérations compatibles du service de découverte des API Google sont directement mappées au verbe HTTP GET REST, comme décrit dans la section Opérations.
Le format spécifique des URI du service de découverte des API Google est le suivant:
https://discovery.googleapis.com/discovery/v1/apis?parameters
où api est l'identifiant d'une ressource de document de découverte, version est l'identifiant de la version particulière de l'API, et _parameters_ est un paramètre à appliquer à la requête. Pour en savoir plus, consultez Récapitulatif des paramètres de requête dans la documentation de référence.
Vous trouverez plus d'informations sur l'ensemble complet des URI utilisés pour chaque opération compatible avec l'API dans la documentation de référence du service de découverte des API Google.
Voici quelques exemples illustrant le fonctionnement du service de découverte des API Google.
Répertoriez toutes les API compatibles avec le service de découverte des API Google:
GET https://discovery.googleapis.com/discovery/v1/apis
Essayer maintenant dans APIs Explorer
Obtenez le document de découverte pour l'API Google Cloud Service Management version 1:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1