年末だしChange Calendarについて書く

はじめに

年末といえばカレンダーだよなという安直な考えが頭をよぎりました。
せっかくなのでAWS Systems ManagerのChange Calendarについて記事を書きます。

Change Calendarは、スケジュールに基づいてシステムの動作を制御できるサービスです。
本記事では、CalendarについてStateという概念を中心に解説します。

Calendarの基本

Stateの管理

Calendarは、スケジュールを定義してOPENとCLOSEDの2つのStateを管理するリソースです。

Stateの実例

上記画像は2025年の日本の祝日を定義したCalendarの一部です。
9月15日の敬老の日が定義されています。

CalendarのTypeを見ると、DEFAULT_OPENであることが分かります。
つまり、このCalendarで特に定義されていない時間帯はOPENというStateで、定義したイベント(敬老の日)の時間帯(0:00～23:59)はCLOSEDというStateになります。

このようにCalendarはイベントの有無でOPENとCLOSEDという2つの状態を管理しています。

※CalendarがDEFAULT_CLOSEDの場合は評価が逆転し、イベント時がOPEN、イベント以外がCLOSEDになります。

Calendarでできること

API経由でのState確認

特に何のイベントも定義していないDEFAULT_OPENのCalendarを用意しました。
現在の日付は12月18日です。
CalendarのStateは以下のコマンドで確認可能です。

aws ssm get-calendar-state --calendar-names <CalendarName>

実際の実行結果は以下の通りです。

~ $ aws ssm get-calendar-state --calendar-names calendar-template-stack-TestCalendar-NitvHCFau1np
{
    "State": "OPEN",
    "AtTime": "2025-12-18T08:13:34Z"
}

12月18日にイベントを追加してみます。

再度Stateを確認するコマンドを実行するとStateがCLOSEDに変更されました。

~ $ aws ssm get-calendar-state --calendar-names calendar-template-stack-TestCalendar-NitvHCFau1np
{
    "State": "CLOSED",
    "AtTime": "2025-12-18T08:18:56Z",
    "NextTransitionTime": "2025-12-18T14:59:59Z"
}

複数のCalendarへの問い合わせ

Stateを問い合わせるAPIは、一度の実行で複数(最大10個)のCalendarに対しての問い合わせが可能です。
例えば、祝日Calendarと本日(12月18日)をイベントとして定義したCalendarの2つに対して問い合わせてみます。

祝日Calendarへの問い合わせ結果はOPENです。

~ $ aws ssm get-calendar-state --calendar-names calendar-template-stack-JapaneseHolidayCalendar-VyPJ2R59q4Gs
{
    "State": "OPEN",
    "AtTime": "2025-12-18T08:28:57Z"
}

本日をイベントとしたCalendarへの問い合わせ結果はCLOSEDです。

~ $ aws ssm get-calendar-state --calendar-names calendar-template-stack-TestCalendar-NitvHCFau1np
{
    "State": "CLOSED",
    "AtTime": "2025-12-18T08:30:11Z",
    "NextTransitionTime": "2025-12-18T14:59:59Z"
}

この時両方のCalendarを対象にStateを確認するとCLOSEDになります。

~ $ aws ssm get-calendar-state --calendar-names calendar-template-stack-TestCalendar-NitvHCFau1np calendar-template-stack-JapaneseHolidayCalendar-VyPJ2R59q4Gs
{
    "State": "CLOSED",
    "AtTime": "2025-12-18T08:31:33Z",
    "NextTransitionTime": "2025-12-18T14:59:59Z"
}

複数のCalendarに問い合わせた際の挙動について公式ドキュメントを確認すると、以下の記述があります。

1 つの要求に複数のCalendarを指定すると、要求内のすべてのCalendarが開いている場合にのみ、コマンドは OPEN のステータスを返します。要求内の 1 つ以上のCalendarが閉じている場合、返されるステータスは CLOSED です。

つまり複数のCalendarのうち一つでもCLOSEDがあればレスポンスはCLOSEDになります。

複数Calendar設計の考察

複数のCalendarに同時問い合わせができる機能が提供されていることから、AWSはCalendarの責任範囲を明確に分離する設計を推奨していると推測されます。

単一責任の原則

• 各Calendarは1つの明確な責任を持つことが望ましい
• 例：祝日Calendar、営業時間Calendar、メンテナンスCalendar

再利用性の向上

• 祝日Calendarは複数のシステムで共有できる
• 営業時間Calendarは部署ごとに異なる設定ができる

管理の容易性

• 祝日の更新は祝日Calendarのみを変更すればよい
• 営業時間の変更は営業時間Calendarのみを変更すればよい
• 変更の影響範囲が明確になる

柔軟な組み合わせ

• システムAは「祝日 + 営業時間」の組み合わせ
• システムBは「祝日 + メンテナンス」の組み合わせ
• 必要な条件を自由に組み合わせて使用できる

このような設計により、複雑な条件を1つのCalendarに詰め込むのではなく、シンプルなCalendarを組み合わせて使うのがよさそうです。

State確認のユースケース

CalendarのStateを確認することで、時間帯に応じた処理の制御が可能になります。

Lambda関数での処理制御

以下のような処理フローで、Calendarの状態に応じて処理を実行するかスキップするかを制御できます。

1. Lambda関数が起動
2. get-calendar-state APIでCalendarの状態を確認
3. Stateが**OPEN**の場合
   → 処理を実行
4. Stateが**CLOSED**の場合
   → 処理をスキップ

例：祝日Calendarを使用した場合

• 平日：State = OPEN → バッチ処理を実行
• 祝日：State = CLOSED → バッチ処理をスキップ

複数Calendarを使った高度な制御

複数のCalendarを組み合わせることで、より複雑な条件での制御が可能です。

1. 処理開始前に複数のCalendarに問い合わせ
2. すべてのCalendarが**OPEN**の場合のみ
   → 処理を実行
3. いずれか1つでも**CLOSED**の場合
   → 処理をスキップ

例：祝日Calendar + 営業時間Calendar

• 平日の営業時間内：両方OPEN → 処理実行
• 祝日または営業時間外：いずれかCLOSED → 処理スキップ

さいごに

今回はAPI経由でStateを問い合わせ、処理フローに利用するという観点でCalendarの記事を書きました。
問い合わせる以外にも、Stateが切り替わる瞬間(CLOSED→OPEN、OPEN→CLOSED)を検知して、何らかの処理のトリガーとする使い方もあります。
機会があれば、後者の利用方法についても記事を書くつもりです。

参考資料

• AWS Systems Manager Change Calendar 公式ドキュメント
• GetCalendarState API リファレンス