イベントタイプ

このページでは、eventType プロパティと、Google カレンダー API で使用できるイベントタイプの仕様について説明します。

Google カレンダーでは、汎用的な予定だけでなく、特定のユースケース向けに設計されたカスタムプロパティ付きの予定も作成できます。

イベントタイプは、API の次の場所で確認できます。

すべてのイベントは eventType とともに返されます。
eventType イベントリソースを作成または更新するときは、設定する必要があります。設定しない場合は、 'default' タイプが使用されます。
eventTypes Events:list 呼び出しで指定すると、特定のタイプのイベントを一覧表示できます。タイプを指定しない場合は、すべてのイベントタイプが返されます。
eventTypes をEvents:watch 呼び出しで指定すると、特定のタイプのイベントの更新を購読できます。タイプを指定しない場合、リクエストはすべてのイベントタイプの購読になります。

デフォルトのイベント

default イベントタイプのイベントは、Google カレンダー API のメインリソースの 1 つとして作成され、使用されます。イベントをさらにカスタマイズするために使用できるさまざまなプロパティをサポートしています。

Google カレンダーの予定の操作を開始するには、予定を作成するをご覧ください。

誕生日

誕生日は、毎年繰り返される特別な終日イベントです。

ユーザーは、Google カレンダーで誕生日の予定を手動で作成できます。また、Google コンタクトにユーザーを追加して、誕生日やその他の重要な日付を入力すると、誕生日情報が Google カレンダーと同期されます。ユーザー自身の誕生日も、Google アカウントプロフィールから Google カレンダーに同期されます。

Google カレンダー API は、誕生日の予定を読み取るための get、 instances、および list メソッドをサポートしています。eventTypes を 'birthday' に設定すると、誕生日の予定のみを一覧表示できます。タイプを指定しない場合、誕生日が他のすべてのイベントタイプとともに一覧表示されます。

返された Event オブジェクトで、この特別なイベントの詳細について birthdayProperties フィールドを確認します。birthdayProperties には次のフィールドがあります。

type: この特別なイベントのタイプ。誕生日、記念日、その他の重要な日付など。
customTypeName: この特別なイベントのユーザー指定のラベル。type が 'custom' に設定されている場合は、このフィールドに入力されます。
contact: この特別なイベントがリンクされている連絡先のリソース名（存在する場合）。形式は 'people/c12345' で、連絡先の詳細を People API から取得するために使用できます。

この API を使用すると、次の仕様で insert メソッドを使用して誕生日の予定を作成できます。

eventType が 'birthday' に設定されます。
start と end フィールドで、 1 日のみの終日の予定を定義する必要があります。
visibility フィールドの値は 'private' である必要があります。
transparency フィールドの値は 'transparent' である必要があります。
年間の繰り返しを設定する必要があります。つまり、 recurrence フィールドは 'RRULE:FREQ=YEARLY' である必要があります。2 月 29 日の誕生日の予定には、次の繰り返しルールが必要です。 'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1'
colorId、 summary、 reminders を設定できます。
birthdayProperties を設定できます。指定する場合は、 type は 'birthday' である必要があり、 customTypeName と contact の両方を空にする必要があります。
他のイベントプロパティを設定することはできません。

この API を使用すると、update メソッドと patch メソッドを使用して、誕生日の予定の colorId、 summary、 reminders を更新できます。 start フィールドと end フィールドを更新して、イベントの日付を変更することもできます。この場合、新しい値は 1 日のみの終日の予定を定義する必要があります。誕生日の予定のタイミングの詳細は、イベントが contactにリンクされている場合、または typeが 'self'の場合、更新できません。

Google カレンダー API では、カスタムの birthdayPropertiesを使用して誕生日の予定を作成したり、これらのプロパティを更新したりすることはできません。重要な日付は People APIで編集でき、変更は Google カレンダーと同期されます。同様に、ユーザーは Google アカウントプロフィールで自分の誕生日を編集でき、Google カレンダーと同期されます。

サポートされていない方法で誕生日を作成または更新しようとするリクエストは失敗します。この場合は、エラーメッセージを確認して問題を確認してください。

この API は、誕生日の予定の import オペレーションをサポートしていますが、イベントはデフォルトのイベントとしてインポートされます。つまり、 eventType は 'default' になります。

この API は、watch メソッドをサポートしており、Google カレンダーの誕生日の予定の変更を購読できます。 eventTypes を 'birthday' に設定すると、誕生日の予定の更新を購読できます。タイプを指定しない場合、誕生日を含むすべてのイベントタイプが購読されます。

誕生日の予定は、 delete メソッドを使用して Google カレンダー API から削除できます。Google カレンダーから誕生日の予定を削除しても、 Google コンタクトや Google アカウントプロフィールのデータには影響しません。

move メソッドまたは update メソッドを使用して、誕生日の予定の主催者を変更することはできません。

Gmail からの予定

Gmail から自動的に生成された予定のイベントタイプは 'fromGmail' です。

Google カレンダー API では、 insert メソッドを使用してこのイベントタイプを作成することはできません。

この API を使用すると、update メソッドと patch メソッドを使用して、 colorId、 reminders、 visibility、 transparency、 status、 attendees、 private 、および shared の拡張プロパティを更新できます。

この API は、get と list メソッドをサポートしています。 Gmail からの予定を読み取るためのeventTypes を 'fromGmail' に設定すると、Gmail から生成された予定のみを一覧表示できます。タイプを指定しない場合、Gmail からの予定が他のすべてのイベントタイプとともに一覧表示されます。

この API は、watch メソッドをサポートしており、Google カレンダーの Gmail からの予定の変更を購読できます。タイプを指定しない場合、を含むすべてのイベントタイプが購読されます。'fromGmail'

Gmail からの予定は、 delete メソッドを使用して Google カレンダー API から削除できます。

move メソッドまたは update メソッドを使用して、Gmail からの予定の主催者を変更することはできません。

サイレントモード、不在設定、勤務場所

Google Calendar API を使用すると、Google カレンダーユーザーのステータスを示す予定を作成して管理できます。

これらの機能は、メインカレンダーと一部の Google カレンダーユーザーでのみ使用できます。詳細については、サイレントモード、不在設定、勤務場所の予定を管理するをご覧ください。

Google Apps Script でイベントタイプを確認する

Google Apps Script は、JavaScript ベースのクラウドスクリプト言語で、 Google Workspace と統合するビジネスアプリケーションを構築できます。スクリプトはブラウザベースのコードエディタで開発され、Google のサーバーに保存されて実行されます。Apps Script を使用して Google カレンダー API にリクエストを送信する方法については、Google Apps Script クイックスタートもご覧ください。

次の手順では、 Google Calendar API を Google Apps Script の高度なサービスとして使用して、予定を読み取って管理する方法について説明します。Google カレンダー API のリソースとメソッドの一覧については、リファレンスドキュメントをご覧ください。

スクリプトを作成して設定する

script.google.com/create にアクセスしてスクリプトを作成します。
[サービス] の横にある左側のパネルで、[サービスを追加] をクリックします。
[Google Calendar API] を選択して [追加] をクリックします。
有効にすると、API が左側のパネルに表示されます。API で使用可能なメソッドとクラスは、エディタで Calendar キーワードを使用して一覧表示できます。

（省略可）Google Cloud プロジェクトを更新する

各 Google Apps Script プロジェクトには、関連付けられた Google Cloud プロジェクトがあります。スクリプトでは、Google Apps Script が自動的に作成するデフォルトプロジェクトを使用できます。カスタムの Google Cloud プロジェクトを使用する場合は、別のスタンダードクラウドプロジェクトに切り替えるをご覧ください。Google Cloud プロジェクトを設定したら、左側の [エディタ] を選択してコードエディタに戻ります。

スクリプトにコードを追加する

次のコードサンプルは、さまざまな eventType 値を使用して予定を一覧表示、読み取り、作成する方法を示しています。

次のコードをコードエディタに貼り付けます。

const CALENDAR_ID = 'CALENDAR_ID' || 'primary';

/** Lists default events. */
function listDefaultEvents() {
  listEvents('default');
}

/** Lists birthday events. */
function listBirthdays() {
  listEvents('birthday');
}

/** Lists events from Gmail. */
function listEventsFromGmail() {
  listEvents('fromGmail');
}

/**
  * Lists events with the given event type. If no type is specified, lists all events.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = undefined) {
  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: eventType ? [eventType] : undefined,
    singleEvents: true,
    timeMax: '2024-07-30T00:00:00+01:00',
    timeMin: '2024-07-29T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
    response.items.forEach(event => console.log(event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Reads the event with the given eventId.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/get
  */
function readEvent() {
  try {
    var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Creates a default event. */
function createDefaultEvent() {
  const event = {
    start: { dateTime: '2024-07-30T10:30:00+01:00'},
    end: { dateTime: '2024-07-30T12:30:00+01:00'},
    description: 'Created from Apps Script.',
    eventType: 'default',
    summary: 'Sample event',
  }
  createEvent(event);
}

/** Creates a birthday event. */
function createBirthday() {
  const event = {
    start: { date: '2024-01-29' },
    end: { date: '2024-01-30' },
    eventType: 'birthday',
    recurrence: ["RRULE:FREQ=YEARLY"],
    summary: "My friend's birthday",
    transparency: "transparent",
    visibility: "private",
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {

  try {
    var response = Calendar.Events.insert(event, CALENDAR_ID);
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

次のように置き換えます。

CALENDAR_ID: 予定を取得して作成するカレンダーのメールアドレス。この定数は、最初は 'primary'に設定されています。これは、ログインしているユーザーのメインカレンダーにアクセスするためのキーワードです。この値を変更すると、アクセス権のある他のユーザーのカレンダーの予定を読み取ることができます。
EVENT_ID: イベントの ID。Events:list を呼び出してイベント ID を取得できます。

コードサンプルの実行

コードエディタの上で、プルダウンメニューから実行する関数を選択し、[実行] をクリックします。
最初の実行時に、アクセス権の承認を求めるメッセージが表示されます。Apps Script がカレンダーにアクセスすることを許可します。
スクリプトの実行結果は、ウィンドウの下部に表示される [実行ログ] で確認できます。