Proprietà estese

I campi delle risorse Eventi coprono i dati più comuni associati a un evento, come la località, l'ora di inizio e così via, ma le applicazioni potrebbero voler archiviare metadati aggiuntivi specifici per il loro caso d'uso. L'API Calendar offre la possibilità di impostare coppie chiave-valore nascoste con un evento, chiamato proprietà estese. Le proprietà estese semplificano l'archiviazione 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. Più concretamente, le proprietà private sono specifiche per calendarId e eventId utilizzate nella richiesta, mentre le proprietà condivise verranno mostrate indipendentemente dal calendarId utilizzato nella richiesta.

Aggiungere e aggiornare proprietà

Le proprietà estese vengono impostate nella risorsa Eventi e, come altri campi, possono essere impostati nelle richieste insert, update e patch. Il metodo preferito è l'utilizzo delle richieste di patch, poiché consente di manipolare alcune proprietà lasciandone altre invariate. L'aggiunta di una nuova proprietà con la stessa chiave sovrascriverà tutte le 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"
    }
  }
}

Elimina proprietà

Tutte le proprietà non incluse in una richiesta di aggiornamento vengono eliminate, ma un approccio migliore è effettuare 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 nelle loro proprietà estese utilizzando una richiesta Events.list. Imposta il campo privateExtendedProperty o sharedExtendedProperty su un vincolo nel formato propertyName=value, che cerca rispettivamente nelle proprietà private e condivise. Il seguente esempio restituisce 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 sono collegati tra loro con una relazione di tipo 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 sulle proprietà private e condivise sono collegati tra loro tramite AND, pertanto gli eventi devono corrispondere a entrambi gli insiemi di vincoli per poter 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à è di 44 caratteri, mentre le proprietà con chiavi più lunghe verranno eliminate automaticamente.
2. La dimensione massima del valore di una proprietà è 1024 caratteri e le proprietà con valori più lunghi verranno troncate automaticamente.
3. Un evento può avere fino a 300 proprietà per un totale di dimensioni fino a 32 kB (dimensioni chiavi + dimensione valore). Queste 300 proprietà includono proprietà condivise e private in tutte le "copie" dell'evento.