Вступление
Во второй версии API DigitalOcean каждое происходящее событие создает an объект «Действие». Они служат как отчетами о событиях, которые произошли в прошлом, так и способом проверки хода текущего события. От создания новой капли до переноса изображения в новый регион, объект Action предоставит вам полезную информацию о событии.
В этой статье будут объяснены объекты Action и показано, как их можно использовать на практике с помощью DropletKit, официальный гем Ruby для API DigitalOcean.
Предпосылки
Эта статья предполагает базовое понимание API DigitalOcean. Чтобы узнать больше об API, в том числе о том, как получить токен доступа, который понадобится для выполнения этого руководства, см. Следующие ресурсы:
Понимание объектов действия
При инициировании события с помощью API в ответе будет возвращен объект Action. Этот объект будет содержать информацию о событии, включая его состояние, метки времени, когда оно было запущено и завершено, а также связанный тип ресурса и идентификатор. Например, если мы хотим сделать снимок капли с идентификатором 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"мы получили бы это в ответ:
{
"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 + - это идентификатор капли. + Status - это` + in-progress`. Это изменится на + complete +, как только событие закончится. Чтобы проверить состояние действия, вы можете напрямую запросить 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 + равно + complete +, существует отметка времени для + complete_at +, а также + start_at +.
Вы также можете получить доступ к a полной истории всех действий, совершенных на вашем аккаунте в конечной точке + / actions +.
curl -X GET -H 'Content-Type: application/json' \
-H 'Authorization: Bearer ''' \
"https://api.digitalocean.com/v2/actions"Использование объектов действий на практике
Хотя перечисление всех объектов Action может быть интересным для проверки вашей истории, на практике вы в основном будете использовать эту конечную точку для проверки состояния процесса. Для этих примеров мы будем использовать + droplet_kit +, the официальный гем Ruby для API DigitalOcean. Может быть установлен с:
gem install droplet_kitДля начала войдите в оболочку Ruby, выполнив команду + irb +. Затем импортируйте гем + droplet_kit + и настройте свой клиент, используя свой токен 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, чтобы проверить ход действия до его завершения:
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 + (или загрузите его с this GitHub Gist), вы можете запустить его из командной строки следующим образом :
DO_TOKEN= ruby snapshot.rb ""Обратите внимание, что для использования скрипта вы должны экспортировать свой токен API в качестве переменной среды с именем + DO_TOKEN +. Сценарий принимает два аргумента: идентификатор капли и, необязательно, имя снимка. Если вы не предоставите имя, это будет дата и время.
Заключение
Элементы действий являются важной частью API DigtialOcean. Использование их для проверки статуса действий является важной рекомендацией, которую необходимо реализовать при использовании API. Теперь, когда вы понимаете, как их использовать, вы готовы перейти к более сложным вариантам использования API, таким как:
Зайдите на DigitalOcean портал разработчика, чтобы узнать больше тем.