このページは Cloud Translation API によって翻訳されました。

詳細プロパティ

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

公開設定

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

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

拡張プロパティはイベントリソースで設定され、他のフィールドと同様に 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 形式の制約を設定します。これにより、それぞれ private プロパティと共有プロパティが検索されます。次の例では、プライベートプロパティ petsAllowed=yes を含むイベントを返します。

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

これらのフィールドは複数回繰り返すことができ、制約は OR で結合されます。したがって、イベントは、いずれかの制約に一致するだけで返されます。次の例では、プライベートプロパティ 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

上限

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