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

介绍

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

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

先决条件

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

• 如何使用DigitalOcean API v2
• DigitalOcean APIv2文档

了解操作对象

当使用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_type是droplet和resource_id是Droplet的ID。 该status是in-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"
  }
}

注意如何现在的status是completed ，有对于时间戳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上自动化您的Web应用程序的扩展

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