API実行編#
初期構築ガイドでは、初めて本サービスを利用される方向けにIaaSポータルを中心に仮想サーバーCentOSを構築し、OSに接続するまでの手順を説明しました。
本章では、すでに構築した仮想サーバーCentOSを使用して、APIを実行する手順を説明します。
API実行の全体の流れ#
本ガイドで説明する全体の流れを以下に示します。
No | 項目 | 説明 |
---|---|---|
1 | 実行環境(CentOS)の準備 | APIを実行する環境を準備します。 あらかじめ初期構築ガイドにしたがい、 仮想サーバーCentOSを作成し、 OSに接続できることが前提となります。 |
2 | curlコマンドの使用方法 | 本サービスのAPIを実行する上で必要となる curlコマンドの使用方法を説明します。 |
3 | エンドポイントの設定 | APIを発行するエンドポイントについて説明します。 |
4 | APIの実行方法 | 仮想サーバーに対するAPIの実行方法を説明します。 |
(1) 仮想サーバーの一覧情報取得 | 仮想サーバーの一覧情報を取得する方法を説明します。 | |
(2) 仮想サーバーの状態確認 | 仮想サーバー一覧の状態を確認する方法を説明します。 | |
(3) 仮想サーバーの停止 | 仮想サーバーの状態を確認し、仮想サーバーを 停止する方法を説明します。 |
|
(4) 仮想サーバーの起動 | 仮想サーバーの状態を確認し、仮想サーバーを 起動する方法を説明します。 |
|
(5) 仮想サーバーの削除 | 仮想サーバーの一覧を確認し、対象の仮想サーバーを 削除する方法を説明します。 |
|
(6) 仮想サーバーの作成 | 新規に仮想サーバーを作成する方法を説明します。 | |
(7) 仮想サーバーの情報更新 | 作成した仮想サーバーの情報(ここでは仮想サーバー名)を 更新する方法を説明します。 |
1.実行環境(CentOS)の準備#
初期構築ガイドで構築した仮想サーバーCentOSを使用して、APIを実行する手順を説明します。
本ガイドでは、仮想サーバーCentOSからAPIを実行するため、必要なツールをOSにインストールします。
仮想サーバー接続を参照し、仮想サーバーにログインしてください。
(1) rootユーザーへの変更#
以下のコマンドでrootユーザーへ変更します。
$ sudo su -
(2) jqパッケージのインストール#
curlコマンドの出力結果を整形し、見やすくするため、jqパッケージをインストールします。 以下のyumコマンドでインストールしてください。
# yum install epel-release # yum install jq
以上で準備作業は完了です。この仮想サーバーからAPIを実行する方法を説明します。
2. curlコマンドの使用方法#
本サービスのリソースを操作するには、APIまたはGUIの2種類の方法があります。ここでは、APIを使用する方法を説明します。なお、GUIでの操作方法については、初期構築ガイド(SSL-VPNによるOS接続)を参照してください。
curlコマンドについて#
- curl - transfer a URL
curlコマンドは、次のプロトコルを使うために、サーバーに対してデータを転送するためのツールです。コマンド自体は、ユーザーとシステムのやり取りをせずに動作するように設計されています。
本ガイドでは、HTTPSプロトコルを用いた操作方法について説明します。- [サポートプロトコル]
DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP
- [サポートプロトコル]
- 書式
curl [オプション] [URL] - オプション
curlコマンドには様々なオプションが利用できます。ここでは代表的なオプションを説明します。
オプション (略称) |
オプション (意味) |
内容 |
---|---|---|
-d | --data | リクエストボディーを指定します。 |
-H |
--header |
ヘッダー情報を指定します。 |
-k | --insecure | セキュアーではないSSL接続および通信を実行することを 明示的に許可するためのオプションです。 |
-S | --show-error | エラーメッセージを表示します。 |
-s | --silent | 進捗やエラーメッセージを抑止します。 |
-X |
--request |
HTTPの場合、HTTPサーバーと通信するとき、リクエストメソッドを指定します。 メソッドの種類としては、GET、PUT、DELETE、POSTなどがあります。 |
リクエストURLを指定します。 |
本章で扱うcurlコマンドのメソッド、ヘッダー、ボディー、および操作についての関係は以下のようになります。POSTおよびPUTメソッドを使用する場合は、ボディーにJSON形式のデータを指定する必要があるため、ヘッダーに"Content-Type: application/json" を指定します。
メソッド (-X指定) |
ヘッダー (-H指定) |
ボディー (-d指定) |
操作例 |
---|---|---|---|
-X GET | -H "X-Auth-Token: トークン情報" ※トークン情報:APIを実行する 際に認証処理の代わりとなる情報 |
不要 | 仮想サーバーの一覧情報取得 仮想サーバーの詳細情報取得 |
-X DELETE | -H "X-Auth-Token: トークン情報" | 不要 | 仮想サーバーの削除 |
-X POST | -H "X-Auth-Token: トークン情報" -H "Content-Type: application/json" |
必要 | 仮想サーバーの作成 仮想サーバーの起動・停止 |
-X PUT | -H "X-Auth-Token: トークン情報" -H "Content-Type: application/json" |
必要 | 仮想サーバーの情報更新 |
- URL
APIのリクエストURLは、以下のルールになっています。APIエンドポイント一覧の取得の方法は、後述のエンドポイントの設定を参照してください。リクエストURL = APIエンドポイント一覧で取得したURL + APIリファレンスのURI
APIリファレンスのURIは、各APIの以下の箇所を参照してください。
-
例1)コンピュートの一覧取得(List Servers)のAPIの場合
エンドポイント一覧で取得したcomputeのURLは以下になります。
APIリファレンスに記載されているList ServersのURIは以下になります。https://compute.jp-west-3.cloud.global.fujitsu.com/v2.1/<プロジェクトID>
これらを組み合わせて、APIのURLは以下になります。/servers
https://compute.jp-west-3.cloud.global.fujitsu.com/v2.1/<プロジェクトID>/servers
-
例2)ネットワークの一覧取得(List Networks)のAPIの場合
エンドポイント一覧で取得したnetworkingのURLは以下になります。
APIリファレンスに記載されているList NetworksのURIは以下になります。https://networking.jp-west-3.cloud.global.fujitsu.com
/v2.0/networks
これらを組み合わせて、APIのURLは以下になります。
https://networking.jp-west-3.cloud.global.fujitsu.com/v2.0/networks
リクエストボディーの記載方法#
APIのリクエストボディーはJSON(JavaScript Object Notation)という表記方式で記載します。
リクエストボディーにパラメーター名とパラメーターの値を組み合わせて、以下のように記載します。
{ " パラメーター名 " : " パラメーターの値 " , … , " パラメーター名 " : " パラメーターの値 " }
以下のルールに従って記載してください。
- パラメーター名とパラメーターの値はそれぞれ " (ダブルクォーテーション)で囲みます。
- パラメーター名とパラメーターの値の間は : (コロン)で区切ります。
- パラメーター名とパラメーターの値のセット(メンバーと呼ぶ)の間は , (カンマ)で区切ります。
- 半角スペースや改行は自由に入れることができます。
-
パラメーターの値にメンバーを入れ子にして指定できます。
-
入れ子の例)
{ " user " : { " userid " : " 1900 " , " username " : " fujitsu " , " password " : " secret " , " groups " : [ " admins " , " users " , " maintainers " ] } }
配列の記載方法#
パラメーターの値に配列を使用することもできます。リクエストパラメーターのTypeがarrayの場合は、以下のように値を配列で指定します。
{ " パラメーター名 " : [ " パラメーターの値 " , … , " パラメーターの値 " ] }
パラメーターの値を配列で指定する場合は、以下のルールに従って記載してください。
- 個々のパラメーターの値を " (ダブルクォーテーション)で囲みます。
- パラメーターの値は , (カンマ)で区切ります。
- パラメーターの値の配列全体を [ ] で囲みます。
トークン情報の取得方法#
APIを利用するためには、トークン情報(以降、トークン)を取得することにより、ユーザーの権限に対応した操作が許可されます。
また、トークンには、リージョナルサービスおよびグローバルサービスに合わせた以下の2種類があり、使用するサービスによって使い分けます。詳細については、機能説明書-リージョンを参照してください。
- リージョナルトークン
- グローバルトークン
なお、それぞれのトークンには、トークンが利用可能な有効期限が設定されています。有効期限を過ぎるとトークンが利用できなくなりますので、ご注意ください。有効期限の制限値については、機能説明書-付録の制限値を参照してください。
トークンを取得するために必要な情報を以下の表に示します。
設定項目 | 変数名 | 説明 |
---|---|---|
ドメイン名(契約番号) | DOMAIN_NAME | ポータルログイン時に指定するドメイン名(契約番号) |
プロジェクトID | PROJECT_ID | 操作対象のプロジェクトID IaaSポータルのAPI実行画面(IaaSポータルユーザーズガイド-API実行参照)により、プロジェクトIDを確認できます。 |
ユーザー名 | USER_NAME | ポータルログイン時に指定するユーザー名 |
ユーザーパスワード | USER_PW | ポータルログイン時に指定するパスワード |
リージョンID | REGION_ID | IaaSポータルログイン時に表示されるリージョンの識別情報 下記IaaSポータル画面の"jp-west-3"の箇所がリージョンIDに該当します。 |
トークンを取得するためのシェルスクリプトを作成します。今後の利用を考えて、シェルスクリプトにしておくことをお勧めします。
CentOS上の任意のディレクトリーで、トークン取得用のファイル(例:get_token.sh)を作成します。
$ cd <任意のディレクトリー>
$ vi get_token.sh
URLには、identityのAPIエンドポイントを使用するため、固定の情報としてエンドポイントをあらかじめ設定しています。なお、以下はリージョナルトークンOS_AUTH_TOKENを取得する場合の例です。
以下の内容を記載したシェルスクリプトを作成します。ドメイン名、プロジェクトID、ユーザー名、パスワード、およびリージョンIDについては、あらかじめ確認した情報を設定します。
#!/bin/bash export DOMAIN_NAME=F2aOOXYZ export PROJECT_ID=1234567890abcdefghigklmlopqrstuvwxyz export USER_NAME=fujitsutarou export USER_PW=1234567890qwertyuiop export REGION_ID=jp-west-3 export URL=https://identity.${REGION_ID}.cloud.global.fujitsu.com/v3/auth/tokens FILE_TOKEN=./token.txt curl -X POST -si $URL \ -H "Content-Type: application/json" \ -H "Accept:application/json" \ -d '{"auth":{ "identity":{"methods":["password"],"password": {"user":{"domain":{"name":"'$DOMAIN_NAME'"}, "name": "'$USER_NAME'", "password": "'"$USER_PW"'"}}}, "scope": { "project": {"id": "'$PROJECT_ID'"}}}}' | \ awk '/X-Subject-Token/ {print $2}' | tr -d '\r\n' | tee ${FILE_TOKEN} export OS_AUTH_TOKEN=`cat ${FILE_TOKEN}`
Note
コマンドプロンプトおよびシェルスクリプト内で長い文字列を入力する場合、\(バックスラッシュ)を付けるとその部分の改行が無視されます。
Note
グローバルトークンを取得したい場合は、URL変数を以下のように設定してください。
export URL=https://identity.gls.cloud.global.fujitsu.com/v3/auth/tokens
作成したget_token.shを実行します。ここでは、コマンドの実行形式として、"source ./get_token.sh" または ". ./get_token.sh"で指定可能ですが、省略形の ". ./get_token.sh"の形式で実行しています。
$ . ./get_token.sh gAAAAABb0VD5cq8BWfyO6c4qEZ6iJlbDUgtWbDI6OUDNz3CbaE4cP94sRimbbU4qsXbyoaxz1JvfAJ-Rp7_z-pIT0bDwxdojfcJWW8TwoXYuEWpLyh_g3BLIAJnuUwNlshZ7u5LHL9-qa1qDmsFv87EdtpN6aRH7Mie9LRU0RfewVT2eJqSS478
OS_AUTH_TOKEN変数にトークン情報が記録されていることを確認します。
$ echo $OS_AUTH_TOKEN gAAAAABb0VD5cq8BWfyO6c4qEZ6iJlbDUgtWbDI6OUDNz3CbaE4cP94sRimbbU4qsXbyoaxz1JvfAJ-Rp7_z-pIT0bDwxdojfcJWW8TwoXYuEWpLyh_g3BLIAJnuUwNlshZ7u5LHL9-qa1qDmsFv87EdtpN6aRH7Mie9LRU0RfewVT2eJqSS478
3.エンドポイントの設定#
APIのエンドポイント一覧を取得します。 この例ではリージョナルエンドポイント一覧を取得します。 以下のコマンドを実行してください。 APIの実行方法については後述しますので、この時点ではコマンドをそのまま実行してください。
$ IDENTITY=https://identity.${REGION_ID}.cloud.global.fujitsu.com $ curl -s $IDENTITY/v3/auth/catalog -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq -c '.catalog[]|.endpoints[]|[.name,.url]'
以下のように、リージョナルエンドポイント一覧が表示されます。表示形式は、[ 機能名 , APIエンドポイント一覧で取得したURL ] のようになっています。
["compute","https://compute.jp-west-3.cloud.global.fujitsu.com/v2.1/1234567890abcdefghigklmlopqrstuvwxyz"] ["keymanagement","https://keymanagement.jp-west-3.cloud.global.fujitsu.com"] ["image","https://image.jp-west-3.cloud.global.fujitsu.com"] ["objectstorage","https://objectstorage.jp-west-3.cloud.global.fujitsu.com/v2/AUTH_1234567890abcdefghigklmlopqrstuvwxyz"] ["networking","https://networking.jp-west-3.cloud.global.fujitsu.com"] ["orchestration","https://orchestration.jp-west-3.cloud.global.fujitsu.com/v1/1234567890abcdefghigklmlopqrstuvwxyz"] ["blockstorage","https://blockstorage.jp-west-3.cloud.global.fujitsu.com/v2/1234567890abcdefghigklmlopqrstuvwxyz"] ["database","https://database.jp-west-3.cloud.global.fujitsu.com/v1.0/1234567890abcdefghigklmlopqrstuvwxyz"] ["blockstorage","https://blockstorage.jp-west-3.cloud.global.fujitsu.com/v3/1234567890abcdefghigklmlopqrstuvwxyz"] ["identity","https://identity.jp-west-3.cloud.global.fujitsu.com"] ["compute","https://compute.jp-west-3.cloud.global.fujitsu.com/v2/1234567890abcdefghigklmlopqrstuvwxyz"] ["nfv","https://nfv.jp-west-3.cloud.global.fujitsu.com"] ["bms","https://baremetal.jp-west-3.cloud.global.fujitsu.com"] ["alarm","https://telemetry.jp-west-3.cloud.global.fujitsu.com"] ["software","https://software.jp-west-3.cloud.global.fujitsu.com"] ["autoscale","https://autoscale.jp-west-3.cloud.global.fujitsu.com"] ["identityv3","https://identity.jp-west-3.cloud.global.fujitsu.com/v3"] ["import-export","https://import-export.jp-west-3.cloud.global.fujitsu.com"]
この一覧と前述のURLのルールを元に、使用するAPIのリクエストURLを確認してください。
Note
グローバルエンドポイント一覧を取得する場合は、以下のコマンドを実行してください。
エンドポイントの設定方法は、リージョナルエンドポイントと同様になります。
$ GLOBAL_IDENTITY=https://identity.gls.cloud.global.fujitsu.com $ curl -s $GLOBAL_IDENTITY/v3/auth/catalog -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq -c '.catalog[]|.endpoints[]|[.name,.url]'
4.APIの実行方法#
(1)仮想サーバーの一覧情報取得#
トークン取得時に設定した変数が設定されていることを確認します。
$ echo $DOMAIN_NAME F2aOOXYZ $ echo $PROJECT_ID 1234567890abcdefghigklmlopqrstuvwxyz $ echo $USER_NAME fujitsutarou $ echo $USER_PW 1234567890qwertyuiop $ echo $REGION_ID jp-west-3
URLとして、computeのAPIエンドポイントを設定しますが、REGION_IDやPROJECT_IDをそのまま流用できるように、以下のように設定します。ここでは、APIの命令部分であるURI部分は後で変更が入る部分となるため、URL変数に含めないようにしておきます。
$ export URL_COMPUTE=https://compute.${REGION_ID}.cloud.global.fujitsu.com/v2.1/${PROJECT_ID} $ echo $URL_COMPUTE https://compute.jp-west-3.cloud.global.fujitsu.com/v2.1/1234567890abcdefghigklmlopqrstuvwxyz
APIリファレンスを確認し、仮想サーバーの一覧情報を取得するAPIを確認します。
curlコマンドに必要なパラメーターを以下のように設定します。
- URI :/servers
- メソッド: -X GET
- リクエストヘッダー:-H "X-Auth-Token: $OS_AUTH_TOKEN"
- リクエストボディー:なし
URLには、すでに定義したURL_COMPUTE変数にURIを足したものを使用します。仮想サーバーの一覧情報を取得するAPIの例を以下に示します。
$ curl -Ss ${URL_COMPUTE}/servers -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq .
{ "servers": [ { "id": "13c4b868-3809-4e2c-9340-d5c8c5963612", "links": [ { "href": "https://compute.jp-west-3.cloud.global.fujitsu.com/v2.1/1234567890abcdefghigklmlopqrstuvwxyz/servers/13c4b868-3809-4e2c-9340-d5c8c5963612", "rel": "self" }, { "href": "https://compute.jp-west-3.cloud.global.fujitsu.com/1234567890abcdefghigklmlopqrstuvwxyz/servers/13c4b868-3809-4e2c-9340-d5c8c5963612", "rel": "bookmark" } ], "name": "centos_V1" }, (省略)
特定のキー情報に絞って情報を表示したい場合は、以下のように指定できます。ここでは、servers情報の中にあるnameキーとidキーを指定しています。
$ curl -Ss ${URL_COMPUTE}/servers -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.servers[] | {"name":.name, "id":.id}'
{ "name": "centos_V1", ※以降の説明では、"centos_V1"を操作対象に扱います。 "id": "13c4b868-3809-4e2c-9340-d5c8c5963612" } { "name": "centos_API2", "id": "d2fd64eb-995e-426d-a7ae-4739e90b7091" } { "name": "centos-old", "id": "d2238f1d-5075-451f-b54a-4afa528b5132" }
(2)仮想サーバーの状態確認#
取得したサーバー一覧のうち、ここでは仮想サーバー名"centos_V1"を操作対象にします。APIではIDを元に操作するため、仮想サーバーIDをSERVER_IDとして設定しておきます。
$ export SERVER_ID=13c4b868-3809-4e2c-9340-d5c8c5963612
APIリファレンスから、仮想サーバーの詳細を表示するAPIを確認します。
上記より、メソッドおよびURIは以下のようになります。
- URI: /servers/${SERVER_ID} ※すでに定義したSERVER_IDを利用します。
- メソッド: -X GET
- リクエストヘッダー:-H "X-Auth-Token: $OS_AUTH_TOKEN"
- リクエストボディー:なし
$ export SERVER_ID=13c4b868-3809-4e2c-9340-d5c8c5963612
仮想サーバーの詳細情報を取得するAPIを以下のように実行します。
$ curl -Ss ${URL_COMPUTE}/servers/${SERVER_ID} -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq .
{ "server": { "OS-EXT-STS:task_state": null, "addresses": { "ssl-vpn-network": [ { "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:d5:ad:dd", "version": 4, "addr": "192.168.0.7", "OS-EXT-IPS:type": "fixed" } ] }, "links": [ { "href": "https://compute.jp-west-3.cloud.global.fujitsu.com/v2.1/1234567890abcdefghigklmlopqrstuvwxyz/servers/13c4b868-3809-4e2c-9340-d5c8c5963612", "rel": "self" }, { "href": "https://compute.jp-west-3.cloud.global.fujitsu.com/1234567890abcdefghigklmlopqrstuvwxyz/servers/13c4b868-3809-4e2c-9340-d5c8c5963612", "rel": "bookmark" } ], "image": "", "OS-EXT-STS:vm_state": "active", "OS-EXT-SRV-ATTR:instance_name": "inst-0000b787", "OS-SRV-USG:launched_at": "2018-10-25T01:47:05.000000", "flavor": { "id": "1346eb39-10ef-405d-bef6-f451fe3b12d1", "links": [ { "href": "https://compute.jp-west-3.cloud.global.fujitsu.com/1234567890abcdefghigklmlopqrstuvwxyz/flavors/1346eb39-10ef-405d-bef6-f451fe3b12d1", "rel": "bookmark" } ] }, "id": "13c4b868-3809-4e2c-9340-d5c8c5963612", "security_groups": [ { "name": "ssl-vpn-SG" } ], "user_id": "1a737cf857f9497cbb7a4e903c9be38d", "OS-DCF:diskConfig": "MANUAL", "accessIPv4": "", "accessIPv6": "", "progress": 0, "OS-EXT-STS:power_state": 1, "OS-EXT-AZ:availability_zone": "jp-west-3a", "metadata": {}, "status": "ACTIVE", "updated": "2018-10-25T01:47:05Z", "hostId": "098d035ce24ab4defbe355b267cc9ba579520c60f4dcb69ec0a27cda", "OS-EXT-SRV-ATTR:host": "sv-01-01-11-03.management.jp-west-3.local", "OS-SRV-USG:terminated_at": null, "key_name": "test-keypair", "OS-EXT-SRV-ATTR:hypervisor_hostname": "sv-01-01-11-03.management.jp-west-3.local", "name": "centos_V1", "created": "2018-10-25T01:46:53Z", "tenant_id": "1234567890abcdefghigklmlopqrstuvwxyz", "os-extended-volumes:volumes_attached": [ { "id": "067438e8-3760-4b32-ad2c-e24fa773dba6" } ], "config_drive": "" } }
name、id、statusキーに絞って表示する場合は、以下のように指定します。
$ curl -Ss ${URL_COMPUTE}/servers/${SERVER_ID} -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.server | {"name": .name, "id": .id, "status": .status}'
{ "name": "centos_V1", "id": "13c4b868-3809-4e2c-9340-d5c8c5963612", "status": "ACTIVE" }
(3)仮想サーバーの停止#
仮想サーバーの状態を確認し、仮想サーバーを停止します。APIリファレンスから仮想サーバーを停止するAPIを確認します。
上記より、必要なパラメーターを以下のように設定します。
- URI: /servers/${SERVER_ID}/action
- メソッド: -X POST
- リクエストヘッダー: -H "X-Auth-Token: $OS_AUTH_TOKEN" -H "Content-Type: application/json"
- リクエストボディー:-d '{"os-stop": null}'
操作対象の仮想サーバーの状態を確認します。
$ curl -Ss ${URL_COMPUTE}/servers/${SERVER_ID} -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.server | {"name": .name, "id": .id, "status": .status}'
仮想サーバーが起動状態(ACTIVE)になっていることが確認できます。
{ "name": "centos_V1", "id": "13c4b868-3809-4e2c-9340-d5c8c5963612", "status": "ACTIVE" }
起動状態の仮想サーバーに対して、仮想サーバーの停止APIを実行します。
$ curl -Ss ${URL_COMPUTE}/servers/${SERVER_ID}/action -X POST -H "X-Auth-Token: $OS_AUTH_TOKEN" -H "Content-Type: application/json" -d '{"os-stop" : null }' | jq .
再度仮想サーバーの状態を確認します。
$ curl -Ss ${URL_COMPUTE}/servers/${SERVER_ID} -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.server | {"name": .name, "id": .id, "status": .status}'
仮想サーバーが停止状態(SHUTOFF)になっていることが確認できます。
{ "name": "centos_V1", "id": "13c4b868-3809-4e2c-9340-d5c8c5963612", "status": "SHUTOFF" }
(4)仮想サーバーの起動#
仮想サーバーの状態を確認し、仮想サーバーを起動します。APIリファレンスから仮想サーバーを起動するAPIを確認します。curlコマンドに指定するパラメーターは以下のようになります。
- URI: /servers/${SERVER_ID}/action
- メソッド: -X POST
- リクエストヘッダー:-H "X-Auth-Token: $OS_AUTH_TOKEN" -H "Content-Type: application/json"
- リクエストボディー:-d '{"os-start": null}'
仮想サーバーの状態を確認します。
$ curl -Ss ${URL_COMPUTE}/servers/${SERVER_ID} -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.server | {"name": .name, "id": .id, "status": .status}'
仮想サーバーが停止状態(SHUTOFF)になっていることが確認できます。
{ "name": "centos_V1", "id": "13c4b868-3809-4e2c-9340-d5c8c5963612", "status": "SHUTOFF" }
停止状態の仮想サーバーに対して、仮想サーバーの起動APIを実行します。
$ curl -Ss ${URL_COMPUTE}/servers/${SERVER_ID}/action -X POST -H "X-Auth-Token: $OS_AUTH_TOKEN" -H "Content-Type: application/json" -d '{"os-start" : null }' | jq .
仮想サーバーの状態を確認します。
$ curl -Ss ${URL_COMPUTE}/servers/${SERVER_ID} -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.server | {"name": .name, "id": .id, "status": .status}'
仮想サーバーが起動状態(ACTIVE)になっていることが確認できます。
{ "name": "centos_V1", "id": "13c4b868-3809-4e2c-9340-d5c8c5963612", "status": "ACTIVE" }
(5)仮想サーバーの削除#
APIリファレンスより仮想サーバーを削除するAPIを確認します。
curlコマンドに必要なパラメーターを以下のように設定します。
- URI: /servers/${SERVER_ID}
- メソッド: -X DELETE
- リクエストヘッダー:-H "X-Auth-Token: $OS_AUTH_TOKEN"
- リクエストボディー: なし
対象の仮想サーバーIDを確認します。
$ echo $SERVER_ID 13c4b868-3809-4e2c-9340-d5c8c5963612
仮想サーバーを削除するAPIを実行します。
$ curl -Ss ${URL_COMPUTE}/servers/${SERVER_ID} -X DELETE -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq .
SERVER_ID変数で設定したIDが存在しないことを確認します。
$ curl -Ss ${URL_COMPUTE}/servers -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.servers[] | {"name": .name, "id": .id}'
{ "name": "centos_API2", "id": "d2fd64eb-995e-426d-a7ae-4739e90b7091" } { "name": "centos-old", "id": "d2238f1d-5075-451f-b54a-4afa528b5132" }
対象の仮想サーバーIDが存在しないため、仮想サーバーが正常に削除されたことが確認できます。
(6)仮想サーバーの作成#
APIリファレンスより仮想サーバーを作成するAPIを確認します。
APIリファレンスのリクエストパラメーターから、API実行に必要なパラメーターを確認します。ここでは、仮想サーバー名を"centos_API"、仮想マシンタイプを"P3-1"、イメージに"CentOS 7 64bit"、配備するネットワークを"ssl-vpn"、セキュリティグループに"ssl-vpn-SG"を割り当てるものとします。
パラメーターについては、以下の表を参考にしてください。
名前 | 説明 | ||
---|---|---|---|
server | name | 仮想サーバーの名前として、"centos_API" を指定します。 | |
flavorRef | フレーバのID を指定します(※)。 本ガイドでは、"P3-1"タイプのフレーバIDを指定します。 |
||
block_device_mapping_v2 | boot_index | ブートインデックスには、"0 "を指定します。 | |
uuid | イメージのIDを指定します(※)。 本ガイドでは、"CentOS 7 64bit"のイメージIDを指定します。 |
||
volume_size | "30"(GB)を指定します。 | ||
device_name | "/dev/vda"を指定します。 | ||
source_type | "image"を指定します。 | ||
destination_type | "volume"を指定します。 | ||
key_name | すでに作成しているキーペア名を指定します。 | ||
networks | uuid | ネットワークのIDを指定します(※)。 本ガイドでは、"ssl-vpn"のネットワークのIDを指定します。 |
|
security_groups | name | セキュリティグループの名前を指定します(※)。 本ガイドでは、"ssl-vpn-SG"に対応する名前を指定します。 |
(※)上記のフレーバのID、イメージのID、ネットワークのID、セキュリティグループのIDについては、APIを使用して各IDを確認する必要があります。
以下に取得方法を説明します。
1.フレーバIDの取得#
フレーバーの一覧を取得するAPIをAPIリファレンスから確認します。
上記よりURLを設定し、フレーバー一覧を取得します。
$ export URL_COMPUTE=https://compute.$REGION_ID.cloud.global.fujitsu.com/v2.1/$PROJECT_ID $ curl -Ss $URL_COMPUTE/flavors -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.flavors[] | {"name": .name, "id": .id}'
P3-1に対応するIDを確認します。
{ "name": "M3-4", "id": "00f26551-ef1c-49a6-9725-b885c31d4d25" } { "name": "S3-8", "id": "13246307-6b41-47a1-aaf2-a985398c1722" } { "name": "P3-1", "id": "1346eb39-10ef-405d-bef6-f451fe3b12d1" } (省略)
P3-1のフレーバIDをFLAVOR_ID変数として設定します。
$ export FLAVOR_ID=1346eb39-10ef-405d-bef6-f451fe3b12d1
2.イメージのIDの取得#
イメージの一覧を取得するAPIをAPIリファレンスから確認します。
上記よりURLを設定し、イメージ一覧を取得します。
イメージは多いため、Selectを使用してCentOSに絞って表示します。
$ export URL_IMAGE=https://image.jp-west-3.cloud.global.fujitsu.com $ curl $URL_IMAGE/v2/images?limit=200 -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.images[] | select(.name | contains("CentOS")) | {"name": .name, "id":.id}'
"CentOS 7.9 64bit (English) 01"に対応するIDを確認します。
{ "name": "CentOS 8.3 64bit (English) 01", "id": "0376b898-03ec-4f52-93af-8be413bcbe6a" } { "name": "CentOS 7.9 64bit (English) 01", "id": "289c1ce0-51fb-4a3b-adad-fb2ef2deb15a" } { "name": "CentOS Linux 7.7 64bit for Baremetal", "id": "ef26d2b4-bbdb-46b4-bc17-1213a40862f8" }
CentOS 7のイメージIDをIMAGE_ID変数として設定します。
$ export IMAGE_ID=289c1ce0-51fb-4a3b-adad-fb2ef2deb15a
3.ネットワーク一覧情報の取得#
ネットワークの一覧を取得するAPIをAPIリファレンスから確認します。
上記よりURLを設定し、ネットワーク一覧を取得します。
$ export URL_NW=https://networking.jp-west-3.cloud.global.fujitsu.com $ curl -Ss $URL_NW/v2.0/networks -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.networks[] | {"name": .name, "id": .id}'
ネットワーク一覧を取得し、"ssl-vpn-network"に対応するIDを確認します。
{ "name": "ssl-vpn-network", "id": "478043e0-74c2-48b7-baf4-fc8a79c17c57" } { "name": "fip-net", "id": "5234aa88-9cd8-49bd-b613-d0006eacb87b" }
ネットワークのIDをNETWORK_ID変数として設定します。
$ export NETWORK_ID=478043e0-74c2-48b7-baf4-fc8a79c17c57
4. セキュリティグループ名の取得#
セキュリティグループの一覧を取得するAPIをAPIリファレンスから確認します。
先ほど設定したURLを使用して、ネットワーク一覧を取得します。
$ curl -Ss $URL_NW/v2.0/security-groups -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.security_groups[] | {"name": .name, "id": .id}'
セキュリティグループ名に"ssl-vpn-SG"があることを確認します。
{ "name": "ssl-vpn-SG", "id": "0e3c0936-bf88-406d-82fb-0d26a0b12ee0" } { "name": "default", "id": "9290fea4-56fc-4030-9d37-03d3c8222e1b" }
セキュリティグループ名をSG_NAME変数として設定します。
$ export SG_NAME=ssl-vpn-SG
5. その他のパラメーター設定#
仮想サーバー名(VM_NAME)、ボリュームサイズ(VOL_SIZE)、デバイス名(DEVICE_NAME)、ボリュームのソースタイプ(SOURCE)、キーペア名(KEYNAME)についても、それぞれ以下のように設定します。
$ export VM_NAME=centos_API $ export VOL_SIZE=30 $ export DEVICE_NAME=/dev/vda $ export SOURCE=image $ export KEYNAME=test-keypair
すべて必要なパラメーターが設定されていることを確認してください。
$ echo $VM_NAME $ echo $FLAVOR_ID $ echo $IMAGE_ID $ echo $VOL_SIZE $ echo $DEVICE_NAME $ echo $SOURCE $ echo $KEYNAME $ echo $NETWORK $ echo $SG_NAME
curlコマンドに必要なパラメーターを決定します。
- URI: /servers/${SERVER_ID}
- メソッド: -X POST
- リクエストヘッダー:
-H "X-Auth-Token: $OS_AUTH_TOKEN" -H "Content-Type: application/json"
- リクエストボディー:
上記のようなJSON形式をリクエストボディーに指定することは難しいため、次に示すようなヒアドキュメントを用いた形式で実行する、またはシェルスクリプトにJSON形式でリクエストボディーを指定することをお勧めします。-d {"server": {"name": "$VM_NAME", "flavorRef": "$FLAVOR_ID" , "block_device_mapping_v2":[ {"boot_index": "0", "uuid":"$IMAGE_ID", "volume_size": "$VOL_SIZE", "device_name": "$DEVICE_NAME", "source_type": "$SOURCE", "destination_type": "volume"} ] , "key_name": "$KEYNAME", "networks": [{"uuid": "$NETWORK_ID"}], "security_groups": [{"name": "$SG_NAME"}] }}
仮想サーバーを作成するAPIを以下のとおりに実行します。
ここでは、シェルスクリプトに文字列をそのまま読み込ませる方法(ヒアドキュメント)を用いることにより、"@- <<EOF"から"EOF"までの内容をJSON形式のまま指定しています。
※ヒアドキュメントでは、シングルクォート(’)を用いると正しく動作しないためご注意ください。
※以下は実行例の画面イメージです。
出力結果は以下のようになります。
{"server": {"security_groups": [{"name": "0e3c0936-bf88-406d-82fb-0d26a0b12ee0"}], "OS-DCF:diskConfig": "MANUAL", "id": "1c84de54-78a3-48c0-bdd6-654abafc2d6f", "links": [{"href": "https://compute.jp-west-3.cloud.global.fujitsu.com/v2.1/1234567890abcdefghigklmlopqrstuvwxyz/servers/1c84de54-78a3-48c0-bdd6-654abafc2d6f", "rel": "self"}, {"href": "https://compute.jp-west-3.cloud.global.fujitsu.com/1234567890abcdefghigklmlopqrstuvwxyz/servers/1c84de54-78a3-48c0-bdd6-654abafc2d6f", "rel": "bookmark"}], "adminPass": "gnSgE2mGw3Bn"}}
仮想サーバーの一覧情報を取得します。ここでは、jqコマンドを使用して、確認に必要な情報(name, id, status)のみ抽出しています。
$ curl -Ss ${URL_COMPUTE}/servers/detail -X GET \ >-H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.servers[] | {name:.name, id:.id, status: .status}'
出力内容に"centos_API"が作成されていれば、正常に仮想サーバーが作成されていることを確認できます。なお、仮想サーバー作成後は、自動的に仮想サーバーが起動状態(ACTIVE)になっていますのでご注意ください。
{ "name": "centos_API", "id": "1c84de54-78a3-48c0-bdd6-654abafc2d6f", "status": "ACTIVE" } (省略)
(7)仮想サーバーの情報更新#
作成した仮想サーバーを更新します。本手順では、仮想サーバー名を更新する方法を説明します。
curlコマンドに必要なパラメーターを以下のように設定します。
- URI: /servers/${SERVER_ID} ※仮想サーバーIDは今回操作対象の仮想サーバーを指定します。
- メソッド: -X PUT
- リクエストヘッダー: -H "X-Auth-Token: $OS_AUTH_TOKEN" -H "Content-Type: application/json"
- リクエストボディー:-d '{"server": {"name": "centos_update" }}'
仮想サーバーの情報を更新するAPIを以下のように実行します。
※ "-d" 指定には、'{ xxxx }' の形式で指定してください。
※ヒアドキュメントを利用する場合は、-d { xxxx } の形式に変更する必要がありますのでご注意ください。
$ curl -Ss ${URL_COMPUTE}/servers/${SERVER_ID} -X PUT -H "X-Auth-Token: $OS_AUTH_TOKEN" -H "Content-Type: application/json" -d '{"server": {"name": "centos_update" }}' | jq .
name部分の値が "centos_update"になっていることを確認します。
{ "server": { "status": "ACTIVE", "updated": "2018-11-06T09:38:31Z", "hostId": "216321eb3c71b5f95ac101bed3dcf0ed4af24417c83e73444336879f", "user_id": "1a737cf857f9497cbb7a4e903c9be38d", "name": "centos_update", "links": [ { "href": "https://compute.jp-west-3.cloud.global.fujitsu.com/v2.1/1234567890abcdefghigklmlopqrstuvwxyz/servers/1c84de54-78a3-48c0-bdd6-654abafc2d6f", "rel": "self" }, { "href": "https://compute.jp-west-3.cloud.global.fujitsu.com/1234567890abcdefghigklmlopqrstuvwxyz/servers/1c84de54-78a3-48c0-bdd6-654abafc2d6f", "rel": "bookmark" } ], (省略)
Note
ヒアドキュメントを用いたコマンド実行例は、以下となります。
$ curl -Ss ${URL_COMPUTE}/servers/${SERVER_ID} -X PUT \ -H "X-Auth-Token: $OS_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d @- <<EOF { "server": { "name": "centos_update" } } EOF
nameおよびidキーのみを表示する場合は、以下のように実行します。
$ curl -Ss ${URL_COMPUTE}/servers -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" | jq '.servers[] | {name: .name, id: .id}'
出力結果は以下のようになります。
{ "name": "centos_update", "id": "1c84de54-78a3-48c0-bdd6-654abafc2d6f" } (省略)
本ガイドでは、仮想サーバーを中心にAPIの利用方法を説明しました。このほかにネットワークなどのリソースを扱う場合は、APIリファレンスを参照し、本書で記載した操作方法を参考にお試しください。