詳細プロパティ

Events リソースのフィールドは、場所や開始時間など、イベントに関連付けられた最も一般的なデータを対象としていますが、アプリケーションでは、ユースケースに固有の追加のメタデータを保存することがあります。Calendar API では、イベントに非表示の Key-Value ペア（拡張プロパティ）を設定できます。拡張プロパティを使用すると、外部データベースを使用しなくても、イベントのアプリケーション固有のデータを簡単に保存できます。

公開設定

拡張プロパティには、プライベートと共有の 2 種類があります。共有プロパティはイベントのすべての参加者に表示され、編集できます。一方、非公開プロパティは、イベントの 1 人の参加者のローカル「コピー」に設定されます。具体的には、プライベート プロパティはリクエストで使用される calendarId と eventId に固有のものであり、共有プロパティはリクエストで使用される calendarId に関係なく表示されます。

プロパティを追加、更新する

拡張プロパティは Events リソースに設定され、他のフィールドと同様に insert、update、patch リクエストで設定できます。パッチ リクエストを使用すると、一部のプロパティを操作し、他のプロパティはそのままにできるため、この方法が推奨されます。同じキーを持つ新しいプロパティを追加すると、同じキーを持つ既存のプロパティが上書きされます。次の例は、プライベート プロパティを設定する方法を示しています。

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId
 
{
  "extendedProperties": {
    "private": {
      "petsAllowed": "yes"
    }
  }
}

プロパティを削除する

更新リクエストに含まれていないプロパティは削除されますが、値を null に設定するパッチ リクエストを行うことをおすすめします。次の例は、非公開プロパティを削除する方法を示しています。

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId
 
{
  "extendedProperties": {
    "private": {
      "petsAllowed": null
    }
  }
}

プロパティを検索

Events.list リクエストを使用して、拡張プロパティの値に基づいてイベントを検索できます。フィールド privateExtendedProperty または sharedExtendedProperty を propertyName=value 形式の制約に設定します。これにより、それぞれプライベート プロパティと共有プロパティに対して検索が行われます。次の例では、非公開プロパティ petsAllowed=yes を持つイベントを返します。

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes

これらのフィールドは複数回繰り返すことができ、制約は OR で結合されるため、イベントは制約のいずれか 1 つに一致するだけで返されます。次の例では、非公開プロパティ petsAllowed=yes または isOutside=yes のいずれかを持つイベントを検索します。

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &privateExtendedProperty=isOutside%3Dyes

ただし、非公開プロパティと共有プロパティの制約は AND 演算で結合されるため、イベントが返されるには両方の制約セットに一致する必要があります。次の例では、非公開プロパティ petsAllowed=yes と公開プロパティ createdBy=myApp を持つイベントを検索します。

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &sharedExtendedProperty=createdBy%3DmyApp

上限

  1. プロパティのキーの最大サイズは 44 文字です。これより長いキーを持つプロパティは、通知なしで削除されます。
  2. プロパティの値の最大サイズは 1, 024 文字です。これより長い値を持つプロパティは、通知なしで切り捨てられます。
  3. イベントには、合計サイズが 32 KB（キーのサイズ + 値のサイズ）までのプロパティを最大 300 個含めることができます。これらの 300 個のプロパティには、イベントのすべての「コピー」にわたる共有プロパティと非公開プロパティが含まれます。