Propiedades extendidas

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

Visibilidad

Hay dos tipos de propiedades extendidas disponibles: privadas y compartidas. Todos los asistentes de un evento pueden ver y editar las propiedades compartidas, mientras que las propiedades privadas se establecen en la "copia" local del evento de un asistente. Más precisamente, las propiedades privadas son específicas de los calendarId y eventId que se usan en la solicitud, mientras que las propiedades compartidas se mostrarán independientemente del calendarId que se use en la solicitud.

Cómo agregar y actualizar propiedades

Las propiedades extendidas se establecen en el recurso Eventos y, al igual que otros campos, se pueden configurar en las solicitudes de inserción, actualización y aplicación de parches. El uso de solicitudes de parches es el método preferido, ya que te permite manipular algunas propiedades y dejar otras sin modificar. 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"
    }
  }
}

Cómo borrar propiedades

Se borrarán todas las propiedades que no se incluyan en una solicitud de actualización, pero un mejor enfoque 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
    }
  }
}

Search properties

Puedes buscar eventos según los valores de sus propiedades extendidas con una solicitud Events.list. Establece el campo privateExtendedProperty o sharedExtendedProperty en una restricción con el formato propertyName=value, que realiza búsquedas en 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 combinan con la operación OR, por lo que los eventos solo deben coincidir con una de las restricciones para que se muestren. En el siguiente ejemplo, se encuentran 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 se combinan con el operador Y, por lo que los eventos deben coincidir con ambos conjuntos de restricciones para que se muestren. En el siguiente ejemplo, se encuentran 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 forma 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 de forma silenciosa.
3. Un evento puede tener hasta 300 propiedades que suman un tamaño de hasta 32 KB (tamaño de las claves + tamaño de los valores). Estas 300 propiedades incluyen propiedades privadas y compartidas en todas las "copias" del evento.