如何理解和使用Action对象和DigitalOcean API

在DigitalOcean API两个版本,出现每个事件产生[的“行动”的对象(https://developers.digitalocean.com/v2/#actions)。这些既作为发生在过去,作为一种方法来检查一个持续事项的进展情况的事件记录。从创建一个新的Droplet的图像传送到一个新的区域,Action对象会为您提供有关该事件的有用信息。本文将解释Action对象并展示它们如何在实践中使用。

介绍

在DigitalOcean API两个版本中,发生的每个事件创建一个“行动”的对象 这些都用作过去发生的事件的记录,并且作为检查正在进行的事件的进展的方式。 从创建新的Droplet到将图像传输到新区域,Action对象将为您提供有关事件的有用信息。

本文将解释Action对象并展示它们如何在实践中通过DropletKit,使用官方的RubyGem的DigitalOcean API

先决条件

本文假设您对DigitalOcean API有基本的了解。 要了解有关API的更多信息,包括如何获取完成本教程所需的访问令牌,请参阅以下资源:

了解操作对象

当使用API​​启动事件时,Action对象将在响应中返回。 此对象将包含有关事件的信息,包括事件的状态,启动和完成时间戳的时间戳以及相关联的资源类型和ID。 例如,如果我们在哪里拍摄ID为3164450的Droplet的快照:

curl -X POST -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer '$TOKEN'' \
    -d '{"type":"snapshot","name":"Nifty New Snapshot"}' \
    "https://api.digitalocean.com/v2/droplets/3164450/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_typedropletresource_id是Droplet的ID。 statusin-progress 这将改变到completed ,一旦事件结束。 为了检查Action的状态,您可以直接查询该Action的API。

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

这将返回请求的操作对象:

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

注意如何现在的statuscompleted ,有对于时间戳completed_at以及started_at

您也可以访问所有动作的完整历史记录在您的帐户在拍摄/actions端点。

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

在实践中使用操作对象

列出所有Action对象可能是有趣的,以便审计您的历史记录,在实践中,您将主要使用此端点,以便检查进程的状态。 我们将使用droplet_kit官方RubyGem的DigitalOcean API ,这些示例。 它可以安装:

gem install droplet_kit

上手,通过运行以下命令进入Ruby的外壳irb然后导入droplet_kitGem和设置您的客户端使用API令牌:

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

一些行动取决于首先采取的其他行动。 例如,尝试拍摄仍处于开机状态的Droplet的快照将导致错误。 必须关闭Droplet才能拍摄快照。

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也返回响应于成功地启动的事件的动作的对象。 它可以作为普通的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"

我们可以使用until在Ruby中循环来检查行动的进展情况,直至完成:

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

把它放在一起

下面的Ruby脚本是一个在实践中如何检查一个动作的状态的例子。 它的权力Droplet断,并使用while从上述循环,以确保该动作已移动之前完成。 一旦关闭动作完成,它将拍摄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

如果您保存该脚本文件名为snapshot.rb (或从这里下载这个GitHub的要点 ),你可以像这样在命令行中运行它:

DO_TOKEN=YOUR_DO_API_TOKEN ruby snapshot.rb 12345 "My Snapshot"

请注意,为了使用该脚本,您必须在API令牌导出为与名称的环境变量DO_TOKEN 该脚本接受两个参数,即Droplet的ID和可选的快照名称。 如果你不提供名称,它将是日期和时间。

结论

行动项目是DigtialOcean API的重要组成部分。 使用它们来检查操作的状态是使用API​​时实施的一个重要的最佳实践。 现在您已了解如何使用它们,您就可以开始使用更复杂的API用例,例如:

退房DigitalOcean开发者门户网站为更多的话题。