共有カレンダーで「来客は赤、社外の打ち合わせは青」と色を決め、予約フォームや社内ツールから入る予定をAPIで塗り分けている会社があります。使っているのは予定の colorId で、colors エンドポイントが返す色の一覧から番号で選ぶ仕組みです。番号に意味はないので、「赤が来客」という約束は、ツールの設定と社内の申し合わせの中にしかありません。
Google Calendar APIに、名前と色を持つ「予定ラベル」が加わり、2026年7月7日のリリースノートで一般提供（GA）と告知されました。予定には eventLabelId でラベルを付け、ラベル自体はカレンダーごとに labelProperties.eventLabels で定義します。リファレンスは、この項目が「supersedes the index-based colorId property（番号で選ぶ colorId に代わる）」と説明しています。本記事では、2026年10月18日にCalendar APIのDiscovery文書（revision 20261012）とGoogleのクライアントライブラリを、10月19日にリファレンス、ラベルのガイド、リリースノート、Workspace Updatesの告知を開いて確認した内容から、既存のツールを切り替える前に知っておく条件を整理します。資料調査と編集部の提案で、認証情報がないためAPIの呼び出しは行っていません。
colorIdと予定ラベルの違い
これまでの colorId は、colors エンドポイントが返す色の一覧の番号を指すだけでした。予定ラベルは、カレンダーごとに定義する名前付きの区分です。リファレンス（Calendars）の labelProperties.eventLabels には次の項目があります。
id: ラベルのID。リファレンスでは、新しく作るときは省略でき、省略すると一意のIDが作られます。更新するときは必須で、指定する場合はカレンダー内で一意のUUID形式にします。ただし、ガイドは「各ラベルにidが必要」と書いています（後述）backgroundColor: 「#039be5」のような16進数の色。必須ですname: ラベルの名前。省略でき、指定する場合は50文字以内です
1つのカレンダーに定義できるラベルは200件までです（「Each calendar can have a maximum of 200 labels.」）。ラベルを定義する場所はカレンダー（calendars リソース）で、個人ごとの表示設定である calendarList 側には項目がありません。
権限の条件はガイドに書かれています。ラベルを定義・変更するには、そのカレンダーのオーナー権限が必要です（「You must have owner access to a calendar to define or modify its labels.」）。予定にラベルを付けるには、writerWithoutPrivateAccess 以上（writer・owner を含む）の権限が要ります。共有カレンダーなら、オーナーが定義したラベルを、予定を入れる人が使う形になります。
予定にラベルを付けるには版の指定が要る
予定にラベルを付けるには、events の insert・import・update・patch に eventLabelVersion=1 を付けます。リファレンス（events.patch など）の説明は次のとおりです。
Version 0 assumes no event label support and processes the colorId field for color management. Version 1 enables support for event labels, and processes the eventLabelId in the event’s body. In this case, the colorId field is ignored. The default is 0.
既定は0なので、何も変えなければ今までどおり colorId が使われます。逆に、eventLabelVersion=1 を付けた要求では colorId が無視されます。同じツールの中で、ある処理は colorId、別の処理はラベル、と混ぜると、どちらの色が残るかを追いにくくなります。切り替えるなら、予定を書き込むすべての処理で版をそろえます。
import { calendar_v3 } from '@googleapis/calendar';
// 共有カレンダーに「来客」「社外打ち合わせ」のラベルを定義する
export async function defineLabels(calendar: calendar_v3.Calendar, calendarId: string) {
const current = await calendar.calendars.get({ calendarId });
const labels = current.data.labelProperties?.eventLabels ?? [];
await calendar.calendars.patch({
calendarId,
requestBody: {
labelProperties: {
eventLabels: [
...labels, // 既存のラベルを含めないと消える
{ name: '来客', backgroundColor: '#d50000' },
{ name: '社外打ち合わせ', backgroundColor: '#039be5' },
],
},
},
});
}
// 予定にラベルを付ける（eventLabelVersion: 1 が必要）
export async function labelEvent(calendar: calendar_v3.Calendar, calendarId: string, eventId: string, labelId: string) {
await calendar.events.patch({
calendarId,
eventId,
eventLabelVersion: 1,
requestBody: { eventLabelId: labelId },
});
}このコードは、Node.js用の @googleapis/calendar 20.1.0の型定義に対して型チェックを通したもので、実際に送って応答を確かめたものではありません。新しいラベルの id を省略しているのはリファレンスの説明に沿ったものですが、ガイドは「各ラベルに id が必要」と書き、例では自分でUUIDを付けて calendars.update で送っています。公式の記述が分かれているため、確実にするなら id に自分でUUIDを入れて送ってください。id を省略した場合の実際の挙動は確かめていません。
ラベルが消える2つの書き方
予定ラベルには、意図せず消してしまう書き方が2つあります。どちらもリファレンスとガイドに書かれている挙動です。
1つ目は、カレンダーのラベル一覧の上書きです。 labelProperties は「If specified, overwrites the existing label properties.」、eventLabels も「If this is present when updating the calendar, it will replace the existing event labels.」です。追加したいラベルだけを送ると、それ以外のラベルは削除されます。ガイドも、先にカレンダーを読み取って今の一覧を取り、手元で足し引きしてから送るよう求めています。上のコードのように calendars.get で今の一覧を取り、そこに足して送ります。削除したいときは一覧から外して送ります。
2つ目は、予定側の項目の省略です。 eventLabelId の説明には「Setting an empty string, or not setting this field at all, will remove the existing label from the event.」とあります。ガイドも「update の要求で項目を省略するとラベルが外れる」と書いています。eventLabelVersion=1 で update するときは、本文に eventLabelId を含めないとラベルが外れます。一方、events.patch の説明には「要求で指定しなかった項目は変わらない（Fields that you don’t specify in the request remain unchanged.）」とあり、patch で eventLabelId を省略したときにラベルが残るかは、資料からは判断できません。時刻だけを変える処理を書くときは、テスト用のカレンダーで patch と update の両方を確かめてください（未確認）。
いつから使えるか
Calendar APIのリリースノートは、2026年7月7日の項目で「The Google Calendar API now provides full support for custom labels and colors」と、予定ラベルを一般提供（Generally Available）として告知しています。labelProperties でラベルを定義し、eventLabelId で予定に付け、eventLabelVersion=1 が必要という説明も、本文で紹介した内容と同じです。Googleが公開するPython用の google-api-python-client でも、2.198.0（Calendarの定義はrevision 20260614）には eventLabelId がなく、2.199.0（revision 20260708、2026年8月20日公開）から入っています。Node.js用の @googleapis/calendar は、10月19日時点の最新版20.1.0に含まれています。
利用者向けには、Workspace Updatesブログが2026年6月17日に「Custom event colors in Google Calendar」を告知しています。決まった11色だけだった予定の色を広げ、ウェブ版・モバイルアプリ・Calendar APIから最大200のカスタムの色を使えるようになり、標準で24色から選べ、ウェブ版（またはAPI）ではRGBの色を自分で決められる、という内容です。展開は即時リリースのドメインで6月17日から、計画的リリースのドメインで6月29日からで、対象はすべてのGoogle Workspaceの顧客、Workspace Individual、個人のGoogleアカウントです。管理者の設定はありません。ブログの「200」は「each user」と書かれており、リファレンスの「1カレンダーあたり200件」とは数え方の表現が違います。上限はリファレンスの値で設計してください。
既存の colorId の色がラベルに移し替えられるのかは、どの資料にも書かれておらず、確認できていません。
切り替える前に決めること（編集部の提案）
- 今の色の約束を書き出す: ツールの設定から、どの
colorIdが何を意味しているかを一覧にします。この一覧が、そのままラベルの名前になります - ラベルを定義する担当を決める: ラベルの一覧はカレンダーの設定で、変更できるのはオーナー権限を持つ人です。オーナーが複数いたり、複数のツールがオーナーの権限で書き換えたりすると、上書きで消える事故が起きます。定義を変える処理は1か所にまとめます
- 書き込む処理をすべて洗い出す: 予約フォーム、社内ツール、Apps Script など、予定を作る・直す処理を一覧にし、
eventLabelVersionをそろえて切り替えます - テスト用のカレンダーで確かめる: ラベルを付けた予定の時刻を変える、参加者を足す、といった日常の更新でラベルが残るかを確認してから本番に移します
共有カレンダーの持ち主を退職前に移す手順はカレンダーの所有者を移す条件で、海外拠点との予定調整は3つ目のタイムゾーンの記事で扱っています。ラベルの定義を変える担当者を決めるときは、カレンダーの持ち主が誰かもあわせて確認してください。
まずは、予定をAPIで書き込んでいる処理がいくつあるかを数えるところから始めてください。1つなら切り替えは小さく済み、複数なら版をそろえる順番を決める必要があります。
2026年10月18日に、Google Calendar APIのDiscovery文書（calendar v3、revision 20261012）、google-api-python-client 2.198.0・2.199.0に同梱の定義とPyPIの公開日時、npmの
@googleapis/calendar20.1.0の型定義を直接取得して確認しました。10月19日に、Events・Calendars・events.patchのリファレンス、ラベルのガイド、Calendar APIのリリースノート、Workspace Updatesの告知（2026年6月17日）を開いて照合しました（資料調査）。コード例は@googleapis/calendar20.1.0に対してTypeScriptの型チェックを通したものです。認証情報がないためAPIの呼び出しは行っておらず、実際の応答、patchでラベルが残るか、idを省略してラベルを作ったときの挙動、カレンダーの画面での表示、既存の色の移し替えは未確認です。
Googleカレンダーと予約フォーム・社内ツールの連携の見直しは、グリームハブのIT・Google Workspace 無料相談で承っています。連携しているツールの数や使い方によって進め方が変わるため、お問い合わせからご相談ください。
参考資料
- Google Calendar API release notes
- Google Calendar API — Labels（ガイド）
- Google Calendar API reference — Events
- Google Calendar API reference — Calendars
- Google Calendar API reference — Events: patch
- Google Workspace Updates — Custom event colors in Google Calendar（2026年6月17日）
- Google Calendar API Discovery document（calendar v3）
- PyPI — google-api-python-client
- npm registry — @googleapis/calendar
