Proprietà estese

I campi delle risorse Eventi 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 l'archiviazione dei 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 di calendarId e eventId utilizzati nella richiesta, mentre le proprietà condivise verranno mostrate indipendentemente da calendarId utilizzato nella richiesta.

Aggiungere e aggiornare le proprietà

Le proprietà estese vengono impostate nella risorsa Events 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 intatte le altre. L'aggiunta di una nuova proprietà con la stessa chiave sovrascriverà 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"
    }
  }
}

Eliminare proprietà

Le proprietà non incluse in una richiesta di aggiornamento verranno eliminate, ma un approccio migliore è quello di 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 proprietà

Puoi cercare gli eventi in base ai valori delle loro proprietà estese utilizzando una richiesta Events.list. Imposta il campo privateExtendedProperty o sharedExtendedProperty su un vincolo nel formato propertyName=value, che esegue la ricerca 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 vengono combinati con l'operatore OR, quindi 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 vengono combinati con l'operatore AND, quindi gli eventi devono corrispondere a entrambi i gruppi 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à è di 44 caratteri e 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 32 kB di dimensioni (dimensione delle chiavi + dimensione dei valori). Queste 300 proprietà includono proprietà condivise e private in tutte le "copie" dell'evento.