Właściwości rozszerzone

Pola zasobów zdarzeń obejmują najczęściej używane dane związane ze zdarzeniem, takie jak lokalizacja, czas rozpoczęcia itp., ale aplikacje mogą przechowywać dodatkowe metadane związane z ich przypadkiem użycia. Interfejs Calendar API umożliwia ustawianie ukrytych par klucz-wartość w zdarzeniu, zwanych właściwościami rozszerzonymi. Rozszerzone właściwości ułatwiają przechowywanie danych dotyczących konkretnej aplikacji na potrzeby zdarzenia bez konieczności korzystania z zewnętrznej bazy danych.

Widoczność

Dostępne są 2 typy rozszerzonych właściwości: prywatne i wspólne. Właściwości udostępnione są widoczne i edytowalne dla wszystkich uczestników wydarzenia, natomiast właściwości prywatne są ustawiane w lokalnej „kopii” wydarzenia danego uczestnika. W szczególności właściwości prywatne są specyficzne dla calendarId i eventId użytych w żądaniu, a właściwości udostępnione są wyświetlane niezależnie od calendarId użytego w żądaniu.

Dodawanie i aktualizowanie usług

Rozszerzone właściwości są ustawiane w zasobie Zdarzenia i podobnie jak inne pola mogą być ustawiane w żądaniach insert, update i patch. Korzystanie z żądań zmian jest preferowaną metodą, ponieważ umożliwia manipulowanie niektórymi właściwościami, nie zmieniając pozostałych. Dodanie nowej usługi z tym samym kluczem spowoduje zastąpienie wszystkich dotychczasowych usług o tym samym kluczu. Ten przykład pokazuje ustawienie właściwości prywatnej:

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

{
  "extendedProperties": {
    "private": {
      "petsAllowed": "yes"
    }
  }
}

Usuwanie usług

Właściwości, których nie ma w żądaniu aktualizacji, zostaną usunięte, ale lepiej jest przesłać żądanie 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
    }
  }
}

Właściwości wyszukiwania

Za pomocą żądania Events.list możesz wyszukiwać zdarzenia na podstawie wartości ich rozszerzonych właściwości. Ustaw pole privateExtendedProperty lub sharedExtendedProperty jako ograniczenie w formacie propertyName=value, które wyszukiwać będzie odpowiednio w przypadku właściwości prywatnych i współdzielonych. Ten 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 powtarzać te pola wiele razy, a ograniczenia są łączone za pomocą operatora LUB, więc aby zdarzenia zostały zwrócone, muszą pasować tylko do jednego z ograniczeń. W tym przykładzie znajdują się 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 właściwości prywatnych i wspólnych są łączone za pomocą operatora AND, więc aby zdarzenia mogły zostać zwrócone, muszą być zgodne z obu zestawami ograniczeń. W tym przykładzie znajdują się 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 o dłuższych kluczach zostaną pominięte.
2. Maksymalna wielkość wartości właściwości to 1024 znaki. Właściwości o dłuższych wartościach zostaną skrócone.
3. Zdarzenie może zawierać maksymalnie 300 właściwości o łącznej wielkości do 32 KB (rozmiar kluczy + rozmiar wartości). Te 300 właściwości obejmują właściwości wspólne i prywatne we wszystkich „kopiach” zdarzenia.