Ce document décrit les exigences générales des API qui peuvent être intégrées en tant que fournisseur de types à Deployment Manager. Utilisez ces instructions pour comprendre les caractéristiques d'une API attendue par Deployment Manager. Si votre API ne correspond pas exactement aux spécifications décrites ici, vous pourrez peut-être résoudre ces incohérences à l'aide d'options d'API avancées.
L'API possède un document descripteur valide
Un document descripteur décrit une API et ses ressources. Seules les API reposant sur une spécification OpenAPI ou un Google Discovery document descripteur peut être intégré à Deployment Manager. Pour obtenir des informations complètes sur la création d'une spécification OpenAPI, accédez au dépôt OpenAPI GitHub.
Le point de terminaison du document descripteur de l'API est accessible
Deployment Manager envoie une requête HTTP pour obtenir le document descripteur de l'API. Veillez donc à héberger votre document descripteur dans un emplacement accessible par Deployment Manager. Il peut s'agir d'une URL disponible publiquement ou d'un point de terminaison protégé par des paramètres d'authentification de base.
L'API accepte l'authentification de base ou OAuth2 si elle est hébergée sur certains services Google
Deployment Manager gère actuellement l'authentification de base (nom d'utilisateur et mot de passe) et l'authentification OAuth 2.0 pour certaines API hébergées sur Google Kubernetes Engine ou sur Google Endpoints. Vous pouvez configurer l'authentification afin d'utiliser le compte de service du projet.
Pour en savoir plus, consultez la page Créer un fournisseur de types.
Les opérations CRUD (création, lecture, mise à jour et suppression) sont acceptées
L'API en question doit être RESTful API compatible avec les opérations CRUD. Ces opérations sont les suivantes :
- Opérations de création : permettent de créer des ressources. Une requête
HTTP POST
doit être effectuée. - Opérations de lecture : permettent d'obtenir des informations sur les ressources de l'API. Une requête
HTTP GET
doit être effectuée. - Opérations de mise à jour : permettent de mettre à jour une ressource. Une requête
HTTP PUT
doit être effectuée. - Opérations de suppression : permettent de supprimer des ressources. Une requête
HTTP DELETE
doit être effectuée.
Une API compatible uniquement avec des opérations CRUD partielles fonctionnera, mais se comportera différemment en fonction des opérations disponibles.
Compatibilité avec les requêtes GET |
Compatibilité avec les requêtes CREATE |
Compatibilité avec les requêtes UPDATE |
Compatibilité avec les requêtes DELETE |
Comportement spécifique de l'API ? |
---|---|---|---|---|
Oui | Oui | Oui | Oui | Aucun |
Oui | Oui | Oui | Non | Les utilisateurs peuvent abandonner une ressource, mais ne peuvent pas la supprimer. |
Oui | Oui | Non | Oui | Toute modification apportée à une ressource existante échoue. Les utilisateurs doivent supprimer et recréer une ressource pour la mettre à jour. |
Oui | Oui | Non | Non | Les deux comportements décrits ci-dessus. |
Oui | Non | Oui | Oui | Si une API n'accepte pas les requêtes de création, les utilisateurs peuvent ajouter des ressources existantes au déploiement en mettant à jour le déploiement avec la règle ACQUIRE . |
Oui | Non | Oui | Non | Les utilisateurs peuvent acquérir une ressource ou la mettre à jour après l'avoir acquise, mais ne peuvent pas la supprimer. |
Oui | Non | Non | Oui | Les utilisateurs peuvent supprimer une ressource et en obtenir une, ou en ajouter une existante à un déploiement. |
Oui | Non | Non | Non | Les utilisateurs peuvent acquérir une ressource existante ou la supprimer avec la règle ABANDON . |
Tous les paramètres de chemins et de requêtes sont résolus
Tous les paramètres de chemins et de requêtes de l'API doivent exister dans le corps de la ressource ou dans toutes les méthodes de l'API afin que Deployment Manager puisse les faire correspondre lorsqu'un utilisateur les fournit. Les conditions suivantes s'appliquent aux paramètres de chemins et de requêtes.
Les paramètres de chemins/requêtes dans la méthode POST doivent également figurer dans la méthode PUT
La déclaration suivante n'est pas valide, car myParameter
est défini dans la méthode POST
, mais pas dans la méthode PUT
:
POST /my-api/{myParameter}/resource/{mySecondParameter}
PUT /my-api/resource/{mySecondParameter} # myParameter is not present
Chaque paramètre des méthodes autres que POST doit figurer soit dans toutes les interfaces de méthodes, soit au sein de la ressource, avec des considérations spéciales si le paramètre est généré par le serveur.
Dans le meilleur des cas, l'API peut ressembler aux exemples suivants dans lesquels le paramètre name
apparaît pour toutes les méthodes.
POST /my-api/my-resource/{name}
PUT /my-api/my-resource/{name}
GET /my-api/my-resource/{name}
DELETE /my-api/my-resource/{name}
Dans un autre scénario, un champ peut apparaître comme un paramètre de chemin pour une méthode, mais pas pour d'autres. Dans ce cas, le champ doit faire partie de la ressource de l'API. Exemple :
POST /my-api/my-resource ← the 'id' field is not present on the POST request
GET /my-api/my-resource/{id}
schema for my-resource
type: object
properties:
# id is part of the resource so Deployment Manager will use this value for
# POST requests after creation
id:
type: string
Dans cet exemple, l'hypothèse est que id
est une valeur générée par le serveur qui est présente sur la ressource, mais pas lors de la création d'une requête POST
. Si la propriété id
est requise pour effectuer une requête sur une ressource existante, mais que la propriété n'est pas présente sur la ressource ni disponible dans le chemin, cela cause des problèmes lors du portage de l'API vers Deployment Manager.
Le comportement subtil de l'API nécessite une configuration supplémentaire
Certains comportements de l'API nécessitent une configuration supplémentaire pour l'intégration à Deployment Manager. Ces comportements incluent les suivants :
Valeurs générées par le serveur : certaines ressources de l'API ont des propriétés générées par le serveur qui changent après chaque requête ou lorsqu'un événement spécifique se produit dans l'API. Vous pouvez utiliser les options d'API avancées pour indiquer à Deployment Manager d'obtenir cette nouvelle valeur chaque fois qu'une requête est envoyée.
Par exemple, une API peut nécessiter la dernière propriété d'empreinte d'une ressource avant d'autoriser une requête de mise à jour. Utilisez les options d'API avancées pour indiquer à Deployment Manager d'obtenir cette valeur chaque fois que l'utilisateur effectue une requête de mise à jour du déploiement.
Gestion des saisies utilisateur : par exemple, si votre API exige que la valeur d'un champ soit toujours précédée par un ID de projet, vous pouvez utiliser des mappages d'entrée pour ajouter automatiquement cette information au lieu d'obliger vos utilisateurs à le faire manuellement.
Valeurs de champ différentes pour chaque méthode : pour les méthodes qui réutilisent le même champ avec des valeurs différentes, vous pouvez utiliser les options de l'API pour indiquer à Deployment Manager quand utiliser quelle valeur.
Pour en savoir plus, consultez la page Définir des options d'API avancées.
Étapes suivantes
- Découvrir comment créer un fournisseur de types
- Découvrir comment utiliser un fournisseur de types
- En savoir plus sur les options d'API avancées
- Découvrir comment créer une configuration
- Créer un déploiement