Comment utiliser et comprendre les objets d’action et l’API DigitalOcean

introduction

Dans la deuxième version de l’API DigitalOcean, chaque événement généré crée an un objet «Action». Celles-ci servent à la fois de comptes rendus d’événements survenus dans le passé et de vérification de la progression d’un événement en cours. De la création d’un nouveau Droplet au transfert d’une image dans une nouvelle région, un objet Action vous fournira des informations utiles sur l’événement.

Cet article explique les objets Action et montre comment ils peuvent être utilisés dans la pratique via DropletKit, la gemme officielle de Ruby pour l’API DigitalOcean.

Conditions préalables

Cet article suppose une compréhension de base de l’API DigitalOcean. Pour en savoir plus sur l’API, notamment sur l’obtention d’un jeton d’accès nécessaire à la réalisation de ce didacticiel, voir les ressources suivantes:

Comprendre les objets d’action

Lors du lancement d’un événement avec l’API, un objet Action sera renvoyé dans la réponse. Cet objet contiendra des informations sur l’événement, notamment son statut, les horodatages de son démarrage et de son achèvement, ainsi que le type de ressource et l’ID associés. Par exemple, si nous prenons un instantané de la droplet avec l’ID 3164450:

curl -X POST -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer ''' \
   -d '{"type":"snapshot","name":"Nifty New Snapshot"}' \
   "https://api.digitalocean.com/v2/droplets//actions"

nous recevrions ceci en réponse:

{
 "action": {
   "id": 36805022,
   "status": "in-progress",
   "type": "snapshot",
   "started_at": "2014-11-14T16:34:39Z",
   "completed_at": null,
   "resource_id": 3164450,
   "resource_type": "droplet",
   "region": "nyc3"
 }
}

Notez que le + type_ressource + est + droplet + et le + id_ressource + est l’ID du droplet. Le + statut est` + en cours`. Cela passera à + ​​terminé + une fois l’événement terminé. Afin de vérifier le statut d’une action, vous pouvez interroger directement l’API pour cette action.

curl -X GET -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer ''' \
   "https://api.digitalocean.com/v2/actions/"

Ceci retournera l’objet d’action demandé:

{
 "action": {
   "id": 36805022,
   "status": "completed",
   "type": "snapshot",
   "started_at": "2014-11-14T16:34:39Z",
   "completed_at": "2014-11-14T16:38:52Z",
   "resource_id": 3164450,
   "resource_type": "droplet",
   "region": "nyc3"
 }
}

Notez que maintenant que le + statut + est + terminé +, il existe un horodatage pour + completed_at + ainsi que + started_at +.

Vous pouvez également accéder à un historique complet de toutes les actions effectuées sur votre compte au point de terminaison + / actions +.

curl -X GET -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer ''' \
   "https://api.digitalocean.com/v2/actions"

Utiliser les objets Actions en pratique

Bien que la liste de tous les objets Action puisse être intéressante pour l’audit de votre historique, vous utiliserez principalement ce noeud final pour contrôler le statut d’un processus. Nous allons utiliser + droplet_kit +, de la gemme officielle de Ruby pour l’API DigitalOcean, pour ces exemples. Il peut être installé avec:

gem install droplet_kit

Pour commencer, entrez dans le shell Ruby en exécutant la commande + irb + puis importez le gem + droplet_kit + et configurez votre client à l’aide de votre jeton d’API:

irb(main):> require 'droplet_kit'
=> true
irb(main):> client = DropletKit::Client.new(access_token: )

Certaines actions dépendent des autres prises en premier. Par exemple, si vous essayez de prendre un instantané d’un droplet encore sous tension, une erreur se produira. Un droplet doit être éteint pour pouvoir prendre un instantané.

irb(main):> client.droplet_actions.snapshot(droplet_id: 4143310, name: 'Snapshot Name')
=> "{\"id\":\"unprocessable_entity\",\"message\":\"Droplet is currently on. Please power it off to run this event.\"}"

Si vous tentez de prendre un instantané immédiatement après le lancement d’une action d’arrêt, vous obtiendrez également la même erreur car vous devez vous assurer que l’action d’arrêt est terminée avant que l’instantané ne puisse être pris. Les actions ne peuvent pas être mises en file d’attente.

irb(main):> client.droplet_actions.shutdown(droplet_id: 4143310)
=> <DropletKit::Action {:@id=>43918785, :@status=>"in-progress", :@type=>"shutdown", :@started_at=>"2015-02-16T21:22:35Z", :@completed_at=>nil, :@resource_id=>4143310, :@resource_type=>"droplet", :@region=>"nyc3"}>
irb(main):> client.droplet_actions.snapshot(droplet_id: 4143310, name: 'Snapshot Name')
=> "{\"id\":\"unprocessable_entity\",\"message\":\"Droplet is currently on. Please power it off to run this event.\"}"

Comme les exemples + curl + ci-dessus, + droplet_kit + renvoie également l’objet Action en réponse à un événement initié avec succès. On peut y accéder en tant qu’objet Ruby normal. Enregistrer la réponse dans une variable vous permettra d’accéder directement à ses attributs:

irb(main):> snapshot = client.droplet_actions.snapshot(droplet_id: 4143310, name: 'Snapshot Name')
=> "{\"id\":\"unprocessable_entity\",\"message\":\"Droplet is currently on. Please power it off to run this event.\"}"
irb(main):> shutdown = client.droplet_actions.shutdown(droplet_id: 4143310)
=> <DropletKit::Action {:@id=>43919195, :@status=>"in-progress", :@type=>"shutdown", :@started_at=>"2015-02-16T21:32:03Z", :@completed_at=>nil, :@resource_id=>4143310, :@resource_type=>"droplet", :@region=>"nyc3"}>
irb(main):> shutdown.status
=> "in-progress"
irb(main):> shutdown.id
=> 43919195

Vous pouvez ensuite vérifier le statut des actions:

irb(main):> action = client.actions.find(id: shutdown.id)
=> <DropletKit::Action {:@id=>43919195, :@status=>"completed", :@type=>"shutdown", :@started_at=>"2015-02-16T21:32:03Z", :@completed_at=>"2015-02-16T21:32:07Z", :@resource_id=>4143310, :@resource_type=>"droplet", :@region=>"nyc3"}>
irb(main):> action.status
=> "completed"

Nous pouvons utiliser une boucle + Until + dans Ruby pour vérifier la progression d’une action jusqu’à ce qu’elle soit terminée:

res = client.droplet_actions.shutdown(droplet_id: id)
until res.status == "completed"
   res = client.actions.find(id: res.id)
   sleep(2)
end

Mettre tous ensemble

Ce script Ruby ci-dessous montre comment vérifier le statut d’une action dans la pratique. Il met un droplet hors tension et utilise la boucle + while + d’en haut pour s’assurer que l’action est terminée avant de poursuivre. Une fois que l’arrêt est terminé, il prend un instantané du droplet.

#!/usr/bin/env ruby

require 'droplet_kit'
require 'json'

token = ENV['DO_TOKEN']
client = DropletKit::Client.new(access_token: token)

droplet_id = ARGV[0]
snapshot_name = ARGV[1] || Time.now.strftime("%b. %d, %Y - %H:%M:%S %Z")

def power_off(client, id)
   res = client.droplet_actions.shutdown(droplet_id: id)
   until res.status == "completed"
       res = client.actions.find(id: res.id)
       sleep(2)
   end
   puts " *   Action status: #{res.status}"
rescue NoMethodError
   puts JSON.parse(res)['message']
end

def take_snapshot(client, id, name)
   res = client.droplet_actions.snapshot(droplet_id: id, name: name)
   puts " *   Action status: #{res.status}"
rescue NameError
   puts JSON.parse(res)['message']
end

unless droplet_id.nil?
   puts "Powering off droplet..."
   power_off(client, droplet_id)
   sleep(2)
   puts "Taking snapshot..."
   take_snapshot(client, droplet_id, snapshot_name)
else
   puts "Power off and snapshot a droplet. Requires a droplet ID and optionally a snapshot name."
   puts "Usage: #{$0} droplet_id ['snapshot name']"
end

Si vous enregistrez ce script dans un fichier nommé + snapshot.rb + (ou le téléchargez à partir de this GitHub Gist), vous pouvez l’exécuter à partir de la ligne de commande comme suit :

DO_TOKEN= ruby snapshot.rb  ""

Notez que pour utiliser le script, vous devez exporter votre jeton d’API en tant que variable d’environnement portant le nom + DO_TOKEN +. Le script utilise deux arguments, l’ID du droplet et éventuellement le nom de l’instantané. Si vous ne fournissez pas de nom, ce sera la date et l’heure.

Conclusion

Les actions sont une partie importante de l’API DigtialOcean. Leur utilisation pour vérifier le statut des actions est une pratique recommandée importante à mettre en œuvre lors de l’utilisation de l’API. Maintenant que vous avez compris comment les utiliser, vous êtes prêt à passer à des cas d’utilisation plus complexes de l’API, tels que:

Consultez le site DigitalOcean pour les développeurs pour plus de rubriques.

Related