SaaSの設定管理台帳をNotion Workersで作る

こんにちは、ともしゅうです。CloudNativeで情シスの運用支援をしています。

前回の記事「SaaS設定、どこを正本にする？管理方式の選び方」で紹介した、SaaSの設定を読み取って台帳に反映する「観測型」を、Notion Workersで試しました。今回の題材はGoogle Workspaceです。設定値を台帳へ同期し、変更したときと元に戻したときの履歴を残せることを確認できました。グループ総数の増減では、変更履歴と作業申請を結びつけ、予定した作業との対応も確かめています。

この記事の3行まとめ

• ユーザー単位の設定値を台帳へ同期し、オン・オフの変更と元に戻した際の履歴を記録できました。
• グループ総数の例では、変更履歴を作業申請と結びつけ、予定した作業との対応を人が確認しました。
• 記録先を選ぶ判断軸は、台帳を使う人、記録の目的、費用と保守の負担です。

現在値と変更履歴と申請を分ける

Notion Workersは、外部サービスから情報を取得するなどの処理を、Notionの環境でコードとして実行する仕組みです。今回は、取得したデータをNotionのデータベースへ反映する「Syncs」を利用し、現在値を更新する処理と、前回取得時からの差分を履歴に残す処理を組み合わせました。

Workers全体の機能と使い方はNotion AIマスターコースで紹介しています。Syncsの同期方式やデータベースの定義方法は、Notion公式のSyncsガイドを参照できます。

データはGoogle WorkspaceのAdmin SDKから取得しました。Google Workspaceが正本で、Notionに保存するのは取得時点の写しです。

Notion側のDBは、現在値台帳・変更履歴・作業申請の3つの役割に分けました。

同期対象は、ドメイン情報と集計値の8項目、それにユーザー単位の「アドレス帳への表示」という設定値1項目です。設定値には専用の現在値DBと変更履歴DBを用意しました。グループ総数の変更履歴には、対象の台帳行と作業申請へのリレーションも設定しています。

こうすると、取得した状態を台帳で確認し、変化があれば変更履歴と申請を見比べられます。値を転記し直す手間を減らしながら、変更に対応する作業を確認できる構成です。設定変更はGoogle Workspace側で行い、Notionからの書き戻しはありません。

この実装例では、Google Workspaceの検証環境を使い、手動で同期を実行しました。

同期に必要な環境と権限

同期の権限は、確認したい項目の取得に必要な範囲へ絞ります。最初の集計値の同期処理は、Notion AIに依頼して作成しました。

連携には、Google側でのAPIアクセスの許可と、Notion側での認証情報・同期先の設定が必要です。管理画面へのログイン権限とは別に、WorkerがAPIを使うための許可も用意しておきます。

今回はユーザー・グループ・顧客情報の読み取り専用権限を使いました。設定値の取得にも既存のユーザー情報の読み取り権限を使えたため、追加の権限は不要でした。保存する情報は、確認したい値と対象を識別するID、取得日時などに絞っています。

具体的な設定方法は、次の公式ガイドを参照してください。今回の台帳をそのまま作る手順ではありませんが、認証と同期の準備を確認できます。

• Google：認証情報の作成（Google側で連携用の認証情報を用意する手順）
• Notion：WorkersのOAuth設定（外部サービスへの接続を認可する手順）
• Notion：Syncsの設定（取得した情報をデータベースへ同期する仕組みと設定例）

SaaSの情報を台帳に同期する

台帳では同じ設定IDの行を更新し、項目ごとの現在値を確認できるようにしました。WorkerがAPIから値を取得し、SyncsがNotionの台帳へ反映する構成です。

ドメイン情報と集計値の台帳で同期する列は、設定ID、設定項目、現在値、取得日時、同期状態です。SaaS名は分類用として別の列に持たせています。対象を増やすときは、APIで取得できる情報と必要な権限を確かめたうえで、取得処理と台帳への反映方法を追加します。

ドメイン情報と集計値として同期した8項目は、次のとおりです。

図1は、これらの情報を項目ごとに並べた台帳の例です。

図1：Google Workspaceを同期元にした台帳の例。ドメイン・人数・件数をマスキングしています。

設定値の変更と復元を確かめる

設定値そのものの例には、ユーザー単位の「ディレクトリ共有」を選びました。ドメインの連絡先共有が有効なときに、そのユーザーのプロフィールをアドレス帳に表示するかどうかの設定です（GoogleのUserリソース仕様）。APIの項目名は includeInGlobalAddressList。台帳では「アドレス帳への表示」として記録しています。

検証用ユーザー1人を対象に、Directory APIの users.get で値を取得しました。専用の現在値DBには設定項目・設定ID・対象ユーザーID・現在値・取得日時を、履歴DBには変更前後の値と前回・今回の取得日時を保存しています。

グループ総数・設定値のどちらも、差分の比較元は履歴用Sync自身が保存した前回値です。現在値用Syncとは別々に取得するため、両者の取得日時は必ずしも一致しません。

管理画面で設定を変更し、その都度同期して、APIの値とNotionの記録を照合しました。結果は次のとおりです。

この1項目では、設定値の取得から変更・復元への追従まで確認できました。 検証したのは管理画面・API・台帳の設定値で、利用者のアドレス帳画面での表示・非表示までは確かめていません。ほかの設定にも広げられるかは、対象のAPIと必要な権限を項目ごとに確認する必要があります。

変更履歴と作業申請を紐付ける

変更履歴と作業申請を結びつけると、値の変化から、その変更に対応する作業をたどれます。今回はグループ総数の増減を例に、1件の申請と複数の変更履歴を紐付ける構成を試しました。作業申請DBでは1件の申請を1レコードとして管理し、変更履歴の各レコードには「作業申請」と「元の台帳行」へのリレーションを持たせています。

図2：変更履歴から、対象の台帳行と作業申請へリレーションを設定する構成。

検証では、作業申請 PoC DBに「検証用空グループ1件の作成・削除」という申請レコードを用意しました。履歴の初回同期で比較用の基準値を保存した後、空グループを1件作成して現在値と変更履歴を同期すると、総数が「17 → 18」に増えた履歴が残りました。

この履歴を申請に書いた対象・作業内容と見比べ、「元の台帳行」にはGoogleグループ総数の行を、「作業申請」には用意した申請レコードを選択しました。続いて検証用グループを削除し、同期後に残った「18 → 17」の履歴も同じ台帳行と申請レコードへ紐付けています。作成と削除それぞれの照合結果を「確認状態」と「判断理由」に記入し、申請の状態を完了にしました。

ここで作業の目的を残す場所は申請側で、履歴の「判断理由」に書くのは、その申請に対応する変更だと判断した根拠です。確認した内容や申請との差異を履歴側に補足しておけば、後から変更と作業の対応をたどれます。

図3：グループの作成と削除による変更履歴の2行。各プロパティの記入例は、図4の履歴行ページで確認できます。

図4：「17 → 18」の履歴行ページ。作業申請と元の台帳行はリレーションで結び、判断理由には申請と照合した内容を記入しています。

この構成では、値の取得と履歴への記録を同期処理が担い、申請との照合結果は人が記入します。同期する列は、イベント、イベントID、設定ID、変更前、変更後、前回取得日時、今回取得日時、記録種別です。「元の台帳行」と「作業申請」は人が選ぶリレーション列で、「確認状態」と「判断理由」も手入力用に分けました。これらの列は同期スキーマの外に置くことで編集可能になります（Syncsガイド）。リレーションの作成方法も公式ガイドで確認できます。

履歴用Syncは、取得した値に差があるときに、前回取得日時と変更前後の値などからイベントIDを作り、そのIDをキーに履歴行を記録します。グループ総数と設定値のどちらも、同じ比較元と変更前後の値で再処理した場合は、同じIDで既存の行を更新する設計です。

同期方式には incremental を使い、今回の処理で返さない過去の行を残しています。ただし、同じキーの行の更新や明示的な削除も可能なため、モード自体が追記専用という意味ではありません。変更ごとに履歴が追加されるのは、この実装で異なるイベントIDを使っているためです。

今回の照合で自動取得しているのはグループ総数の増減であり、対応する申請は人が確認して紐付けています。どのグループを誰が変更したかを調べるには、操作に応じてGroups Enterpriseログイベントや管理ログイベントを別途確認する必要があります。検索できる範囲は、エディションと管理者権限によって異なります。また、申請が紐付いていない変更は確認の対象になりますが、それだけで不正とは断定できません。申請漏れや記入漏れ、作業ミス、想定外の操作などを分けて確認します。

取得した値の比較で捉えられる範囲にも限りがあります。グループを1件削除して別のグループを1件作成した場合など、総数が変わらない変更は検知できません。設定値・集計値のいずれも、取得の間に変更され、次の取得前に元に戻った操作は記録に残りません。

台帳の鮮度を確認する

台帳に値が表示されていても、同期が止まっていれば古い情報を見ている可能性があります。最後に取得できた日時を確認し、その値をいつの情報として扱えるか判断できるようにしておく必要があります。

運用時の工夫として、Notionの数式で取得日時からの経過時間を計算し、一定時間を超えた行を「要確認」と表示する方法が考えられます。その行だけをフィルターで集めた確認用ビューがあれば、取得日時を一行ずつ見直さずに、同期の稼働状況を調べる対象を絞れます。判定の基準は、予定する同期頻度に合わせて決めます。

記録先を選ぶ判断軸

今回の構成でNotionを使う利点は、取得した値と変更履歴、対応する作業申請を同じ場所でたどれることです。普段からNotionを使う人が台帳を確認するなら、そのまま照合結果を記録できる点も使いやすさにつながります。

記録先を選ぶときは、使う人の作業場所と、費用・保守の負担を合わせて考える必要があります。GitHubで日常的に差分を確認するチームなら、APIで取得した値を非公開リポジトリへ保存する構成も候補です。どちらを選ぶ場合も、収集処理を保守する人と、変更を確認して作業との対応を記録する人が必要になります。

料金の条件は、Notion Workersの公式ヘルプとGitHubの料金表で確認できます。Workersの無料ベータ中の条件と有料化後の費用は分けて考える必要があります。今回の消費クレジットは実測していないため、この構成の費用は評価していません。採用を検討するときは、必要な同期頻度と処理量で試し、利用量に加えて収集処理を保守する手間も見積もります。

おわりに

今回はNotion Workersを使い、SaaSの設定値を同期して変化を履歴に残すことと、グループ総数の変更履歴を作業申請に結びつける構成を試しました。取得した値だけでなく、対応する作業も同じ場所で確認できる点に、運用で使う台帳としての良さを感じました。

ここで紹介した構成は一例です。何を確認したいか、誰が使うか、既存のツールや費用、保守の体制によって、合う仕組みは会社ごとに変わります。今回の例を参考に、自社の状況に合う仕組みを検討してください。設定管理の進め方やツール選びに迷ったときは、お気軽にご相談ください！