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 outros metadados específicos do caso de uso. A API Calendar oferece a possibilidade de definir pares de chave-valor ocultos com um evento, chamados propriedades estendidas. As propriedades estendidas facilitam o armazenamento de 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: privadas e compartilhadas. As propriedades compartilhadas são visíveis e editáveis por todos os participantes de um evento, enquanto as propriedades privadas são definidas na "cópia" local de um participante do evento. Mais especificamente, as propriedades privadas são específicas para o calendarId e o 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, como outros campos, podem ser definidas em solicitações de inserção, atualização e patch. O uso de solicitações de correção é o método preferencial, porque permite manipular algumas propriedades e deixar outras intocadas. Adicionar uma nova propriedade com a mesma chave vai substituir todas as propriedades existentes com a mesma chave. O exemplo a seguir mostra como definir uma propriedade privada:

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

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

Excluir propriedades

Todas as propriedades que não forem 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 a exclusão de 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 para uma restrição no formato propertyName=value, que pesquisa propriedades privadas e compartilhadas, respectivamente. O exemplo a seguir retorna eventos com a propriedade privada 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 agrupadas por OR. Portanto, 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

No entanto, as restrições em propriedades privadas e compartilhadas são AND'ed juntas. 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 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 as propriedades com valores mais longos serão truncadas silenciosamente.
3. Um evento pode ter até 300 propriedades, totalizando até 32 KB (tamanho das chaves + tamanho dos valores). Essas 300 propriedades incluem propriedades compartilhadas e privadas em todas as "cópias" do evento.