Partilhar via

Visão geral das propriedades estendidas do Outlook

  • Artigo

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Cuidado

As tarefas do Outlook foram preteridas e deixaram de devolver dados a 10 de agosto de 2022. Atualize as aplicações existentes que utilizam esta funcionalidade com tarefas do Outlook.

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:

Ou, nos seguintes recursos de grupo do Microsoft 365:

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

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 pela respetiva etiqueta 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 pela respetiva etiqueta 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.

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:

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