アクションオブジェクトとDigitalOcean APIの使用方法と理解方法

前書き

DigitalOcean APIのバージョン2では、発生する各イベントによりhttps://developers.digitalocean.com/documentation/v2/#actions [「アクション」オブジェクト]が作成されます。これらは、過去に発生したイベントの記録としても、進行中のイベントの進行状況を確認する方法としても機能します。新しいドロップレットの作成から画像の新しい領域への転送まで、Actionオブジェクトはイベントに関する有用な情報を提供します。

この記事では、Actionオブジェクトについて説明し、DropletKit、https：//rubygems.org/gems/droplet_kit [DigitalOcean APIの公式Ruby gem]を介して実際に使用する方法を示します。

前提条件

この記事は、DigitalOcean APIの基本的な理解を前提としています。このチュートリアルを完了するために必要なアクセストークンの取得方法など、APIの詳細については、次のリソースを参照してください。

アクションオブジェクトについて

APIでイベントを開始すると、応答でActionオブジェクトが返されます。このオブジェクトには、イベントのステータス、開始時と完了時のタイムスタンプ、関連するリソースタイプとIDなどのイベントに関する情報が含まれます。たとえば、ID 3164450のDropletのスナップショットを取得する場合：

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"

応答としてこれを受け取ります。

{
 "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"
 }
}

「+ resource_type 」は「 droplet 」であり、「 resource_id 」はドロップレットのIDです。 ` status`は` + in-progress`です。イベントが終了すると、これは「+ completed +」に変わります。アクションのステータスを確認するには、そのアクションのAPIを直接クエリできます。

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

これにより、要求されたアクションオブジェクトが返されます。

{
 "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"
 }
}

+ status +`が `+ completed +`になったことに注意してください。+ completed_at + と + started_at + `のタイムスタンプがあります。

`+ / actions +`エンドポイントでアカウントで取得したhttps://developers.digitalocean.com/v2/#list-all-actions [すべてのアクションの完全な履歴]にアクセスすることもできます。

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

実際のアクションオブジェクトの使用

すべてのActionオブジェクトをリストすることは履歴を監査するために興味深いかもしれませんが、実際にはプロセスのステータスをチェックするためにこのエンドポイントを主に使用します。これらの例では、 + droplet_kit +、https：//rubygems.org/gems/droplet_kit [DigitalOcean APIの公式Ruby gem]を使用します。以下を使用してインストールできます。

gem install droplet_kit

開始するには、コマンド + irb +`を実行してRubyシェルに入り、 `+ droplet_kit + gemをインポートして、APIトークンを使用してクライアントをセットアップします。

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

一部のアクションは、最初に実行される他のアクションに依存しています。たとえば、まだ電源が入っているドロップレットのスナップショットを取得しようとすると、エラーが発生します。スナップショットを取得するには、ドロップレットの電源を切る必要があります。

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.\"}"

シャットダウンアクションを開始した直後にスナップショットを取得しようとすると、スナップショットを取得する前にシャットダウンアクションが完了していることを確認する必要があるため、同じエラーが発生します。アクションをキューに入れることはできません。

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.\"}"

上記の `+ curl `の例のように、 ` droplet_kit +`は、正常に開始されたイベントへの応答としてActionオブジェクトも返します。通常のRubyオブジェクトとしてアクセスできます。応答を変数に保存すると、その属性に直接アクセスできます。

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

その後、アクションのステータスを確認できます。

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"

Rubyで `+ until +`ループを使用して、完了するまでActionの進行状況を確認できます。

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

すべてを一緒に入れて

以下のRubyスクリプトは、実際にアクションのステータスを確認する方法の例です。ドロップレットの電源を切り、上から移動する前にアクションが完了したことを確認するために、上からの「+ while +」ループを使用します。シャットダウンアクションが完了すると、ドロップレットのスナップショットが作成されます。

#!/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

このスクリプトを「+ snapshot.rb +」という名前のファイルとして保存する（またはhttps://gist.github.com/andrewsomething/d06f57b98ced36042ae6[this GitHub Gist]からダウンロードする）場合は、次のようにコマンドラインから実行できます。：

DO_TOKEN= ruby snapshot.rb  ""

スクリプトを使用するには、APIトークンを環境変数として「+ DO_TOKEN +」という名前でエクスポートする必要があることに注意してください。スクリプトは、ドロップレットのIDと、オプションでスナップショットの名前の2つの引数を取ります。名前を指定しない場合は、日付と時刻になります。

結論

アクションアイテムは、DigtialOcean APIの重要な部分です。これらを使用してアクションのステータスを確認することは、APIを使用するときに実装する重要なベストプラクティスです。これらの使用方法が理解できたので、次のようなAPIのより複雑なユースケースに進む準備ができました。

DigitalOceanでWebアプリケーションのスケーリングを自動化する方法

その他のトピックについては、https：//developers.digitalocean.com/guides/ [DigitalOcean開発者のポータル]をご覧ください。

TOC

アクションオブジェクトとDigitalOcean APIの使用方法と理解方法

前書き

前提条件

アクションオブジェクトについて

実際のアクションオブジェクトの使用

すべてを一緒に入れて

結論

Related