Proprietà estese

I campi delle risorse Event coprono i dati più comuni associati a un evento, come posizione, ora di inizio e così via, ma le applicazioni potrebbero voler memorizzare metadati aggiuntivi specifici per il loro caso d'uso. L'API Calendar offre la possibilità di impostare coppie chiave-valore nascoste con un evento, chiamate proprietà estese. Le proprietà estese semplificano la memorizzazione di dati specifici dell'applicazione per un evento senza dover utilizzare un database esterno.

Visibilità

Sono disponibili due tipi di proprietà estese: private e condivise. Le proprietà condivise sono visibili e modificabili da tutti i partecipanti a un evento, mentre le proprietà private vengono impostate sulla "copia " locale dell'evento di un partecipante. In particolare, le proprietà private sono specifiche per calendarId e eventId utilizzati nella richiesta, mentre le proprietà condivise vengono mostrate indipendentemente da calendarId utilizzato nella richiesta.

Aggiungere e aggiornare le proprietà

Le proprietà estese vengono impostate nella risorsa Eventi e, come altri campi, possono essere impostate nelle richieste insert, update e patch. L'utilizzo delle richieste di patch è il metodo preferito, in quanto consente di manipolare alcune proprietà lasciando invariate altre. L'aggiunta di una nuova proprietà con la stessa chiave sovrascriverà eventuali proprietà esistenti con la stessa chiave. L'esempio seguente mostra l'impostazione di una proprietà privata:

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

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

Eliminare le proprietà

Tutte le proprietà non incluse in una richiesta di aggiornamento verranno eliminate, ma un approccio migliore è inviare una richiesta di patch per impostare il valore su null. L'esempio seguente mostra l'eliminazione di una proprietà privata:

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

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

Cerca nelle proprietà

Puoi cercare gli eventi in base ai valori delle relative proprietà estese utilizzando una richiesta Events.list. Imposta il campo privateExtendedProperty o sharedExtendedProperty su un vincolo nel formato propertyName=value, che esegue ricerche rispettivamente in base alle proprietà private e condivise. Il seguente esempio restituisce gli eventi con la proprietà privata petsAllowed=yes:

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

Puoi ripetere questi campi più volte e i vincoli vengono combinati con l'operatore OR, pertanto gli eventi devono corrispondere a uno solo dei vincoli per essere restituiti. L'esempio seguente trova gli eventi con la proprietà privata petsAllowed=yes o isOutside=yes:

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

Tieni presente che i vincoli relativi alle proprietà private e condivise sono combinati con l'operatore AND, pertanto gli eventi devono corrispondere a entrambi gli insiemi di vincoli per essere restituiti. L'esempio seguente trova gli eventi con la proprietà privata petsAllowed=yes e la proprietà pubblica createdBy=myApp:

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

Limiti

1. La dimensione massima della chiave di una proprietà è 44 caratteri e le proprietà con chiavi più lunghe verranno eliminate in modo silenzioso.
2. La dimensione massima del valore di una proprietà è 1024 caratteri e le proprietà con valori più lunghi verranno troncate senza alcun messaggio.
3. Un evento può avere fino a 300 proprietà per un totale di massimo 32 kB (dimensioni chiavi + dimensioni valori). Queste 300 proprietà includono proprietà condivise e private, in tutte le "copie" dell'evento.