Propiedades extendidas

Los campos de los recursos de eventos cubren los datos más comunes asociados con un evento, como la ubicación, la hora de inicio, etc., pero es posible que las aplicaciones quieran almacenar metadatos adicionales específicos de su caso de uso. La API de Calendar permite configurar pares clave-valor ocultos con un evento, denominados propiedades extendidas. Las propiedades extendidas facilitan el almacenamiento de datos específicos de la aplicación para un evento sin tener que utilizar una base de datos externa.

Visibilidad

Hay dos tipos de propiedades extendidas disponibles: privadas y compartidas. Las propiedades compartidas son visibles y editables para todos los asistentes a un evento, mientras que las propiedades privadas se establecen en la "copia" local de un asistente. De manera más concreta, las propiedades privadas son específicas de calendarId y eventId que se usan en la solicitud, mientras que las propiedades compartidas se mostrarán sin importar el calendarId que se use en la solicitud.

Cómo agregar y actualizar propiedades

Las propiedades extendidas se establecen en el recurso de eventos y, al igual que otros campos, se pueden configurar en las solicitudes insert, update y patch. El uso de solicitudes de parches es el método preferido, ya que te permite manipular algunas propiedades y dejar otras intactas. Si agregas una propiedad nueva con la misma clave, se reemplazarán las propiedades existentes con la misma clave. En el siguiente ejemplo, se muestra cómo configurar una propiedad privada:

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

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

Borrar propiedades

Se borrarán todas las propiedades que no estén incluidas en una solicitud de actualización, pero un enfoque mejor es realizar una solicitud de parche para establecer el valor en nulo. En el siguiente ejemplo, se muestra cómo borrar una propiedad privada:

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

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

Buscar propiedades

Puedes buscar eventos en función de los valores de sus propiedades extendidas mediante una solicitud de Events.list. Establece el campo privateExtendedProperty o sharedExtendedProperty en una restricción del formato propertyName=value, que busca propiedades privadas y compartidas, respectivamente. En el siguiente ejemplo, se muestran eventos con la propiedad privada petsAllowed=yes:

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

Puedes repetir estos campos varias veces y las restricciones se unen con el operador O, por lo que los eventos solo deben coincidir con una de las restricciones para que se muestre. En el siguiente ejemplo, se buscan eventos con la propiedad privada petsAllowed=yes o isOutside=yes:

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

Sin embargo, ten en cuenta que las restricciones de las propiedades privadas y compartidas están juntas mediante el operador Y, por lo que los eventos deben coincidir con ambos conjuntos de restricciones para mostrarse. En el siguiente ejemplo, se buscan eventos con la propiedad privada petsAllowed=yes y la propiedad pública createdBy=myApp:

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

Límites

1. El tamaño máximo de la clave de una propiedad es de 44 caracteres, y las propiedades con claves más largas se descartarán de manera silenciosa.
2. El tamaño máximo del valor de una propiedad es de 1,024 caracteres, y las propiedades con valores más largos se truncarán silenciosamente.
3. Un evento puede tener hasta 300 propiedades con un total de hasta 32 KB (tamaño de las claves + tamaño del valor). Estas 300 propiedades incluyen propiedades compartidas y privadas en todas las "copias" del evento.