Propriedades estendidas

Os campos dos recursos de eventos cobrem 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. A API Calendar permite definir pares de chave-valor ocultos com um evento, chamados de propriedades estendidas. Com as propriedades estendidas, é fácil armazenar dados específicos do aplicativo para um evento sem precisar usar 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 de um evento de um participante. Mais especificamente, as propriedades particulares são específicas do calendarId e do eventId usados na solicitação, enquanto as propriedades compartilhadas são mostradas independente do calendarId usado na solicitação.

Adicionar e atualizar propriedades

As propriedades estendidas são definidas no recurso "Events" e, como outros campos, podem ser definidas em solicitações insert, update e patch. Usar solicitações de patch é o método preferido, porque permite manipular algumas propriedades sem alterar outras. Adicionar uma nova propriedade com a mesma chave vai substituir as propriedades atuais com a mesma chave. O exemplo a seguir mostra como definir 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, mas 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

É possível pesquisar 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

É possível repetir esses campos várias vezes, e as restrições são combinadas com OR. Assim, os eventos só precisam corresponder a uma das restrições para serem retornados. O exemplo a seguir encontra eventos com a propriedade particular petsAllowed=yes ou isOutside=yes:

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

As restrições em propriedades particulares e compartilhadas são combinadas com AND. Portanto, os eventos precisam corresponder aos dois conjuntos de restrições para serem retornados. O exemplo a seguir encontra eventos com a propriedade particular 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 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 truncadas sem aviso prévio.
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.