Comment utiliser le marquage par gouttelettes avec l’API DigitalOcean

introduction

L'API DigitalOcean fournit un accès à la plupart des fonctionnalités du panneau de configuration de DigitalOcean et offre un moyen simple de manipuler des gouttelettes et d'autres ressources à partir de la ligne de commande ou de votre propre code.

Le marquage par gouttelettes est une nouvelle fonctionnalité. La fonctionnalité vous permet de regrouper et de localiser les gouttelettes en appliquant des balises, ainsi que de lancer des actions sur toutes les gouttelettes avec une balise spécifique.

Conditions préalables

Ce guide utilise l'utilitairecurl et Bash pour tous les exemples. Il suppose que vous êtes familiarisé avec l'utilisation de l'API DigitalOcean et que vous avez déjà généré unpersonal access token. Pour plus de détails sur ce processus et les bases de l'utilisation de l'API, consultezHow To Use the DigitalOcean API v2.

Une fois que vous avez un jeton, commencez par définir la variable$TOKEN dans votre shell. La commandeexport garantit que les processus enfants peuvent lire la variable:

export TOKEN=your_personal_access_token

Nous utiliserons$TOKEN pour le reste des exemples de ce document, toujours à l'intérieur d'une chaîne entre guillemets afin que sa valeur, plutôt que la chaîne littérale$TOKEN, soit interpolée. Si vous recevez des erreurs, assurez-vous d'abord que cette valeur est correctement définie dans votre shell actuel.

Création, liste et affichage des balises

Les balises peuvent être créées avant d’être appliquées aux ressources ou créées et appliquées lors de la création des ressources.

Créer des balises indépendamment

Utilisezcurl pour envoyer un POST au point de terminaison de l'API, y compris les en-têtes pour lesContent-Type, votre jeton d'accès personnel et certaines données JSON pour spécifier le nom de la balise. Remplacez le nom de tag souhaité partag_name:

curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"name":"tag_name"}' \
"https://api.digitalocean.com/v2/tags"

Output{"tag":{"name":"tag_name","resources":{"droplets":{"count":0,"last_tagged":null}}}}

[.note] #Note: cette demande, comme toute autre demande qui modifie votre compte, nécessite que votre jeton ait une portée «écriture» qui lui est attribuée.
#

Création et application de balises lors de la création d'autres ressources

Les ressources peuvent également inclure un attributtags lors de la création. Il s'agit d'un tableau de noms de balises qui seront appliqués lors de la création. Les balises qui n'existent pas déjà seront créées pour satisfaire la demande. Au moment de la rédaction de cet article, la seule ressource prise en charge est un Droplet, mais d’autres seront éventuellement disponibles.

Pour créer une Droplet et appliquer des balises lors de la création, vous pouvez taper:

curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"name":"example.com","region":"nyc3","size":"512mb","image":"ubuntu-14-04-x64","tags":["tag_name","another_tag"]}' \
"https://api.digitalocean.com/v2/droplets"

Cela créera un nouveau Droplet avec les balisestag_name etanother_tag appliquées. Si l'exemple de la section précédente a été exécuté, cette commande appliquerait la balisetag_name existante et créerait et appliquerait la baliseanother_tag au droplet.

Liste des balises existantes

Vous pouvez lister toutes vos balises actuelles avec une requête GET à/v2/tags:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/tags"

Output{"tags":[{"name":"tag_name","resources":{"droplets":{"count":0,"last_tagged":null}}}],"links":{},"meta":{"total":1}}

Pour afficher une balise individuelle, utilisez une requête GET à/v2/tags/tag_name:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/tags/tag_name"

Output{"tag":{"name":"tag_name","resources":{"droplets":{"count":0,"last_tagged":null}}}}

L'exemple de sortie ci-dessus est bref. Notez que la propriétéresources.droplets.last_tagged estnull. Une fois que vous avez associé une balise à une ou plusieurs gouttelettes, cette propriété contient des informations détaillées sur la dernière gouttelette marquée.

Marquage et déstiquetage des gouttelettes

Les balises peuvent également être appliquées aux ressources existantes. Au moment de la rédaction de cet article, la seule ressource prise en charge est un Droplet, mais d’autres seront éventuellement disponibles.

Les gouttelettes sont associées aux balises à l'aide de leur attributid. Vous pouvez récupérer un objet JSON contenant un tableaudroplets répertoriant tous vos Droplets avec une requête GET à/v2/droplets:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/droplets"

Une fois que vous connaissez lesid d'un Droplet, vous pouvez l'associer à un tag en POSTANT sur/v2/tags/tag_name/resources, y compris les données JSON qui définissentresource_id sur les Dropletid etresource_type à la chaînedroplet:

curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"resources":[{"resource_id":"droplet_id","resource_type":"droplet"}]}' \
"https://api.digitalocean.com/v2/tags/tag_name/resources"

Essayez à nouveau une requête GET pour la balise, et la propriétéresources.droplets.last_tagged devrait contenir des informations détaillées sur le droplet que vous venez de baliser:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/tags/tag_name"

Pour supprimer une balise d'un Droplet spécifique, vous pouvez envoyer une requête DELETE à/v2/tags/tag_name/resources/, avec les mêmes données que vous avez utilisées pour marquer le Droplet en premier lieu:

curl -X DELETE \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"resources":[{"resource_id":"droplet_id","resource_type":"droplet"}]}' \
"https://api.digitalocean.com/v2/tags/tag_name/resources"

Cela supprimera la balise de la ressource.

Trouver des gouttelettes par étiquette

Pour trouver toutes les gouttelettes associées à une balise particulière, envoyez une requête GET à/v2/droplets?tag_name=tag_name:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/droplets?tag_name=tag_name"

Cela filtrera vos gouttelettes en fonction de la balise demandée.

Effectuer des actions sur des gouttelettes étiquetées

Vous pouvez effectuer un certain nombre d’actions sur toutes les gouttelettes associées à une balise spécifique:

Data Remarques

Data	Remarques
`{"type":"power_cycle"}`	Éteignez et rallumez Droplets.
`{"type":"power_on"}`	Power Droplets sur. Doit être éteint.
`{"type":"power_off"}`	Éteignez les gouttelettes. Doit être sur.
`{"type":"shutdown"}`	Shutdown Droplets, similaire à la mise hors tension à partir de la ligne de commande.
`{"type":"enable_private_networking"}`	Activezprivate networking.
`{"type":"enable_ipv6"}`	ActivezIPv6 addresses pour les gouttelettes.
`{"type":"enable_backups"}`	Activez les sauvegardes pour les gouttelettes.
`{"type":"disable_backups"}`	Désactivez les sauvegardes.
`{"type":"snapshot, "name": "snapshot_name"}`	Prenez des instantanés des gouttelettes. Les gouttelettes doivent d'abord être éteintes et un`name` est obligatoire.

{"type":"power_cycle"}

Éteignez et rallumez Droplets.

{"type":"power_on"}

Power Droplets sur. Doit être éteint.

{"type":"power_off"}

Éteignez les gouttelettes. Doit être sur.

{"type":"shutdown"}

Shutdown Droplets, similaire à la mise hors tension à partir de la ligne de commande.

{"type":"enable_private_networking"}

Activezprivate networking.

{"type":"enable_ipv6"}

ActivezIPv6 addresses pour les gouttelettes.

{"type":"enable_backups"}

Activez les sauvegardes pour les gouttelettes.

{"type":"disable_backups"}

Désactivez les sauvegardes.

{"type":"snapshot, "name": "snapshot_name"}

Prenez des instantanés des gouttelettes. Les gouttelettes doivent d'abord être éteintes et unname est obligatoire.

Pour effectuer une action, envoyez un POST à/v2/droplets/actions?tag_name=tag_name avec des données JSON en spécifiant untype et toutes les valeurs supplémentaires requises par l'action:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"action_type"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=tag_name"

Vous pouvez récupérer un historique des actions récentes, y compris leur état d'achèvement, avec une requête GET à/v2/actions:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/actions"

C'est un moyen utile de déterminer si les actions sont terminées ou sont toujours en cours.

Exemple: instantané des gouttelettes marquées

Supposons que vous ayez une collection de Droplets associée à une balise nomméefileserver et que vous souhaitiez toutes les instantanées.

Exécutez d'abord une actionshutdown:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"shutdown"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=fileserver"

Attendez que l'arrêt se termine sur toutes les gouttelettes et exécutez une actionsnapshot, y compris une valeurname pour l'instantané:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"snapshot", "name":"snapshot_name"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=fileserver"

Notez que la réalisation des instantanés peut prendre une heure ou plus, selon la taille de la gouttelette. Une fois les instantanés terminés, vous pouvez remettre les gouttelettes en ligne avec une actionpower_on:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"power_on"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=fileserver"

Cela va redémarrer la gouttelette.

Suppression de balises

Vous pouvez supprimer une balise elle-même et supprimer son association à toutes les ressources, avec une requête DELETE à/v2/tags/tag_name:

curl -X DELETE \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/tags/tag_name"

La balise sera complètement enlevée.

Conclusion

Le balisage est une simple abstraction, mais associé à des outils de script de base, il peut offrir un mécanisme puissant d’inventaire et de gestion de vos systèmes.

De là, vous voudrez peut-être creuser plus profondément dans lesdetailed DigitalOcean API documentation, ou enquêter surlibraries which wrap the API for popular programming languages.

TOC