Partilhar via

Referência da API REST de propriedades estendidas do Outlook (beta)

  • Artigo

Aplica-se a: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Observação

Esta versão da documentação abrange a API REST de propriedades estendidas do Outlook na versão prévia. Os recursos de versão prévia estão sujeitos a alterações antes da finalização e podem fazer com que seu código deixe de funcionar. Por essa razão, em geral, você deve usar somente uma versão de produção de uma API em seu código de produção. Se disponível, a versão v2.0 é a preferida no momento.

A API REST de propriedades estendidas do Outlook permite que os aplicativos armazenem dados personalizados e forneçam mecanismo de fallback para acessar dados personalizados para propriedades do Outlook MAPI quando essas propriedades ainda não foram expostas nos metadados da API REST do Outlook. Você pode usar a API de propriedades estendidas para armazenar ou obter desses dados personalizados em uma mensagem, pasta de e-mail, evento, calendário, contatos, pasta de contato, tarefa ou pasta de tarefas na conta do usuário conectado. A conta pode estar no Office 365 ou em uma conta da Microsoft (Hotmail.com, Live.com, MSN.com, Outlook.com e Passport.com).

Observação

Para simplificar a referência, o restante deste artigo usa o "Outlook.com" para incluir esses domínios de conta da Microsoft.

Não tem interesse na versão beta da API? No sumário à esquerda, vá para a seção de Referência da API REST do Office 365 e selecione a versão desejada.

Utilização da API REST de propriedades estendidas

Propriedades estendidas ou extensões de dados?

Use as propriedades estendidas e esta API REST somente se você precisar acessar dados personalizados para propriedades MAPI do Outlook que ainda não estejam expostas por meio dos metadados da API REST do Outlook. Para a maioria dos cenários, você deve usar Extensões de dados do Office 365 e sua API REST para armazenar e acessar dados personalizados para itens na caixa de correio do usuário. Você pode verificar quais propriedades os metadados expõem em https://outlook.office.com/api/{version}/$metadata, substituindo {version} por v2.0, beta, etc., pela versão de sua escolha.

Autenticação

Como outras APIs REST do Outlook, para cada solicitação à API de Propriedades Estendidas, você deve incluir um token de acesso válido. A obtenção de um token de acesso exige que você registre e identifique seu aplicativo e obtenha a autorização adequada.

Você pode saber mais sobre algumas opções simplificadas de registro e autorização. Tenha isso em mente ao prosseguir com as operações específicas na API de Propriedades Estendidas.

Versão da API

Essa API foi promovida da versão prévia para o status de Disponibilidade Geral (GA). Há suporte nas versões v2.0 e beta da API REST do Outlook.

Recursos REST com suporte

Você pode criar propriedades estendidas para instâncias dos seguintes recursos:

O recurso deve estar na caixa de correio do usuário conectado no Office 365 ou no Outlook.com.

Parâmetros de URL

Os exemplos neste artigo usam os seguintes espaços reservados de ID em parâmetros de URLs de solicitação REST. Você deve especificar a ID da instância do recurso para o qual você deseja criar uma extensão.

Parâmetro Tipo Descrição
Parâmetros de URL
calendar_id sequência de caracteres A ID do calendário.
contact_id sequência de caracteres A ID do contato.
contactFolder_id sequência de caracteres A ID da pasta de contato.
event_id sequência de caracteres A ID do evento.
mailFolder_id sequência de caracteres A ID da pasta de e-mail.
message_id sequência de caracteres A ID da mensagem.
propertyId_value sequência de caracteres Um valor PropertyId em um dos formatos suportados.
property_value sequência de caracteres O valor de uma propriedade estendida.
task_id sequência de caracteres A ID da tarefa.
taskFolder_id sequência de caracteres A ID da pasta de tarefas.

Veja Usar a API REST do Outlook para obter mais informações comuns a todos os subconjuntos da API REST do Outlook.

Visão geral

Você pode criar e armazenar dinamicamente dados em uma propriedade estendida de uma instância de entidade. Dependendo se você pretende armazenar um único valor ou valores múltiplos (do mesmo tipo), você pode criar a propriedade estendida como uma SingleValueLegacyExtendedProperty ou MultiValueLegacyExtendedProperty.

Cada um desses tipos identifica a propriedade por sua PropertyId e armazena dados em Value.

Você pode usar a PropertyId para obter uma instância de entidade 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.

Observação

Não é possível usar a API REST para obter todas as propriedades estendidas de uma instância específica em uma única chamada.

Formatos PropertyId

Ao criar uma propriedade estendida de valor único ou vários valores, você pode especificar PropertyId em um dos dois formatos, com base em um nome de sequência de caracteres ou identificador numérico, e no tipo real de valor ou valores da propriedade. As próximas duas tabelas descrevem os formatos com suporte para especificar propriedades estendidas de valor único e vários valores. {_type_} representa o tipo de valor ou valores da propriedade. Os exemplos mostram a sequência de caracteres, o inteiro e as matrizes desses tipos.

Como propriedades estendidas, na maioria dos casos, interoperam com propriedades MAPI definidas não expostas nos metadados da API REST do Outlook, para manter a simplicidade, o formato escolhido deve refletir se a propriedade MAPI correspondente usa um valor numérico ou uma sequência de caracteres em seu identificador de propriedade MAPI. Você pode encontrar informações que precisaria para mapear uma propriedade estendida para uma propriedade MAPI existente, como o identificador de propriedade e o GUID, em [MS-OXPROPS] da Microsoft Corporation, "Lista de propriedade mestre de protocolos do Exchange Server".

Observação

Depois de escolher um formato para a PropertyId, você deve acessar essa propriedade estendida apenas com esse formato.

Formatos PropertyId 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 pelo namespace (o GUID) ao qual ela pertence e por um nome.
"{type} {guid} Id {id}" "Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012" Identifica uma propriedade pelo namespace (o GUID) ao qual ela pertence e por um identificador.

Formatos PropertyId 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 pelo namespace (o GUID) e por um nome.
"{type} {guid} Id {id}" "IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013" Identifica uma propriedade pelo namespace (o GUID) e por um identificador.

Operações de propriedade estendida

Criar propriedade estendida em um item existente

Criar uma ou mais propriedades estendidas para a instância especificada de um recurso suportado. Cada propriedade estendida pode ter um valor único ou vários valores.

PATCH https://outlook.office.com/api/beta/me/messages('{message_id}')
PATCH https://outlook.office.com/api/beta/me/events('{event_id}')
PATCH https://outlook.office.com/api/beta/me/contacts('{contact_id}')
PATCH https://outlook.office.com/api/beta/me/tasks('{task_id}')
PATCH https://outlook.office.com/api/beta/me/mailfolders('{mailFolder_id}')
PATCH https://outlook.office.com/api/beta/me/calendars('{calendar_id}')
PATCH https://outlook.office.com/api/beta/me/contactfolders('{contactFolder_id}')
PATCH https://outlook.office.com/api/beta/me/taskfolders('{taskFolder_id}')

Escopo mínimo necessário

Um dos escopos de leitura/gravação a seguir correspondente ao recurso de destino:

Parâmetro Tipo Descrição
Parâmetros de corpo
SingleValueExtendedProperties Coleção (SingleValueLegacyExtendedProperty) Uma matriz de uma ou mais propriedades estendidas de valor único.
PropertyId sequência de caracteres Para cada propriedade na coleção SingleValueExtendedProperties, especifique isso para identificar a propriedade. Deve seguir um dos formatos suportados para propriedades estendidas de valor único. Obrigatório.
Valor sequência de caracteres Para cada propriedade na coleção SingleValueExtendedProperties, especifique o valor da propriedade. Obrigatório.
MultiValueExtendedProperties Coleção (MultiValueLegacyExtendedProperty) Uma matriz de uma ou mais propriedades estendidas de vários valores.
PropertyId sequência de caracteres Para cada propriedade na coleção SingleValueExtendedProperties, especifique isso para identificar a propriedade. Deve seguir um dos formatos suportados para propriedades estendidas de múltiplos valores. Obrigatório.
Valor ​Coleção (sequência de caracteres) Para cada propriedade na coleção MultiValueExtendedProperties, especifique os valores para essa propriedade. Obrigatório.

Solicitação de exemplo

O primeiro exemplo cria uma propriedade estendida de valor único para a mensagem especificada. Essa propriedade estendida é o único elemento na matrizSingleValueExtendedProperties . O corpo da solicitação inclui o seguinte para a propriedade estendida:

  • PropertyId especifica o tipo de propriedade como string, o GUID, e a propriedade denominada Color.
  • Value especifica Green como o valor da propriedade Color.
PATCH https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')

Content-Type: application/json

{
  "SingleValueExtendedProperties": [
      {
         "PropertyId":"String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
         "Value":"Green"
      }
    ]
}

Resposta de exemplo

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 200 OK e inclui a mensagem especificada em seu corpo, semelhante à resposta da atualização de uma mensagem. A resposta não inclui a propriedade estendida recém-criada.

Solicitação de exemplo

O segundo exemplo cria uma propriedade estendida de vários valores para a mensagem especificada. Essa propriedade é o único elemento na matriz MultiValueExtendedProperties . O corpo da solicitação inclui:

  • PropertyId que especifica a propriedade como uma matriz da sequência de caracteres com o GUID especificado e o nome Palette.
  • Value que especifica Palette como uma matriz de 3 valores de sequência de caracteres, ["Green", "Aqua", "Blue"].
PATCH https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2_as77AACHsLrBBBA=')

Content-Type: application/json

{
  "MultiValueExtendedProperties": [
      {
         "PropertyId":"StringArray {66f5a359-4659-4830-9070-00049ec6ac6e} Name Palette",
         "Value":["Green", "Aqua", "Blue"]
      }
    ]
}

Resposta de exemplo

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 200 OK e inclui a mensagem especificada em seu corpo, semelhante à resposta da atualização de uma mensagem. A resposta não inclui a propriedade estendida recém-criada.

Para ver a propriedade estendida recém-criada, obtenha a mensagem expandida com a propriedade estendida.

Criar propriedade estendida em um novo item

Crie uma ou mais propriedades estendidas ao criar uma nova instância de um recurso suportado, tudo na mesma chamada POST. Inclua as propriedades ou a propriedade estendida no corpo da solicitação POST.

POST https://outlook.office.com/api/beta/me/messages
POST https://outlook.office.com/api/beta/me/events
POST https://outlook.office.com/api/beta/me/contacts
POST https://outlook.office.com/api/beta/me/tasks
POST https://outlook.office.com/api/beta/me/mailfolders
POST https://outlook.office.com/api/beta/me/calendars
POST https://outlook.office.com/api/beta/me/contactfolders
POST https://outlook.office.com/api/beta/me/taskfolders

Escopo mínimo necessário

Um dos escopos de leitura/gravação a seguir correspondente ao recurso de destino:

Parâmetro Tipo Descrição
Parâmetros de corpo
SingleValueExtendedProperties Coleção (SingleValueLegacyExtendedProperty) Uma matriz de uma ou mais propriedades estendidas de valor único.
PropertyId sequência de caracteres Para cada propriedade na coleção SingleValueExtendedProperties, especifique isso para identificar a propriedade. Deve seguir um dos formatos suportados para propriedades estendidas de valor único. Obrigatório.
Valor sequência de caracteres Para cada propriedade na coleção SingleValueExtendedProperties, especifique o valor da propriedade. Obrigatório.
MultiValueExtendedProperties Coleção (MultiValueLegacyExtendedProperty) Uma matriz de uma ou mais propriedades estendidas de vários valores.
PropertyId sequência de caracteres Para cada propriedade na coleção SingleValueExtendedProperties, especifique isso para identificar a propriedade. Deve seguir um dos formatos suportados para propriedades estendidas de múltiplos valores. Obrigatório.
Valor ​Coleção (sequência de caracteres) Para cada propriedade na coleção MultiValueExtendedProperties, especifique os valores para essa propriedade. Obrigatório.

Solicitação de exemplo

O primeiro exemplo cria um novo evento e uma propriedade estendida de valor único. Além das propriedades que você normalmente incluiria a um novo evento, o corpo da solicitação inclui a matriz SingleValueExtendedProperties que contém uma propriedade estendida de valor único e o seguinte para a propriedade:

  • PropertyId especifica o tipo de propriedade como string, o GUID, e a propriedade denominada Fun.
  • Value especifica Food como o valor da propriedade Fun.
POST https://outlook.office.com/api/beta/me/events

Content-Type: application/json

{
  "Subject": "Celebrate Thanksgiving",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together!"
  },
  "Start": {
      "DateTime": "2015-11-26T18:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-26T23:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    }
  ],
  "SingleValueExtendedProperties": [
     {
           "PropertyId":"String {66f5a359-4659-4830-9070-00040ec6ac6e} Name Fun",
           "Value":"Food"
     }
  ]
}

Resposta de exemplo

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 201 Created e inclui o novo evento em seu corpo, semelhante à resposta da criação de apenas um evento. A resposta não inclui propriedades estendidas recém-criadas.

Para ver a propriedade estendida recém-criada, obtenha o item expandido com a propriedade estendida.

Solicitação de exemplo

O segundo exemplo cria uma propriedade estendida de vários valores em um novo evento, todos na mesma operação POST. Além das propriedades que você normalmente incluiria para um novo evento, o corpo da solicitação inclui a matriz MultiValueExtendedPropertiesque contém uma propriedade estendida.

O corpo da solicitação inclui o seguinte para essa propriedade estendida de valores múltiplos:

  • PropertyId que especifica a propriedade como uma matriz da sequência de caracteres com o GUID especificado e o nome Recreation.
  • Value que especifica Recreation como uma matriz de 3 valores de sequência de caracteres, ["Food", "Hiking", "Swimming"].
POST https://outlook.office.com/api/beta/me/events

Content-Type: application/json

{
  "Subject": "Family reunion",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together this Thanksgiving!"
  },
  "Start": {
      "DateTime": "2015-11-26T09:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-29T21:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    },
    {
      "EmailAddress": {
        "Address": "Lauren@contoso.com",
        "Name": "Lauren Solis"
      },
      "Type": "Required"
    }
  ],
  "MultiValueExtendedProperties": [
     {
           "PropertyId":"StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
           "Value": ["Food", "Hiking", "Swimming"]
     }
  ]
}

Resposta de exemplo

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 201 Created e inclui o novo evento em seu corpo, semelhante à resposta da criação de apenas um evento. A resposta não inclui propriedades estendidas recém-criadas.

Para ver a propriedade estendida recém-criada, obtenha o item expandido com a propriedade estendida.

Obter item expandido com propriedade estendida

Obter uma instância de um recurso suportado expandido com a propriedade estendida especificada por um filtro na PropertyId.

A sequência de caracteres {propertyId_value} que você especifica no filtro para PropertyId deve seguir um dos formatos PropertyId suportados. Certifique-se de aplicar a codificação de URL aos caracteres de espaço na sequência de caracteres de filtro.

Expandir item com propriedades estendidas de valor único correspondentes

GET https://outlook.office.com/api/beta/me/messages('{message_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/events('{event_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/tasks('{task_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/mailfolders('{mailFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/calendars('{calendar_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contactfolders('{contactFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/taskfolders('{taskfolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

Expandir item com propriedades estendidas de vários valores correspondentes

GET https://outlook.office.com/api/beta/me/messages('{message_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/events('{event_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/tasks('{task_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/mailfolders('{mailFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/calendars('{calendar_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contactfolders('{contactFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/taskfolders('{taskfolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

Escopo mínimo necessário

Um dos escopos de leitura a seguir correspondente ao recurso de destino:

Solicitação de exemplo

O primeiro exemplo obtém e expande a mensagem especificada incluindo uma propriedade estendida de valor único. O filtro retorna a propriedade estendida que tem sua PropertyId correspondente à sequência de caracteres String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (com codificação de URL removida aqui para facilitar a leitura).

GET https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')?$expand=SingleValueExtendedProperties($filter=PropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color')

Resposta de exemplo

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 200 OK.

O corpo da resposta inclui todas as propriedades da mensagem especificada e a propriedade estendida retornada do filtro.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE1M2_bs88AACHsLqWAAA=')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H\"",
    "Id": "AAMkAGE1M2_bs88AACHsLqWAAA=",
    "CreatedDateTime": "2015-11-11T02:41:24Z",
    "LastModifiedDateTime": "2015-12-09T04:07:57Z",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H",
    "Categories": [
    ],
    "ReceivedDateTime": "2015-11-11T02:41:24Z",
    "SentDateTime": "2015-11-11T02:41:24Z",
    "HasAttachments": false,
    "InternetMessageId": "<SN2SR0101MB002977E7C30F9CA9AA55961484130@SN2SR0101MB0029.contoso.com>",
    "Subject": "RE: Talk about emergency prep",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=iso-8859-1\">\r\n<style type=\"text/css\" style=\"\">\r\n<!--\r\np\r\n\t{margin-top:0;\r\n\tmargin-bottom:0}\r\n-->\r\n</style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<hr tabindex=\"-1\" style=\"display:inline-block; width:98%\">\r\n<div id=\"divRplyFwdMsg\" dir=\"ltr\"><font face=\"Calibri, sans-serif\" color=\"#000000\" style=\"font-size:11pt\"><b>From:</b> Christine Irwin<br>\r\n<b>Sent:</b> Sunday, November 8, 2015 12:28:31 AM<br>\r\n<b>To:</b> Terrie Barrera<br>\r\n<b>Subject:</b> Talk about emergency prep<br>\r\n<b>When:</b> Sunday, November 8, 2015 7:00 PM-8:00 PM.<br>\r\n<b>Where:</b> The Commons</font>\r\n<div>&nbsp;</div>\r\n</div>\r\n<div>\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt; color:#000000; background-color:#FFFFFF; font-family:Calibri,Arial,Helvetica,sans-serif\">\r\n<p>Please see the attached before you come to the meeting.<br>\r\n</p>\r\n</div>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "________________________________",
    "Importance": "Normal",
    "ParentFolderId": "AQMkAGE1M2jgxCloXP1JupQN7j5uzzwAAAIBDwAAAA==",
    "Sender": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "From": null,
    "ToRecipients": [
        {
            "EmailAddress": {
                "Name": "Christine Irwin",
                "Address": "christine@contoso.com"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVlLTY0YjcxZWUzNTE1MAAQAHWT1sRiMChEmlQCIZUadoU=",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsRead": true,
    "IsDraft": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACHsLqWAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "HashtagDetailsPreview": null,
    "LikesPreview": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "UnsubscribeData": [
    ],
    "UnsubscribeEnabled": false,
    "SingleValueExtendedProperties@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkAGE1M2_bs88AACHsLqWAAA%3D')/SingleValueExtendedProperties",
    "SingleValueExtendedProperties": [
        {
            "PropertyId": "String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
            "Value": "Green"
        }
    ]
}

Solicitação de exemplo

O segundo exemplo obtém e expande o evento especificado incluindo uma propriedade estendida de vários valores. O filtro retorna a propriedade estendida que tem sua PropertyId correspondente à sequência de caracteres StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation (com codificação de URL removida aqui para facilitar a leitura).

GET https://outlook.office.com/api/beta/me/events('AAMkAGE1M2_bs88AACbuFiiAAA=')?$expand=MultiValueExtendedProperties($filter=PropertyId%20eq%20'StringArray%20{66f5a359-4659-4830-9070-00050ec6ac6e}%20Name%20Recreation')

Resposta de exemplo

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 200 OK.

O corpo da resposta inclui todas as propriedades do evento especificado e a propriedade estendida retornada do filtro.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE1M2_bs88AACbuFiiAAA=')",
    "@odata.etag": "W/\"mODEKWhc/Um6lA3uPm7PPAAAm8k15A==\"",
    "Id": "AAMkAGE1M2_bs88AACbuFiiAAA=",
    "CreatedDateTime": "2015-12-09T05:18:05.9477979Z",
    "LastModifiedDateTime": "2015-12-09T05:18:06.197802Z",
    "ChangeKey": "mODEKWhc/Um6lA3uPm7PPAAAm8k15A==",
    "Categories": [
    ],
    "OriginalStartTimeZone": "Pacific Standard Time",
    "OriginalEndTimeZone": "Pacific Standard Time",
    "ResponseStatus": {
        "Response": "Organizer",
        "Time": "0001-01-01T00:00:00Z"
    },
    "iCalUId": "04000000828A332796D9",
    "ReminderMinutesBeforeStart": 15,
    "IsReminderOn": true,
    "HasAttachments": false,
    "Subject": "Family reunion",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nLet's get together this Thanksgiving!\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "Let's get together this Thanksgiving!",
    "Importance": "Normal",
    "Sensitivity": "Normal",
    "Start": {
        "DateTime": "2015-11-26T17:00:00.0000000",
        "TimeZone": "UTC"
    },
    "End": {
        "DateTime": "2015-11-30T05:00:00.0000000",
        "TimeZone": "UTC"
    },
    "Location": {
        "DisplayName": ""
    },
    "IsAllDay": false,
    "IsCancelled": false,
    "IsOrganizer": true,
    "Recurrence": null,
    "ResponseRequested": true,
    "SeriesMasterId": null,
    "ShowAs": "Busy",
    "Type": "SingleInstance",
    "Attendees": [
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Terrie Barrera",
                "Address": "Terrie@contoso.com"
            }
        },
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Lauren Solis",
                "Address": "Lauren@contoso.com"
            }
        }
    ],
    "Organizer": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACbuFiiAAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
    "MultiValueExtendedProperties@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events('AAMkAGE1M2_bs88AACbuFiiAAA%3D')/MultiValueExtendedProperties",
    "MultiValueExtendedProperties": [
        {
            "PropertyId": "StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
            "Value": [
                "Food",
                "Hiking",
                "Swimming"
            ]
        }
    ]
}

Obter item por filtragem na propriedade estendida

Obter instâncias de um recurso suportado que tem a propriedade estendida especificada por um filtro em PropertyId e Value. O filtro é aplicado a todas as instâncias do recurso na caixa de correio do usuário conectado. Essa filtragem suporta apenas propriedades estendidas de valor único, mas não de vários valores.

A sequência de caracteres {propertyId_value} que você especifica no filtro para PropertyId deve seguir um dos formatos PropertyId suportados.

Se {property_value} não é uma sequência de caracteres, verifique se você converteu explicitamente ep/value para o tipo de dados do Edm apropriado ao compará-lo com {property_value}. Veja exemplos de solicitações para propriedades sem sequência de caracteres digitada abaixo para exemplos de tais conversões.

Certifique-se de aplicar a codificação de URL aos seguintes caracteres na sequência de caracteres de filtro: dois pontos, barra inclinada e espaço.

GET https://outlook.office.com/api/beta/me/messages?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/events?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/contacts?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/tasks?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/mailfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/calendars?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/contactfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/taskfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

Escopo mínimo necessário

Um dos escopos de leitura a seguir correspondente ao recurso de destino:

Solicitação de exemplo

O primeiro exemplo obtém mensagens que possuem a propriedade estendida de valor único com sequência de caracteres digitada especificada no filtro. O filtro procura a propriedade estendida com:

  • Sua PropertyId correspondente à sequência de caracteres String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (com codificação de URL removida aqui para facilitar a leitura).
  • Seu Value sendo a sequência de caracteres Green.
GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties%2FAny(ep%3A%20ep%2FPropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color'%20and%20ep%2FValue%20eq%20'Green')

Os próximos dois exemplos mostram como acessar mensagens que possuam propriedades estendidas de valor único sem sequência de caracteres digitada. Para facilitar a leitura, elas não incluem a codificação de URL necessária. O exemplo a seguir mostra um filtro que procura a propriedade estendida com:

  • Sua PropertyId correspondente à sequência de caracteres CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid.
  • Seu Value sendo o GUID b9cf8971-7d55-4b73-9ffa-a584611b600b. Para comparar o valor da propriedade com um GUID, converta ep/Value para Edm.Guid.
GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid' and cast(ep/Value, Edm.Guid) eq (b9cf8971-7d55-4b73-9ffa-a584611b600b))

O terceiro exemplo mostra um filtro que procura a propriedade estendida com:

  • Sua PropertyId correspondente à cadeia de caracteres Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete.
  • Seu Value igual ao inteiro 12. Para comparar o valor da propriedade com um inteiro, converta ep/Value para Edm.Int32.
GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete' and cast(ep/Value, Edm.Int32) eq 12)

Resposta de exemplo

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 200 OK e o corpo da resposta inclui todas as propriedades das mensagens cuja propriedade estendida corresponde ao respectivo filtro. O corpo da resposta é semelhante à resposta da obtenção de uma coleção de mensagens. A resposta não inclui a propriedade estendida correspondente.

Próximas etapas

Se você estiver pronto para começar a criar um aplicativo ou apenas quiser aprender mais, temos tudo o que você precisa.

Se preferir, aprenda mais sobre como usar a plataforma do Office 365: