Właściwości rozszerzone

Pola zasobów zdarzeń obejmują najczęstsze dane związane ze zdarzeniem, takie jak lokalizacja, czas rozpoczęcia itp., ale aplikacje mogą chcieć przechowywać dodatkowe metadane dostosowane do swojego przypadku użycia. Interfejs Calendar API umożliwia ustawianie ukrytych par klucz-wartość w wydarzeniu nazywanych właściwościami rozszerzonymi. Rozszerzone właściwości ułatwiają przechowywanie danych specyficznych dla aplikacji dotyczących zdarzenia bez konieczności korzystania z zewnętrznej bazy danych.

Widoczność

Dostępne są 2 rodzaje usług rozszerzonych: prywatne i udostępniane. Udostępnione właściwości są widoczne i możliwe do edytowania dla wszystkich uczestników wydarzenia, a właściwości prywatne są ustawiane na lokalnej „kopie” wydarzenia jednego uczestnika. Dokładniej rzecz ujmując, właściwości prywatne dotyczą tylko właściwości calendarId i eventId użytych w żądaniu, a współdzielone usługi są wyświetlane niezależnie od pola calendarId użytego w żądaniu.

Dodawanie i aktualizowanie właściwości

Właściwości rozszerzone są ustawiane w zasobie zdarzeń i tak jak inne pola można ustawiać w żądaniach insert, update i poprawek. Preferowaną metodą jest użycie żądań poprawki, ponieważ umożliwia manipulowanie niektórymi właściwościami, a inne pozostawia bez zmian. Dodanie nowej usługi z tym samym kluczem spowoduje zastąpienie istniejących usług o tym samym kluczu. Oto przykład konfigurowania usługi prywatnej:

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

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

Usuń właściwości

Wszystkie właściwości, które nie zostały uwzględnione w żądaniu aktualizacji, zostaną usunięte, ale lepiej wysłać żądanie poprawki z wartością null. Oto przykład usuwania usługi prywatnej:

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

{
  "extendedProperties": {
    "private": {
      "petsAllowed": null
    }
  }
}

Wyszukaj właściwości

Zdarzenia możesz wyszukiwać na podstawie wartości z ich właściwości rozszerzonych, używając żądania Events.list. Ustaw w polu privateExtendedProperty lub sharedExtendedProperty ograniczenie w formacie propertyName=value, które wyszukuje je odpowiednio według właściwości prywatnych i udostępnianych. 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ą połączone operatorem LUB, więc zdarzenia muszą pasować tylko do jednego z ograniczeń, aby zostały zwrócone. Ten przykład znajduje 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 udostępnianych są połączone operatorem ORAZ, więc aby zdarzenia były zwracane, muszą pasować do obu zestawów ograniczeń. Ten przykład znajduje zdarzenia z właściwościami prywatną petsAllowed=yes i publicznymi createdBy=myApp:

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

Ograniczenia

1. Maksymalny rozmiar klucza usługi to 44 znaki. Właściwości z dłuższymi kluczami są pomijane dyskretnie.
2. Maksymalny rozmiar wartości właściwości to 1024 znaki, a usługi o dłuższych wartościach będą dyskretnie obcinane.
3. Zdarzenie może mieć maksymalnie 300 właściwości o łącznym rozmiarze do 32 kB (rozmiar kluczy + rozmiar wartości). Te 300 usług obejmuje wszystkie „kopie” wydarzenia.