詳細プロパティ

イベント リソースのフィールドには、イベントに関連する最も一般的なデータ（場所、開始時間など）が含まれていますが、ユースケースに固有の追加メタデータを保存することもできます。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. イベントには、最大 300 個のプロパティを指定できます。合計サイズは最大 32 KB（キーのサイズ + 値のサイズ）です。これらの 300 個のプロパティには、イベントのすべての「コピー」にわたる共有プロパティと非公開プロパティが含まれます。