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. A API Calendar oferece a capacidade 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 do evento de um participante. Mais concretamente, as propriedades privadas são específicas do calendarId e do eventId usados na solicitação, enquanto as propriedades compartilhadas serão mostradas independentemente do calendarId usado na solicitação.

Adicionar e atualizar propriedades

As propriedades estendidas são definidas no recurso de eventos e, como outros campos, podem ser definidas em solicitações de inserção, atualização e patch. O uso de solicitações de patch é o método preferido, porque permite manipular algumas propriedades sem alterar outras. A adição de uma nova propriedade com a mesma chave vai substituir as propriedades atuais com a mesma chave. O exemplo a seguir mostra a definição de uma propriedade privada:

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 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 como uma restrição no formato propertyName=value, que pesquisa propriedades privadas 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 unidas por 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

No entanto, as restrições em propriedades privadas 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 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 1024 caracteres, e as propriedades com valores mais longos serão truncadas silenciosamente.
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 privadas em todas as "cópias" do evento.