詳細プロパティ

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

公開設定

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

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

拡張プロパティはイベント リソースに設定され、他のフィールドと同様に 挿入、 更新、および パッチ リクエストで設定できます。 パッチリクエストを使用すると、一部のプロパティを操作しながら、他のプロパティはそのままにできるため、この方法をおすすめします。同じキーで新しいプロパティを追加すると、同じキーを持つ既存のプロパティが上書きされます。非公開プロパティを設定する例を次に示します。

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. 1 つのイベントに最大 300 個のプロパティを設定でき、合計サイズは最大 32 KB（キーサイズ + 値サイズ）です。これらの 300 個のプロパティには、イベントのすべての「コピー」の共有プロパティと非公開プロパティが含まれます。