Propriedades estendidas

Os campos dos recursos de eventos abrangem os dados mais comuns associados a um evento, como local, horário de início etc., mas os aplicativos podem querer armazenar metadados adicionais específicos para o caso de uso deles. A API Calendar permite definir pares de chave-valor ocultos com um evento, chamados de propriedades estendidas. As propriedades estendidas facilitam o armazenamento de dados específicos do aplicativo para um evento sem a necessidade de utilizar um banco de dados externo.

Visibilidade

Há dois tipos de propriedades estendidas disponíveis: particulares e compartilhadas. As propriedades compartilhadas são visíveis e editáveis por todos os participantes de um evento, enquanto as propriedades particulares são definidas na "cópia" local do evento de um participante. Mais concretamente, as propriedades particulares são específicas para calendarId e eventId usados na solicitação, enquanto as propriedades compartilhadas são mostradas independentemente do calendarId usado na solicitação.

Adicionar e atualizar propriedades

As propriedades estendidas são definidas no recurso Eventos e, assim como outros campos, podem ser definidas nas solicitações insert, update e patch. O método recomendado é o uso de solicitações de patch, porque ele permite que você manipule algumas propriedades enquanto mantém outras. Adicionar uma nova propriedade com a mesma chave substituirá todas as propriedades atuais com a mesma chave. O exemplo a seguir mostra a definição de uma propriedade particular:

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

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

Excluir propriedades

Todas as propriedades não incluídas em uma solicitação de atualização serão excluídas. No entanto, uma abordagem melhor é fazer uma solicitação de patch para definir o valor como nulo. O exemplo a seguir mostra como excluir uma propriedade particular:

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

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

Pesquisar propriedades

Pesquise eventos com base nos valores das propriedades estendidas usando uma solicitação Events.list. Defina o campo privateExtendedProperty ou sharedExtendedProperty como uma restrição no formato propertyName=value, que pesquisa propriedades particulares e compartilhadas, respectivamente. O exemplo a seguir retorna eventos com a propriedade particular petsAllowed=yes:

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

Você pode repetir esses campos várias vezes e as restrições são unidas por OR. Portanto, os eventos só precisam corresponder a uma das restrições a serem retornadas. O exemplo a seguir encontra eventos com a propriedade privada petsAllowed=yes ou isOutside=yes:

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

No entanto, as restrições em propriedades particulares e compartilhadas são unidas por AND. Portanto, os eventos precisam corresponder aos dois conjuntos de restrições para serem retornados. O exemplo a seguir encontra eventos com a propriedade privada petsAllowed=yes e a propriedade pública createdBy=myApp:

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

Limites

1. O tamanho máximo da chave de uma propriedade é de 44 caracteres, e as propriedades com chaves mais longas serão descartadas silenciosamente.
2. O tamanho máximo do valor de uma propriedade é de 1.024 caracteres, e propriedades com valores mais longos serão silenciosamente truncadas.
3. Um evento pode ter até 300 propriedades, totalizando até 32 KB de tamanho (tamanho das chaves + tamanho do valor). Essas 300 propriedades incluem propriedades compartilhadas e particulares em todas as "cópias" do evento.