如何使用并理解动作对象和DigitalOcean应用程序接口

介绍

在DigitalOcean API的第二版本中,每个发生的事件都会创建一个行动对象(https://developers.digitalocean.com/documentation/v2/#actions)。这些都是过去发生的事件记录,也是检查正在进行的事件进度的一种方式。

本文将解释动作对象,并展示如何通过DropletKit(DigitalOcean API的官方卢比宝石)在实践中使用它们(https://rubygems.org/gems/droplet_kit)。

前提条件

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

理解行动对象

使用 API 启动事件时,响应中会返回一个 Action 对象. 该对象将包含有关事件的信息,包括其状态、开始和完成时的时刻标记以及相关资源类型和 ID。

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

我们会收到这个作为回应:

 1{
 2  "action": {
 3    "id": 36805022,
 4    "status": "in-progress",
 5    "type": "snapshot",
 6    "started_at": "2014-11-14T16:34:39Z",
 7    "completed_at": null,
 8    "resource_id": 3164450,
 9    "resource_type": "droplet",
10    "region": "nyc3"
11  }
12}

请注意,resource_type是dropplet,而resource_id是Dropplet的ID。status是in-progress。一旦事件完成,它将更改为Completed。

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

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

 1{
 2  "action": {
 3    "id": 36805022,
 4    "status": "completed",
 5    "type": "snapshot",
 6    "started_at": "2014-11-14T16:34:39Z",
 7    "completed_at": "2014-11-14T16:38:52Z",
 8    "resource_id": 3164450,
 9    "resource_type": "droplet",
10    "region": "nyc3"
11  }
12}

請注意,現在「狀態」是「完成」,有「完成_at」和「開始_at」的時刻印。

您还可以访问在您的帐户中的/actions终端点上执行的所有操作的完整历史(https://developers.digitalocean.com/v2/#list-all-actions)。

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

在实践中使用行动对象

虽然列出所有动作对象可能有趣,以便审核您的历史,但在实践中,您通常会使用此终点来检查一个过程的状态。

1gem install droplet_kit

要开始,请通过运行命令 irb 输入 Ruby 壳,然后导入 droplet_kit 宝石,并使用 API 代币设置您的客户端:

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

某些操作取决于其他操作先进行。例如,尝试拍摄仍在启动的 Droplet 时会导致错误。

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

试图在启动关闭操作后立即拍摄快照也会导致相同的错误,因为您必须确保关闭操作在可以拍摄快照之前完成。

1irb(main):> client.droplet_actions.shutdown(droplet_id: 4143310)
2=> <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"}>
3irb(main):> client.droplet_actions.snapshot(droplet_id: 4143310, name: 'Snapshot Name')
4=> "{\"id\":\"unprocessable_entity\",\"message\":\"Droplet is currently on. Please power it off to run this event.\"}"

与上面的弯曲示例一样,droplet_kit还会返回行动对象,以响应成功启动的事件. 它可以作为一个正常的 Ruby 对象访问。

1irb(main):> snapshot = client.droplet_actions.snapshot(droplet_id: 4143310, name: 'Snapshot Name')
2=> "{\"id\":\"unprocessable_entity\",\"message\":\"Droplet is currently on. Please power it off to run this event.\"}"
3irb(main):> shutdown = client.droplet_actions.shutdown(droplet_id: 4143310)
4=> <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"}>
5irb(main):> shutdown.status
6=> "in-progress"
7irb(main):> shutdown.id
8=> 43919195

然后你可以检查行动的状态:

1irb(main):> action = client.actions.find(id: shutdown.id)
2=> <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"}>
3irb(main):> action.status
4=> "completed"

我们可以在Ruby中使用一个直到循环来检查一个动作的进展,直到它完成:

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

把一切都放在一起

这个 Ruby 脚本是如何在实践中检查一个操作的状态的一个例子,它可以关闭一个滴滴,并从上方使用而循环来确保该操作在继续之前已经完成。

 1#!/usr/bin/env ruby
 2
 3require 'droplet_kit'
 4require 'json'
 5
 6token = ENV['DO_TOKEN']
 7client = DropletKit::Client.new(access_token: token)
 8
 9droplet_id = ARGV[0]
10snapshot_name = ARGV[1] || Time.now.strftime("%b. %d, %Y - %H:%M:%S %Z")
11
12def power_off(client, id)
13    res = client.droplet_actions.shutdown(droplet_id: id)
14    until res.status == "completed"
15        res = client.actions.find(id: res.id)
16        sleep(2)
17    end
18    puts " *   Action status: #{res.status}"
19rescue NoMethodError
20    puts JSON.parse(res)['message']
21end
22
23def take_snapshot(client, id, name)
24    res = client.droplet_actions.snapshot(droplet_id: id, name: name)
25    puts " *   Action status: #{res.status}"
26rescue NameError
27    puts JSON.parse(res)['message']
28end
29
30unless droplet_id.nil?
31    puts "Powering off droplet..."
32    power_off(client, droplet_id)
33    sleep(2)
34    puts "Taking snapshot..."
35    take_snapshot(client, droplet_id, snapshot_name)
36else
37    puts "Power off and snapshot a droplet. Requires a droplet ID and optionally a snapshot name."
38    puts "Usage: #{$0} droplet_id ['snapshot name']"
39end

如果您将此脚本保存为名为snapshot.rb的文件(或从 GitHub Gist下载),您可以从命令行执行它,如下:

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

请注意,要使用脚本,您必须将 API 代币导出为环境变量,名称为DO_TOKEN。脚本需要两个参数,即滴滴的 ID 和可选的快照名称。

结论

操作项目是 DigtialOcean API 的重要组成部分。使用它们来检查操作的状态是使用 API 时实施的重要最佳实践. 现在您已经了解如何使用它们,您已经准备好转向更复杂的 API 用例,如:

如何在DigitalOcean上自动扩展您的Web应用程序

查看 DigitalOcean 开发者门户查看更多主题。