Propiedades extendidas

Los campos de los recursos de Events abarcan los datos más comunes asociados con un evento, como la ubicación, la hora de inicio, etcétera, pero es posible que las aplicaciones deseen almacenar metadatos adicionales específicos para su caso de uso. La API de Calendar permite establecer 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

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

Cómo agregar y actualizar propiedades

Las propiedades extendidas se establecen en el recurso Events y, al igual que otros campos, se pueden establecer en las solicitudes insert, update y patch. El uso de solicitudes de parche es el método preferido, ya que te permite manipular algunas propiedades sin modificar otras. 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 establecer 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 como 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 según los valores de sus propiedades extendidas con una solicitud de Events.list. Establece el campo privateExtendedProperty o sharedExtendedProperty en una restricción con el formato propertyName=value, que busca en las propiedades privadas y compartidas, respectivamente. En el siguiente ejemplo, se muestran los 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 el operador OR, por lo que los eventos solo deben coincidir con una de las restricciones para devolverse. 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

Ten en cuenta que las restricciones sobre las propiedades privadas y compartidas se combinan con un AND, por lo que los eventos deben satisfacer ambos conjuntos de restricciones para devolverse. 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 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 con un tamaño total de hasta 32 KB (tamaño de las claves más el tamaño de los valores). Estas 300 propiedades incluyen propiedades compartidas y privadas en todas las "copias" del evento.