退職者アカウントの停止日をAPIで取る Admin SDKの新項目

退職した社員のアカウントを、すぐに削除せず「停止」にしておく方法があります。メールやドライブのデータを引き継ぐ間、残しておけます。問題は、停止したあとです。半年たっても停止のまま残り、いつ止めたのか、もう消してよいのかを誰も判断できない。管理コンソールで1人ずつ監査ログをさかのぼれば分かりますが、人数が増えると現実的ではありません。

Admin SDK Directory APIのユーザー情報（User）に、停止した日時を表す suspensionTime と、アーカイブした日時を表す archivalTime が加わりました。本記事では、2026年10月18日にDirectory APIのDiscovery文書（directory_v1、revision 20261012）、Googleのクライアントライブラリ、管理ツールGAMのリポジトリを、10月19日にAPIリファレンス（Users）とユーザー検索のガイドを開いて確認した内容から、棚卸しへの使い方を整理します。資料調査と編集部の提案で、認証情報がないためAPIの呼び出しは行っていません。

加わった2つの項目

APIリファレンスのUsersのページ（2026年6月3日更新）とDiscovery文書の User には、次の説明があります。

• suspensionTime:「Output only. User’s account suspension time. (Read-only)」
• archivalTime:「Output only. User’s account archival time. (Read-only)」

どちらも読み取り専用で、APIから値を書き換えることはできません。もともとあった項目と並べると、次のようになります。

suspensionReason があるので、管理者が止めたのか、Google側の判断で止まったのかも同時に分かります。棚卸しでは、管理者が止めたもの以外を先に確認する、という並べ方ができます。

なお、日付の形式（どのタイムゾーンで、どの書式の文字列か）は確認できていません。リファレンスでは型が string とあるだけで、Discovery文書のこの2項目にも format の指定がありません。比較に使う前に、実際の値を1件見て形式を確かめてください。

いつから取れるか

Admin SDKのリリースノート（10月19日時点で最新の項目は2025年12月30日）とWorkspace Updatesブログには、この2項目の告知は見当たりませんでした。リファレンスのUsersのページには載っています。Googleが公開するPython用の google-api-python-client で比べると、2.197.0（Directoryの定義はrevision 20260421）には2つの項目がなく、2.198.0（revision 20260531、2026年6月25日公開）から入っています。Node.js用の @googleapis/admin も、10月19日時点の最新版37.0.2の型定義に含まれています。

管理ツールGAMの更新履歴（src/GamUpdate.txt）の7.44.00には「Added support for User data archivalTime and suspensionTime that is available when fields archived and suspended are requested in gam info user and gam print users.」とあります。GAMの説明では、archived や suspended を出力の項目に含めたときに一緒に返る、という書き方です。

項目が加わる前に停止したユーザーにも日時が入るのかは、どちらの資料にも書かれていません。古い停止ユーザーで値が空なら、その人は従来どおり監査ログで確かめる必要があります。

停止から90日を過ぎたユーザーを洗い出す

次のコードは、全ユーザーを取得し、停止またはアーカイブから90日を過ぎたものを一覧にします。users.list の fields で必要な項目だけに絞っています。maxResults の上限は500です。

import { admin_directory_v1 } from '@googleapis/admin';

// 停止・アーカイブから90日を過ぎたユーザーを洗い出す
export async function staleAccounts(admin: admin_directory_v1.Admin, now = new Date()) {
  const limit = now.getTime() - 90 * 24 * 60 * 60 * 1000;
  const out: { email: string; state: string; since: string; reason?: string }[] = [];
  let pageToken: string | undefined;
  do {
    const res = await admin.users.list({
      customer: 'my_customer',
      maxResults: 500,
      pageToken,
      fields: 'nextPageToken,users(primaryEmail,suspended,suspensionTime,suspensionReason,archived,archivalTime)',
    });
    for (const u of res.data.users ?? []) {
      if (!u.suspended && !u.archived) continue;
      const since = u.archived ? u.archivalTime : u.suspensionTime;
      if (since && Date.parse(since) < limit) {
        out.push({ email: u.primaryEmail!, state: u.archived ? 'archived' : 'suspended', since, reason: u.suspensionReason ?? undefined });
      }
    }
    pageToken = res.data.nextPageToken ?? undefined;
  } while (pageToken);
  return out;
}

このコードは、@googleapis/admin 37.0.2の型定義に対して型チェックを通したもので、実際に送って応答を確かめたものではありません。ユーザー検索のガイドには isSuspended・isArchived という条件があり、users.list の query に isSuspended=true のように書けば停止中のユーザーだけに絞れます。ここでは停止とアーカイブを1回の取得で拾うため、全件を取って手元で絞っています。呼び出しには admin.directory.user.readonly 以上のスコープが必要です。

一覧ができたら何を判断するか（編集部の提案）

日時が取れても、消してよいかどうかは別の確認が要ります。一覧に並んだユーザーごとに、次の順で確かめます。

1. データの引き継ぎが終わっているか: メール・ドライブ・カレンダーの持ち主の移し替えが済んでいるかを確認します。共有カレンダーは、所有者を退職前に移す条件にあるとおり、削除の前に移す必要があります
2. 保持の義務があるか: 訴訟や監査のために残すべきデータがあれば、Vaultの保持の設定を確かめます。削除してから気づいても戻せません
3. 停止のままか、アーカイブか、削除か: 停止のままでもライセンスがかかる契約かどうかで判断が変わります。アーカイブユーザーのライセンスとの関係は、退職者アカウントを消せない・払い続けたくない問題で整理しています
4. 判断を記録する: 誰が、いつ、どの根拠で消したかを残します。次の棚卸しで同じ確認を繰り返さずに済みます

90日という区切りは、この記事での例です。自社の就業規則や保持の方針にあわせて決めてください。

使う前に確かめること

• 値が入らないユーザー: 項目が加わる前に停止・アーカイブしたユーザーで、日時が返るかは未確認です。空のユーザーは別の一覧にして、監査ログで確かめます
• 一度戻してまた止めた場合: 停止を解除して再び停止したとき、日時が最新の停止に置き換わるのかは書かれていません
• アーカイブと停止の関係: アーカイブしたユーザーで suspended がどう返るかは確認していません。上のコードは、どちらかが true なら対象にしています
• ライブラリの版: Node.jsで使う場合は、型定義に項目がある版にします。古い版でも fields に指定すれば返る可能性はありますが、確認していません

まずは、いま停止中のユーザーが何人いるかを数え、日時が入っているかを1件確かめるところから始めてください。管理者アカウント全体の見直しは、Google Workspaceのセキュリティチェックリストとあわせて進めると漏れが減ります。

2026年10月18日に、Admin SDK Directory APIのDiscovery文書（directory_v1、revision 20261012）、google-api-python-client 2.197.0・2.198.0に同梱の定義とPyPIの公開日時、npmの @googleapis/admin 37.0.2の型定義、GAM-team/GAMの src/GamUpdate.txt を直接取得して確認しました。10月19日に、APIリファレンス（Users、users.list）、ユーザー検索のガイド、Admin SDKのリリースノートを開いて照合しました（資料調査）。コード例は @googleapis/admin 37.0.2に対してTypeScriptの型チェックを通したものです。認証情報がないためAPIの呼び出しは行っておらず、実際の応答、日時の形式、項目追加前に停止したユーザーの値、停止の解除と再停止の扱いは未確認です。

退職者アカウントの棚卸しや、入退社の手続きのGoogle Workspace側の整備は、グリームハブのIT・Google Workspace 無料相談で承っています。ユーザー数や保持の方針によって進め方が変わるため、お問い合わせからご相談ください。

参考資料

• Directory API reference — REST Resource: users
• Directory API reference — Method: users.list
• Directory API — Search for users（ガイド）
• Admin SDK Directory API Discovery document（directory_v1）
• PyPI — google-api-python-client
• npm registry — @googleapis/admin
• GAM-team/GAM — src/GamUpdate.txt