ホストメンテナンス取得API

[更新日:2024年5月23日]

1.概要

さくらのクラウドで提供している「さくらのクラウドAPI」では、アカウントが利用中のサーバ/アプライアンスが収容されるホストサーバのメンテナンス予定一覧を取得することが可能です。

※さくらのクラウドAPIの利用方法など、一般的な情報については APIドキュメント を参照ください。

API URL

APIを利用する際のベースURLは以下のものを使用します。

https://secure.sakura.ad.jp/cloud/api/global/1.0/maintenances

注意事項

APIを実行するためには、APIキーに「リソース閲覧」以上のアクセスレベルが必要になります。
詳細は、 アクセスレベルのページ をご覧ください。

2.使用例

APIキーの作成

APIキーの発行方法は APIキー をご覧ください。

メンテナンス情報の取得

手順内で使用するパラメータは以下の通りです。

パラメータ 説明 省略時のデフォルト値
アクセストークン 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

注意事項

API経由で取得できるホストメンテナンスの情報は、全てのメンテナンスまたはAPIキーで指定したアカウントのリソースが含まれるメンテナンスのみとなります。
会員IDでの絞り込みはできませんのでご注意ください。