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をラップするライブラリを調べたりすることができます。