Visão geral das propriedades estendidas do Outlook

  • Artigo

Namespace: microsoft.graph

Propriedades estendidas permitem armazenar dados personalizados e servem especificamente como um mecanismo de fallback para aplicativos acessarem dados personalizados para propriedades MAPI do Outlook quando essas propriedades ainda não estiverem expostas no Microsoft API do Graph metadata_. Você pode usar a API REST de propriedades estendidas para armazenar ou obter esses dados personalizados nos seguintes recursos de usuário:

Ou, nos seguintes recursos de grupo do Microsoft 365:

Usar propriedades estendidas ou extensões abertas?

Na maioria dos cenários comuns, você deve ser capaz de usar extensões abertas (representadas pelo openTypeExtension, anteriormente conhecido como Office 365 extensões de dados) para armazenar e acessar dados personalizados para instâncias de recurso na caixa de correio de um usuário. Use propriedades estendidas somente se precisar acessar dados personalizados para propriedades MAPI do Outlook que ainda não estão expostas nos metadados do Microsoft API do 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 Você não pode usar a API REST para obter todas as propriedades estendidas de uma instância específica em uma 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 próximas tabelas descrevem esses formatos como aplicados a propriedades estendidas de vários valores e únicos. {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

Formato Exemplo Descrição
"{type} {guid} Name {name}" "String {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" Identifica uma propriedade namespace (GUID) à qual ele pertence, e um nome de cadeia de caracteres.
"{type} {guid} Id {id}" "Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012" Identifica uma propriedade namespace (GUID) à qual ele pertence, e um identificador numérico.
"{type} {proptag}" "String 0x4001" Identifica uma propriedade predefinida por sua marca de propriedade.

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

Formato Exemplo Descrição
"{type} {guid} Name {name}" "StringArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" Identifica uma propriedade namespace (GUID) e um nome de cadeia de caracteres.
"{type} {guid} Id {id}" "IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013" Identifica uma propriedade namespace (GUID) e um identificador numérico.
"{type} {proptag}" "StringArray 0x4002" Identifica uma propriedade predefinida por sua marca de propriedade.

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.

Use o formato proptag para acessar propriedades predefinidas pelo MAPI ou por um cliente ou servidor e que ainda não foram expostas no Microsoft Graph. Essas propriedades tem identificadores de propriedade no intervalo 0x0001-0x7fff. Não tente definir uma propriedade personalizada usando o formato proptag.

Você pode encontrar informações sobre como mapear uma propriedade estendida para uma propriedade MAPI existente, como o identificador de propriedade e GUID, em [MS-OXPROPS] Microsoft Corporation, "Exchange Server Protocols Master Property List".

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:

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