DigitalOceanAPIでドロップレットタグ付けを使用する方法
序章
DigitalOcean APIは、DigitalOceanコントロールパネルにあるほとんどの機能へのアクセスを提供し、コマンドラインまたは独自のコードからドロップレットやその他のリソースを操作する簡単な方法を提供します。
ドロップレットのタグ付けは新機能です。 この機能を使用すると、タグを適用してドロップレットをグループ化して検索したり、特定のタグを使用してすべてのドロップレットに対してアクションを開始したりできます。
前提条件
このガイドでは、すべての例でcurlユーティリティとBashを使用しています。 これは、DigitalOcean APIの使用に精通しており、パーソナルアクセストークンをすでに生成していることを前提としています。 このプロセスの詳細とAPIの基本的な使用法については、 DigitalOcean APIv2の使用方法を参照してください。
トークンを取得したら、シェルで$TOKEN変数を設定することから始めます。 exportコマンドは、子プロセスが変数を読み取れるようにします。
export TOKEN=your_personal_access_token
このドキュメントの残りの例では、$TOKENを使用します。常に二重引用符で囲まれた文字列内にあるため、リテラル文字列$TOKENではなくその値が補間されます。 エラーが発生した場合は、最初にこの値が現在のシェルで正しく設定されていることを確認してください。
タグの作成、一覧表示、および表示
タグは、リソースに適用する前に作成することも、リソースの作成中に作成して適用することもできます。
独立してタグを作成する
curlを使用してAPIエンドポイントにPOSTを送信します。これには、Content-Typeのヘッダー、個人用アクセストークン、タグ名を指定するためのJSONデータが含まれます。 tag_nameを目的のタグ名に置き換えます。
curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"name":"tag_name"}' \
"https://api.digitalocean.com/v2/tags"
Output{"tag":{"name":"tag_name","resources":{"droplets":{"count":0,"last_tagged":null}}}}
注：このリクエストは、アカウントに変更を加える他のリクエストと同様に、トークンに「書き込み」スコープが割り当てられている必要があります。
他のリソースを作成するときのタグの作成と適用
リソースには、作成時にtags属性を含めることもできます。 これは、作成時に適用されるタグ名の配列です。 まだ存在しないタグは、リクエストを満たすために作成されます。 この記事の執筆時点でサポートされているリソースはDropletのみですが、最終的には他のリソースも利用できるようになります。
ドロップレットを作成し、作成時にタグを適用するには、次のように入力します。
curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"name":"example.com","region":"nyc3","size":"512mb","image":"ubuntu-14-04-x64","tags":["tag_name","another_tag"]}' \
"https://api.digitalocean.com/v2/droplets"
これにより、タグtag_nameおよびanother_tagが適用された新しいドロップレットが作成されます。 前のセクションの例を実行した場合、このコマンドは既存のtag_nameタグを適用し、another_tagタグを作成してドロップレットに適用します。
既存のタグの一覧表示
/v2/tagsへのGETリクエストを使用して、現在のすべてのタグを一覧表示できます。
curl -X GET \ -H "Authorization: Bearer $TOKEN" \ "https://api.digitalocean.com/v2/tags"
Output{"tags":[{"name":"tag_name","resources":{"droplets":{"count":0,"last_tagged":null}}}],"links":{},"meta":{"total":1}}
個々のタグを表示するには、/v2/tags/tag_nameへのGETリクエストを使用します。
curl -X GET \ -H "Authorization: Bearer $TOKEN" \ "https://api.digitalocean.com/v2/tags/tag_name"
Output{"tag":{"name":"tag_name","resources":{"droplets":{"count":0,"last_tagged":null}}}}
上記の出力例は簡単です。 resources.droplets.last_taggedプロパティがnullであることに注意してください。 タグを1つ以上のドロップレットに関連付けると、このプロパティには、最後にタグ付けされたドロップレットに関する詳細情報が含まれます。
ドロップレットのタグ付けとタグ付け解除
タグは既存のリソースにも適用できます。 この記事の執筆時点でサポートされているリソースはDropletのみですが、最終的には他のリソースも利用できるようになります。
ドロップレットは、id属性を使用してタグに関連付けられます。 /v2/dropletsへのGETリクエストを使用して、すべてのドロップレットを一覧表示するdroplets配列を含むJSONオブジェクトを取得できます。
curl -X GET \ -H "Authorization: Bearer $TOKEN" \ "https://api.digitalocean.com/v2/droplets"
ドロップレットのidがわかったら、resource_idをドロップレットidに設定するJSONデータを含め、/v2/tags/tag_name/resourcesにPOSTすることで、タグに関連付けることができます。 resource_typeから文字列dropletへ：
curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"resources":[{"resource_id":"droplet_id","resource_type":"droplet"}]}' \
"https://api.digitalocean.com/v2/tags/tag_name/resources"
タグのGETリクエストを再試行すると、resources.droplets.last_taggedプロパティに、タグ付けしたばかりのドロップレットに関する詳細情報が含まれているはずです。
curl -X GET \ -H "Authorization: Bearer $TOKEN" \ "https://api.digitalocean.com/v2/tags/tag_name"
特定のドロップレットからタグを削除するには、最初にドロップレットにタグを付けるために使用したのと同じデータを使用して、/v2/tags/tag_name/resources/にDELETEリクエストを発行できます。
curl -X DELETE \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"resources":[{"resource_id":"droplet_id","resource_type":"droplet"}]}' \
"https://api.digitalocean.com/v2/tags/tag_name/resources"
これにより、リソースからタグが削除されます。
タグによる液滴の検索
特定のタグに関連付けられているすべてのドロップレットを検索するには、/v2/droplets?tag_name=tag_nameにGETリクエストを発行します。
curl -X GET \ -H "Authorization: Bearer $TOKEN" \ "https://api.digitalocean.com/v2/droplets?tag_name=tag_name"
これにより、要求されたタグでドロップレットがフィルタリングされます。
タグ付けされた液滴に対するアクションの実行
特定のタグに関連付けられているすべてのドロップレットに対して、いくつかのアクションを実行できます。
| データ | ノート |
|---|---|
{"type":"power_cycle"}
|
ドロップレットをオフにしてから再度オンにします。 |
{"type":"power_on"}
|
電源ドロップレットをオンにします。 オフにする必要があります。 |
{"type":"power_off"}
|
パワードロップレットをオフにします。 オンにする必要があります。 |
{"type":"shutdown"}
|
コマンドラインから電源を切るのと同様に、ドロップレットをシャットダウンします。 |
{"type":"enable_private_networking"}
|
プライベートネットワーキングを有効にします。 |
{"type":"enable_ipv6"}
|
ドロップレットのIPv6アドレスを有効にします。 |
{"type":"enable_backups"}
|
ドロップレットのバックアップを有効にします。 |
{"type":"disable_backups"}
|
バックアップを無効にします。 |
{"type":"snapshot, "name": "snapshot_name"}
|
ドロップレットのスナップショットを撮ります。 ドロップレットの電源を最初にオフにする必要があり、nameは必須です。
|
アクションを実行するには、typeとアクションに必要な追加の値を指定するJSONデータを使用してPOSTを/v2/droplets/actions?tag_name=tag_nameに送信します。
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"action_type"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=tag_name"
/v2/actionsへのGETリクエストを使用して、完了ステータスを含む最近のアクションの履歴を取得できます。
curl -X GET \ -H "Authorization: Bearer $TOKEN" \ "https://api.digitalocean.com/v2/actions"
これは、アクションが完了したか、まだ進行中であるかを判断するのに便利な方法です。
例：タグ付き液滴のスナップショット
fileserverという名前のタグに関連付けられたドロップレットのコレクションがあり、それらすべてのスナップショットを作成するとします。
最初にshutdownアクションを発行します。
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"shutdown"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=fileserver"
すべてのドロップレットでシャットダウンが完了するのを待ち、スナップショットのname値を含むsnapshotアクションを発行します。
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"snapshot", "name":"snapshot_name"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=fileserver"
ドロップレットのサイズによっては、スナップショットが完了するまでに1時間以上かかる場合があることに注意してください。 スナップショットが終了したら、power_onアクションを使用してドロップレットをオンラインに戻すことができます。
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"power_on"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=fileserver"
これにより、ドロップレットが再開されます。
タグの削除
/v2/tags/tag_nameへのDELETEリクエストを使用して、タグ自体を削除し、すべてのリソースへの関連付けを削除できます。
curl -X DELETE \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $TOKEN" \ "https://api.digitalocean.com/v2/tags/tag_name"
タグは完全に削除されます。
結論
タグ付けは単純な抽象化ですが、基本的なスクリプトツールと組み合わせることで、システムのインベントリと管理のための強力なメカニズムを提供できます。
ここから、詳細なDigitalOcean APIドキュメントを詳しく調べたり、一般的なプログラミング言語のAPIをラップするライブラリを調べたりすることができます。
