Calendar APIで勤務時間を設定 入社・時短を自動反映

Googleカレンダーの勤務時間は、会議に招待する人に相手の勤務時間外だと知らせたり、空き時間を探すときの目安になったりする設定です。ただしGoogleのヘルプが案内している設定の場所は、本人のパソコンの画面です。Calendar APIのカレンダーのリソースにも、これまで勤務時間の項目はありませんでした。入社した人が未設定のままだったり、時短勤務に切り替えたあとも以前の時間が残ったりしても、このリソースから直すことはできなかったわけです。

2026年11月3日のCalendar APIのリリースノートで、カレンダーのリソース（Calendar）の新しい項目 workingHours が一般提供（Generally Available）になったと告知されました。本記事では、リリースノート、リファレンス、API定義（Discovery文書）、ヘルプを2026年11月6日に確認した内容をもとに、書き方と、人事の情報と連携するときに気をつけたい点を整理します。

リリースノートとリファレンスに書かれていること

リリースノートの2026年11月3日の項目には、Google Workspaceのユーザーの主カレンダーについて、Calendars リソースの新しいプロパティ workingHours で勤務時間を読み取り、更新できると書かれています。提供段階は「Generally Available」です。

Calendars のリファレンス（最終更新 2026年11月3日）にもこの項目が載っており、2026年11月6日に取得したDiscovery文書（revision 20261102）の説明と一致しています。Googleの公式クライアント（google-api-go-client）が自動生成している定義の履歴では、2026年11月5日のコミットで revision が 20260925 から 20261030 に上がり、このときに workingHours が追加されています。

リファレンスの説明を要約すると、次のとおりです。

• 対象は主カレンダーだけ。 Google Workspaceのユーザーの主カレンダー（primary）でのみ使える
• 中身は2つ。 勤務時間が有効かどうか（workingHoursEnabled）と、曜日ごとの時間帯の一覧（availableTimes）
• 時間帯は「その日の0時からの分」。 periodStart は含み、periodEnd は含まない。9時は540、18時は1080
• 曜日は英語の小文字。 monday から sunday までの7つ
• 更新するときは全体を渡す。 一部の曜日だけを送る差分の更新はできない

書き方：曜日と時刻を「分」に直して送る

人事の情報にある「平日 9:00〜18:00」のような勤務時間を、APIの形に変換して、主カレンダーの更新（calendars.patch）で送ります。次のコードは、Node.js 22の標準の fetch を使った例です。

const DAYS = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'];
const toMinutes = (hhmm) => {
  const [h, m] = hhmm.split(':').map(Number);
  return h * 60 + m;
};

// 例: { monday: [['09:00', '18:00']], ... } を workingHours に変換する
export function buildWorkingHours(schedule) {
  const availableTimes = [];
  for (const [day, blocks] of Object.entries(schedule)) {
    if (!DAYS.includes(day)) throw new Error(`unknown day: ${day}`);
    for (const [start, end] of blocks) {
      const periodStart = toMinutes(start);
      const periodEnd = toMinutes(end); // 終了は「含まない」
      if (periodEnd <= periodStart) throw new Error(`${day} ${start}-${end}`);
      availableTimes.push({ dayOfWeek: day, periodStart, periodEnd });
    }
  }
  // 空のまま有効にはできない（API の定義）
  return { workingHoursEnabled: availableTimes.length > 0, availableTimes };
}

export async function setWorkingHours(accessToken, workingHours) {
  // 主カレンダー（primary）だけが対象。オブジェクト全体を渡す
  const res = await fetch('https://www.googleapis.com/calendar/v3/calendars/primary', {
    method: 'PATCH',
    headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ workingHours }),
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return (await res.json()).workingHours;
}

2026年11月6日に、このコードをNode.js 22.23.4（macOS）で実行し、buildWorkingHours が作る本文をDiscovery文書（revision 20261102）の定義と突き合わせました。項目名・曜日の値・整数の型は一致しています。認証情報がないため、実際のアカウントでの更新と、カレンダーの画面での表示は確認していません。

calendars.patch のリファレンスには、patchの呼び出しは1回でクォータを3単位使うため、getのあとにupdateを使うことを勧める、とも書かれています。多くの社員に一括で流す場合は、この点も考えて組み立ててください。

なお、ヘルプによると、設定の画面では1日に複数の時間帯を追加できます。ただしAPIのリファレンスには、1日に複数の時間帯（昼休みで分けるなど）を送れるとは明記されていません。availableTimes は一覧なので形としては書けますが、受け付けられるかは検証用のアカウントで確かめてから使ってください。

「全体を渡す」更新で起きること

リファレンスには、更新の扱いが細かく書かれています。連携の仕組みを作るときは、ここを先に確かめておきます。

1. 送った内容で置き換わる。 calendars.patch のリファレンスには、配列を指定すると既存の配列を上書きし、以前の要素は捨てられると書かれています。「水曜だけ短くする」つもりで水曜の1件だけを送ると、ほかの曜日の時間帯が消えると読めます。必ず週全体を組み立ててから送ります
2. 送らなければ変わらない。 workingHours を省くか、nullや空のオブジェクトを送った場合は、今の勤務時間がそのまま残ります。カレンダーの名前や説明だけを更新する既存の処理が、勤務時間を消すことはないと読めます
3. 止めるときは workingHoursEnabled を false にする。 勤務時間をなくすときは、availableTimes を省くか空の一覧にして、workingHoursEnabled を false にします
4. 空の一覧のまま有効にはできない。 availableTimes が空のときに workingHoursEnabled を true にすることはできない、と書かれています

上のコードで、時間帯が1件もなければ workingHoursEnabled を false にしているのは、4つ目の制約に合わせるためです。

人事の情報と連携するときに決めておくこと（編集部の提案）

ここからは、公式の資料から読み取れる性質をもとにした編集部の提案です。

本人が設定した勤務時間を上書きしてよいかを決める。 APIで全体を送ると、本人が画面で調整した内容は置き換わります。人事の情報を正とするのか、未設定の人にだけ初期値を入れるのかを、先に決めておきます。後者なら、calendars.get で今の workingHours を読み、無効か空のときだけ書き込む作りにできます。

期間限定の時短は、開始と終了の両方で更新する。 ヘルプによると、勤務時間は毎週くり返す形でしか設定できず、一時的な変更は通常の勤務時間を直して、終わったら戻す扱いです。APIの項目も曜日ごとの形なので、短くする日と戻す日の両方を連携の処理に入れておきます。

時刻がどのタイムゾーンで解釈されるかを確かめる。 リファレンスは「その日の0時からの分」としか書いておらず、どのタイムゾーンの0時かは明記していません。ヘルプには、出張、勤務場所の設定、タイムゾーンの変更があると、勤務時間は勤務場所の現地時刻に自動で合わせられるとあります。カレンダー自体のタイムゾーン（timeZone）が基準になると考えられますが、海外拠点の社員がいる会社では、検証用のアカウントで表示を確かめてから展開してください。タイムゾーンの表示については3つ目のタイムゾーンの記事でも扱いました。

誰の権限で書き込むかを決める。 calendars.patch に使えるスコープは、リファレンスでは calendar・calendar.calendars・calendar.app.created の3つです。calendar.app.created の公式の説明はセカンダリカレンダーの作成とその予定の操作なので、社員の主カレンダーに書き込むには前の2つのどちらかが要ると考えられます。calendar.calendars の説明はカレンダーのプロパティの参照・変更とセカンダリカレンダーの作成で、calendar より範囲が絞られています。社員全員の分をまとめて設定するなら、サービスアカウントのドメイン全体の委任で本人として書き込む構成が候補になりますが、強いスコープを組織全体に許可することになるため、対象の部署やスコープを絞って設計します。カレンダーの所有者の移管など、管理者の権限で操作するAPIはセカンダリカレンダーの移管の記事で整理しています。

勤務場所の設定とは分けて考える。 出社・在宅といった勤務場所は、Calendar APIでは予定（イベント）の一種として扱われ、今回の workingHours とは別の仕組みです。連携の範囲を決めるときに混同しないようにします。

確認した範囲と、まだ分からないこと

2026年11月6日に、Calendar APIのリリースノート（2026年11月3日の項目）、Calendars と calendars.patch のリファレンス、スコープの説明のページ、Discovery文書（revision 20261102）、googleapis/google-api-go-client リポジトリのコミット（4b9955f、2026年11月5日）、Googleカレンダーのヘルプを確認しました（資料調査）。コード例は、作る本文と定義の項目・型の照合のみ実施しています。実際のアカウントでの更新と、画面での表示は確認していません。対象のエディションの一覧、1日に複数の時間帯を送れるか、時刻の基準となるタイムゾーンも、公式の資料からは確認できていません。ヘルプには、管理者が勤務時間をオンにしていないと設定の項目が出ない場合があるとありますが、その組織でAPIから書き込めるかも未確認です。使う前に、検証用のアカウントで確かめてください。

入社・異動の手続きとGoogle Workspaceの設定をつなぐ仕組みは、グリームハブのIT・Google Workspace 無料相談で承っています。人事の情報の持ち方や権限の範囲によって構成が変わるため、お問い合わせからご相談ください。

参考資料

• Google Calendar API release notes
• Google Calendar API reference — Calendars
• Google Calendar API reference — Calendars: patch
• Choose Google Calendar API scopes
• Manage focus time, out of office, and working location events
• Google Calendar Help — Set your working hours
• Google Calendar API Discovery document（calendar v3）
• googleapis/google-api-go-client — calendar/v3/calendar-api.json