Visão geral das propriedades estendidas do Outlook

Namespace: microsoft.graph

As propriedades expandidas permitem armazenar dados personalizados e servem especificamente como um mecanismo de contingência para que as aplicações acedam a dados personalizados para propriedades MAPI do Outlook quando estas propriedades ainda não estão expostas no metadata_ da Microsoft Graph API. Você pode usar a API REST de propriedades estendidas para armazenar ou obter esses dados personalizados nos seguintes recursos de usuário:

• message
• mailFolder
• event
• calendar
• contact
• contactFolder
• Tarefa do Outlook
• Pasta de tarefas do Outlook

Ou, nos seguintes recursos de grupo do Microsoft 365:

• grupo event
• grupo calendar
• grupo post

Usar propriedades estendidas ou extensões abertas?

Nos cenários mais comuns, deve conseguir utilizar extensões abertas ( representadas por openTypeExtension, anteriormente conhecidas como extensões de dados do Office 365) para armazenar e aceder a dados personalizados para instâncias de recursos na caixa de correio de um utilizador. Utilize propriedades expandidas apenas se precisar de aceder a dados personalizados para propriedades MAPI do Outlook que ainda não estejam expostas nos metadados da API do Microsoft Graph.

Tipos de propriedades estendidas

Dependendo se você pretende armazenar um único valor ou vários valores (do mesmo tipo) em uma propriedade estendida, pode criar uma propriedade estendida como uma singleValueLegacyExtendedProperty ou uma multiValueLegacyExtendedProperty.

Cada um desses tipos identifica a propriedade por sua id e armazena dados em value.

Você pode usar id para obter uma instância de recurso específica em conjunto com essa propriedade estendida ou para filtrar em uma propriedade estendida de valor único para obter todas as instâncias que possuem essa propriedade.

Nota Não pode utilizar a API REST para obter todas as propriedades expandidas de uma instância específica numa chamada.

formatos de id

Você pode especificar o id de uma propriedade estendida em um dos três formatos:

• Como uma propriedade nomeada, identificada pelo tipo de propriedade estendida, namespace e nome de uma cadeia de caracteres.
• Como uma propriedade nomeada, identificada pelo tipo de propriedade estendida, namespace e um identificador numérico.
• Em um formato de proptag, identificado pelo tipo de propriedade estendida e uma marca de propriedade MAPI.

As duas tabelas seguintes descrevem estes formatos como aplicados a propriedades expandidas de valor único e múltiplo. {tipo} representa o tipo de valor ou valores da propriedade estendida. Os exemplos mostram a cadeia de caracteres, inteiro e matrizes desses tipos.

Formatos de id válidos para propriedades estendidas de valor único

Formatos de id válidos para propriedades estendidas de vários valores

Use qualquer um dos formatos de propriedade nomeada para definir uma propriedade estendida de valor único ou vários valores como uma propriedade personalizada. Entre os dois formatos, o primeiro que leva o nome da cadeia de caracteres (Nome) é o formato preferencial para facilitar a referência. Propriedades nomeadas tem seus identificadores de propriedade no intervalo 0x8000-0xfffe.

Utilize o formato de proptag para aceder às propriedades predefinidas pela MAPI ou por um cliente ou servidor e que ainda não tenham sido expostas no Microsoft Graph. Essas propriedades tem identificadores de propriedade no intervalo 0x0001-0x7fff. Não tente definir uma propriedade personalizada com o formato proptag.

Pode encontrar informações sobre o mapeamento de uma propriedade expandida para uma propriedade MAPI existente, como o identificador de propriedade e o GUID, em [MS-OXPROPS] Microsoft Corporation, "Lista de Propriedades Mestra de Protocolos do Exchange Server".

Observação Depois de escolher um formato para a id, você deve acessar essa propriedade estendida apenas com esse formato.

Operações da API REST

Operações de propriedades estendidas de valor único:

• Criar uma propriedade estendida em uma instância de recurso nova ou existente
• Obter uma instância de recurso, ou uma coleção delas, com uma propriedade estendida usando $expand ou $filter

Operações de propriedades estendidas de vários valores:

• Criar uma propriedade estendida em uma instância de recurso nova ou existente
• Obter uma instância de recurso com uma propriedade estendida usando $expand.