ホストメンテナンス取得API¶
[更新日：2024年1月12日]
1．概要¶
さくらのクラウドで提供している「さくらのクラウドAPI」では、アカウントが利用中のサーバ/アプライアンスが収容されるホストサーバのメンテナンス予定一覧を取得することが可能です。
※さくらのクラウドAPIの利用方法など、一般的な情報については APIドキュメント を参照ください。
API URL¶
APIを利用する際のベースURLは以下のものを使用します。
https://secure.sakura.ad.jp/cloud/api/global/1.0/maintenances
注意事項¶
APIを実行するためには、APIキーに「リソース閲覧」以上のアクセスレベルが必要になります。
詳細は、 アクセスレベルのページ をご覧ください。
2．使用例¶
メンテナンス情報の取得¶
手順内で使用するパラメータは以下の通りです。
| パラメータ | 説明 | 省略時のデフォルト値 |
|---|---|---|
| アクセストークン | APIキーのアクセストークンです。 例：ACCESS_TOKEN と表示しています。 |
省略不可 |
| アクセストークンシークレット | APIキーのアクセストークンシークレットです。 例：ACCESS_TOKEN_SECRET と表示しています |
省略不可 |
| start_at | 取得する期間の開始日を指定します。 例：YYYY-MM-DD と表示しています |
API実行日 |
| end_at | 取得する期間の終了日を指定します。 例：YYYY-MM-DD と表示しています |
API実行日の1か月後 ※2023年11月20日に実行した場合、「2023-12-20」となります。 |
| search_type | アカウントが利用中のリソースが含まれるメンテナンスを取得対象とする場合に 「related」を指定します。 |
all |
| page_count | 1ページに出力する件数を指定します。 | 20 |
以下のコマンド例では、API実行日から1か月間の間に予定されている全てのホストメンテナンスを取得します。
※「page_count」を指定していないため、表示件数は最大20件となります。
$ curl --user 'ACCESS_TOKEN:ACCESS_TOKEN_SECRET' 'https://secure.sakura.ad.jp/cloud/api/global/1.0/maintenances' | jq .
APIサーバからのレスポンスは以下のようになります。
{
"is_ok": true,
"meta": {
"total_pages": 1,
"total_count": 1
},
"maintenances": [
{
"maintenance_id": "XXX",
"zone": "is1a",
"start_at": "YYYY-MM-DD hh:mm:ss",
"end_at": "YYYY-MM-DD hh:mm:ss",
"title": "MM/DD さくらのクラウド(一部のホストサーバ)でメンテナンスを実施します",
"info_url": "http://support.sakura.ad.jp/mainte/mainteentry.php?id=XXXXX",
"service": "IaaS",
"accounts": []
}
]
}
以下のコマンド例では、「2023年12月1日」から「2023年12月31日」までの間に予定されている、アカウントが利用中のリソースが含まれるメンテナンスを取得します。
$ curl --user 'ACCESS_TOKEN:ACCESS_TOKEN_SECRET' 'https://secure.sakura.ad.jp/cloud/api/global/1.0/maintenances' \
--get \
--data-urlencode '{
"Filter": {
"start_at": "2023-12-01",
"end_at": "2023-12-31",
"search_type": "related",
"page_count": 100
}
}' | jq .
APIサーバからのレスポンスは以下のようになります。
{
"is_ok": true,
"meta": {
"total_pages": 1,
"total_count": 1
},
"maintenances": [
{
"maintenance_id": "XXX",
"zone": "is1a",
"start_at": "2023-12-13 13:00:00",
"end_at": "2023-12-13 18:00:00",
"title": "12/13 さくらのクラウド(一部のホストサーバ)でメンテナンスを実施します",
"info_url": "http://support.sakura.ad.jp/mainte/mainteentry.php?id=XXXX",
"service": "IaaS",
"accounts": [
{
"account_id": "xxxxxxxxxxxx",
"account_name": "xxxxxxxxxx",
"account_code": "xxxxxxxxxx",
"resources": [
{
"resource_class": "server",
"resource_id": "xxxxxxxxxxxx"
},
{
"resource_class": "appliance",
"resource_id": "xxxxxxxxxxxx"
}
]
}
]
}
]
}
レスポンスに含まれる主なキーの内容は以下の通りです。
| キー名 | 説明 |
|---|---|
| zone | メンテナンスの対象ゾーン |
| start_at | メンテナンス開始日時 |
| end_at | メンテナンス終了日時 |
| title | メンテナンス情報 |
| info_url | メンテナンスのお知らせへのリンクURL |
| resource_class | 対象リソースの種類 |
| resource_id | 対象リソースのリソースID |