Właściwości rozszerzone

Pola zasobów Events obejmują najczęstsze dane związane z wydarzeniem, takie jak lokalizacja, godzina rozpoczęcia itp., ale aplikacje mogą chcieć przechowywać dodatkowe metadane specyficzne dla ich przypadku użycia. Interfejs Calendar API umożliwia ustawianie ukrytych par klucz-wartość w zdarzeniu, zwanych właściwościami rozszerzonymi. Właściwości rozszerzone ułatwiają przechowywanie danych dotyczących konkretnej aplikacji w przypadku zdarzenia bez konieczności korzystania z zewnętrznej bazy danych.

Widoczność

Dostępne są 2 rodzaje właściwości rozszerzonych: prywatne i współdzielone. Wspólne właściwości są widoczne i edytowalne dla wszystkich uczestników wydarzenia, a prywatne właściwości są ustawiane w lokalnej „kopii” wydarzenia należącej do jednego z uczestników. Właściwości prywatne są powiązane z calendarId i eventId używanymi w żądaniu, a właściwości udostępnione będą wyświetlane niezależnie od calendarId używanego w żądaniu.

Dodawanie i aktualizowanie obiektów

Właściwości rozszerzone są ustawiane w zasobie Events i podobnie jak inne pola można je ustawiać w żądaniach insert, update i patch. Korzystanie z żądań PATCH jest preferowaną metodą, ponieważ umożliwia modyfikowanie niektórych właściwości bez zmiany innych. Dodanie nowej właściwości z tym samym kluczem spowoduje zastąpienie wszystkich istniejących właściwości z tym samym kluczem. Poniższy przykład pokazuje ustawianie właściwości prywatnej:

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

Usuwanie usług

Wszystkie właściwości, które nie zostały uwzględnione w żądaniu aktualizacji, zostaną usunięte. Lepszym rozwiązaniem jest jednak wysłanie żądania zmiany, aby ustawić wartość na null. Poniższy przykład pokazuje usuwanie usługi prywatnej:

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

Wyszukaj właściwości

Możesz wyszukiwać zdarzenia na podstawie wartości ich właściwości rozszerzonych za pomocą żądania Events.list. Ustaw pole privateExtendedProperty lub sharedExtendedProperty na ograniczenie w formacie propertyName=value, które wyszukuje odpowiednio właściwości prywatne i udostępnione. Poniższy przykład zwraca zdarzenia z właściwością prywatną petsAllowed=yes:

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

Możesz powtórzyć te pola wiele razy, a ograniczenia są połączone operatorem OR, więc aby zdarzenia zostały zwrócone, muszą spełniać tylko jedno z ograniczeń. Poniższy przykład wyszukuje zdarzenia z właściwością prywatną petsAllowed=yes lub isOutside=yes:

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

Pamiętaj, że ograniczenia dotyczące usług prywatnych i udostępnionych są łączone za pomocą operatora AND, więc aby zdarzenia zostały zwrócone, muszą spełniać oba zestawy ograniczeń. Poniższy przykład wyszukuje zdarzenia z prywatną właściwością petsAllowed=yes i publiczną właściwością createdBy=myApp:

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

Limity

  1. Maksymalna długość klucza właściwości to 44 znaki. Właściwości z dłuższymi kluczami zostaną pominięte.
  2. Maksymalna długość wartości właściwości to 1024 znaki. Właściwości o dłuższych wartościach zostaną bez powiadomienia skrócone.
  3. Zdarzenie może mieć maksymalnie 300 właściwości o łącznym rozmiarze do 32 KB (rozmiar kluczy + rozmiar wartości). Te 300 właściwości obejmuje właściwości udostępnione i prywatne we wszystkich „kopiach” zdarzenia.