Compartilhar via

Referência de API REST de Extensões de dados do Office 365 (versão 2.0)

  • Artigo

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

A API REST de Extensões de Dados do Office 365 permite que os aplicativos armazenem dinamicamente dados personalizados em uma mensagem, evento ou contato da conta do usuário. A conta pode estar no Office 365 ou ser 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 v2.0 da API? No tabela de conteúdo à esquerda, vá para a seção Referência da API REST do Office 365 e selecione a versão desejada.

Visão geral

Uma extensão de dados na API REST do Outlook é um tipo aberto do OData v4 que contém propriedades que você pode especificar em tempo de execução. Você pode usar a API de extensões de dados para ampliar uma instância de um tipo de entidade já definido no Modelo de Dados de Entidade (EDM) - uma mensagem, evento ou contato - especificando dinamicamente propriedades e valores personalizados em uma carga útil JSON. Isso torna a definição desses tipos de entidades mais flexível, economizando tempo para definir novos tipos de entidade apenas para esse propósito.

A propriedade ExtensionName é a única propriedade definida para todas as extensões. Um modo de garantir que os nomes de extensão sejam exclusivos é usar um método reverso no sistema de nomes de domínio (DNS) que seja dependente do seu próprio domínio, por exemplo, Com.Contoso.Contact. Não use o domínio Microsoft em um nome de extensão.

Como uma extensão é um tipo aberto, você pode especificar dados adicionais específicos para uma instância de uma entidade. Por exemplo, você pode criar uma extensão para contatos comerciais individuais que rastreie dados personalizados, como nome da empresa e referenciador inicial, e especificar os dados na carga do JSON, conforme abaixo:

POST https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions
{
   @odata.type: "Microsoft.OutlookServices.OpenTypeExtension",  
   "ExtensionName": "Com.Contoso.Customer",
   "CompanyName": "Alpine Skis",
   "InitialReferrer":  "Robin McCall"
}

Você pode usar a API de Extensões de Dados para executar operações CRUD em um recurso novo ou existente. Leia mais sobre as operações suportadas.

Para obter mais informações sobre o tipo aberto OData, consulte a documentação do OData v4 em OData.org.

Usar a API REST de Extensões de Dados

Extensões de dados ou propriedades estendidas?

As extensões de dados são a solução recomendada para a maioria dos cenários que envolvem o armazenamento e o acesso a dados personalizados. Se, no entanto, você precisar acessar dados personalizados para as propriedades MAPI do Outlook que ainda não estejam expostas por meio dos metadados da API REST do Outlook, você poderá usar as propriedades estendidas e sua API REST. 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

Assim como acontece com outras APIs REST do Outlook, para cada solicitação à API de Extensões de Dados você deve incluir um token de acesso válido. Para obter um token de acesso você deve ter registrado e identificado o seu aplicativo e obtido a autorização adequada.

Saiba mais aqui 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 Extensões de Dados.

Recursos REST com suporte

Você pode criar extensões para instâncias dos seguintes recursos no ponto de extremidade REST do Outlook:

Versão da API

Essa API foi promovida da versão prévia para o status de Disponibilidade Geral (GA). É suportado nas versões v2.0 e beta:

https://outlook.office.com/api/v2.0/

https://outlook.office.com/api/beta/

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
contact_id sequência de caracteres A ID do contato.
event_id sequência de caracteres A ID do evento.
message_id sequência de caracteres A ID da mensagem.

Veja Use a API REST do Outlook para obter mais informações comuns a todos os subconjuntos da API REST do Outlook e da API REST de Extensões de Dados do Office 365.

Operações de extensão

Criar extensão em um item existente

Criar uma extensão e adicionar propriedades personalizadas para a instância especificada de um recurso. O recurso pode ser uma mensagem, um evento de calendário ou um contato no Office 365 ou no Outlook.com. Os dados na carga do JSON podem ser tipos primitivos ou matrizes de tipos primitivos.

Para criar uma extensão para cada um dos recursos suportados:

POST https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions
POST https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions
POST https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions

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
ExtensionName sequência de caracteres Um identificador de texto exclusivo para uma extensão. Obrigatório.

Exemplo de solicitação

Este exemplo cria uma extensão para a mensagem especificada. O corpo da solicitação inclui o seguinte para a extensão:

  • O tipo Microsoft.OutlookServices.OpenTypeExtension que é definido como sendo um tipo aberto OData nos metadados da API REST do Outlook.
  • O nome da extensão "Com.Contoso.Referral".
  • Dados adicionais a serem armazenados como propriedades customizadas na carga do JSON: CompanyName, DealValuee ExpirationDate que contêm tipos primitivos e TopModels e TopSalespersons que contêm matrizes de tipos primitivos.
POST https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions

Content-Type: application/json

{ 
  "@odata.type" : "Microsoft.OutlookServices.OpenTypeExtension", 
  "ExtensionName" : "Com.Contoso.Referral", 
  "CompanyName" : "Wingtip Toys",
  "DealValue@odata.type": "#Int64", 
  "DealValue" : 500050, 
  "ExpirationDate" : "2015-12-03T10:00:00.000Z",
  "TopModels": [
     3001,
     4002,
     5003
  ],
  "TopSalespersons": [
     "Dana Swope",
     "Fanny Downs",
     "Randi Welch"
  ]
}

Exemplo de resposta

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 201 Created.

O corpo da resposta inclui o seguinte para a nova extensão:

  • A propriedade padrão ExtensionName.
  • A propriedade Id com o nome totalmente qualificado de Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral.
  • Os dados personalizados a serem armazenados.
{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue@odata.type": "#Int64",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "TopModels@odata.type": "#Collection(Int32)",
    "TopModels": [
      3001,
      4002,
      5003
    ],
    "TopSalespersons@odata.type": "#Collection(String)",
    "TopSalespersons": [
      "Dana Swope",
      "Fanny Downs",
      "Randi Welch"
    ]
}

Criar extensão em um novo item

Crie uma ou mais extensões ao criar uma nova instância de um recurso, todas na mesma chamada POST e adicione propriedades personalizadas à extensão. O recurso pode ser uma mensagem, um evento de calendário ou um contato no Office 365 ou no Outlook.com. Os dados na carga do JSON podem ser tipos primitivos ou matrizes de tipos primitivos.

Para criar uma extensão para cada um dos recursos suportados, faça uma chamada POST semelhante à criação desse recurso e inclua uma extensão no corpo da solicitação POST.

POST https://outlook.office.com/api/v2.0/me/messages
POST https://outlook.office.com/api/v2.0/me/events
POST https://outlook.office.com/api/v2.0/me/contacts

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
ExtensionName sequência de caracteres Um identificador de texto exclusivo para uma extensão. Obrigatório.

Exemplo de solicitação

Este exemplo cria uma mensagem e uma extensão na mesma chamada. O corpo da solicitação inclui o seguinte:

  • As propriedades Subject, Body e ToRecipients típicas de uma nova mensagem.
  • E para a extensão:
    • O tipo Microsoft.OutlookServices.OpenTypeExtension que é definido como sendo um tipo aberto OData nos metadados da API REST do Outlook.
    • O nome da extensão "Com.Contoso.Referral".
    • Dados adicionais a serem armazenados como propriedades customizadas na carga do JSON: CompanyName, ExpirationDatee DealValue que contêm tipos primitivos e TopModels e TopSalespersons que contêm matrizes de tipos primitivos.
POST https://outlook.office.com/api/v2.0/me/messages

Content-Type: application/json

{
  "Subject": "Annual review",
  "Body": {
    "ContentType": "HTML",
    "Content": "You should be proud!"
  },
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "rufus@contoso.com"
      }
    }
  ],
  "Extensions": [
    {
      "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

Exemplo de resposta

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 201 Created.

O corpo da resposta inclui as propriedades da nova mensagem e o seguinte para a nova extensão:

  • A propriedade Id com o nome totalmente qualificado de Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral.
  • A propriedade padrão ExtensionName especificada na solicitação.
  • Os dados personalizados especificados na solicitação, armazenados como propriedades personalizadas.
{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')",
  "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj\"",
  "Id": "AAMkAGEbs88AAB84uLuAAA=",
  "CreatedDateTime": "2015-10-30T03:03:43Z",
  "LastModifiedDateTime": "2015-10-30T03:03:43Z",
  "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj",
  "Categories": [ ],
  "ReceivedDateTime": "2015-10-30T03:03:43Z",
  "SentDateTime": "2015-10-30T03:03:43Z",
  "HasAttachments": false,
  "Subject": "Annual review",
  "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\nYou should be proud!\r\n</body>\r
\n</html>\r\n"
  },
  "BodyPreview": "You should be proud!",
  "Importance": "Normal",
  "ParentFolderId": "AQMkAGEwAAAIBDwAAAA==",
  "Sender": null,
  "From": null,
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "rufus@contoso.com",
        "Name": "John Doe"
      }
    }
  ],
  "CcRecipients": [ ],
  "BccRecipients": [ ],
  "ReplyTo": [ ],
  "ConversationId": "AAQkAGEFGugh3SVdMzzc=",
  "IsDeliveryReceiptRequested": false,
  "IsReadReceiptRequested": false,
  "IsRead": true,
  "IsDraft": true,
  "WebLink": "https://outlook.office.com/owa/?
ItemID=AAMkAGEbs88AAB84uLuAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
  "MentionedMe": null,
  "Mentioned": [ ],
  "InferenceClassification": "Focused",
  "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages
('AAMkAGEbs88AAB84uLuAAA%3D')/Extensions",
  "Extensions": [
    {
      "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
      "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels@odata.type": "#Collection(Int32)",
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons@odata.type": "#Collection(String)",
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

Obter extensão

Obtenha uma extensão por nome ou ID na instância especificada de um recurso. O recurso pode ser uma mensagem, um evento de calendário ou um contato no Office 365 ou no Outlook.com.

Obter a extensão por nome ou por ID retorna o mesmo corpo de resposta.

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extensionId}')

Escopo mínimo necessário

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

Parâmetro Tipo Descrição
Parâmetro de URL
extensionId sequência de caracteres Pode ser um nome de extensão que seja um identificador de texto exclusivo entre todas as extensões em uma instância de recurso ou um nome completo que concatene o tipo de extensão e o identificador de texto exclusivo. O nome totalmente qualificado é retornado na propriedade id quando você cria a extensão. Obrigatório.

Exemplo de solicitação

O primeiro exemplo referencia uma extensão por seu nome e obtém a extensão da mensagem especificada.

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

O segundo exemplo referencia uma extensão pelo seu ID (nome totalmente qualificado) e obtém a extensão na mensagem especificada.

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Exemplo de resposta

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

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00Z"
}

Obter item expandido com extensão

Obter uma instância de um recurso expandido com a extensão especificada por um filtro no Id. O recurso pode ser uma mensagem, um evento de calendário ou um contato no Office 365 ou no Outlook.com.

Você pode filtrar no Id com o nome da extensão ou com o nome totalmente qualificado e, em seguida, obter a instância expandida com a extensão, conforme mostrado abaixo. Certifique-se de aplicar a codificação de URL aos caracteres de espaço na sequência de caracteres de filtro.

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

Escopo mínimo necessário

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

Parâmetro Tipo Descrição
Parâmetro de URL
extensionId sequência de caracteres Pode ser um nome de extensão que seja um identificador de texto exclusivo entre todas as extensões em uma instância de recurso ou um nome completo que concatene o tipo de extensão e o identificador de texto exclusivo. O nome totalmente qualificado é retornado na propriedade id quando você cria a extensão. Obrigatório.

Exemplo de solicitação

O exemplo a seguir obtém e expande a mensagem especificada incluindo a extensão retornada de um filtro. O filtro retorna a extensão em que Id corresponde a um nome totalmente qualificado.

Para sua conveniência, a solicitação é mostrada abaixo com a codificação de URL do caractere reservado, espaço.

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')?$expand=Extensions($filter=Id%20eq%20'Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Exemplo de resposta

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

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

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM\"",
    "Id": "AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM",
    "Categories": [
    ],
    "CreateDateTime": "2015-06-19T02:03:31Z",
    "LastModifiedDateTime": "2015-08-13T02:28:00Z",
    "Subject": "Attached is the requested info",
    "BodyPreview": "See the images attached.",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;\">\r\n<p>See the images attached. <br>\r\n</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "Importance": "Normal",
    "HasAttachments": true,
    "ParentFolderId": "AQMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===QAAAA==",
    "From": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "Sender": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "ToRecipients": [
        {
            "EmailAddress": {
                "Address": "wendy@contoso.com",
                "Name": "Wendy Molina"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===mivdTmQ=",
    "ReceivedDateTime": "2015-06-19T02:05:04Z",
    "SentDateTime": "2015-06-19T02:04:59Z",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsDraft": false,
    "IsRead": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===%2FNJTqt5NqHlVnKVBwCY4MQpaFz9SbqUDe4%2Bbs88AAAAAAEJAACY4MQpaFz9SbqUDe4%2Bbs88AAApA4JMAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Users('desmond40contoso.com')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions", 
    "Extensions": [ 
      { 
        "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
        "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
        "ExtensionName": "Com.Contoso.Referral",
        "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
        "CompanyName": "Wingtip Toys",
        "DealValue": 500050,
        "ExpirationDate": "2015-12-03T10:00:00Z"
      }
     ]
}

Encontre e expanda itens com uma extensão

Você pode encontrar instâncias de um recurso que contenham uma extensão correspondente a um filtro. Além disso, na mesma consulta, você pode obter essas instâncias expandidas com a extensão. As consultas nesta seção localizam essas instâncias, as expandem e incluem a extensão na resposta.

O recurso pode ser uma mensagem, um evento de calendário ou um contato no Office 365 ou no Outlook.com.

Você pode filtrar no Id com o nome da extensão ou com o nome totalmente qualificado e, em seguida, obter a instância expandida com a extensão, conforme mostrado abaixo. Certifique-se de aplicar a codificação de URL aos caracteres de espaço na sequência de caracteres de filtro.

GET https://outlook.office.com/api/v2.0/me/messages?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/events?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/contacts?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

Escopo mínimo necessário

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

Parâmetro Tipo Descrição
Parâmetro de URL
extensionId sequência de caracteres Pode ser um nome de extensão que seja um identificador de texto exclusivo entre todas as extensões em uma instância de recurso ou um nome completo que concatene o tipo de extensão e o identificador de texto exclusivo. O nome totalmente qualificado é retornado na propriedade id quando você cria a extensão. Obrigatório.

Exemplo de solicitação

O exemplo a seguir pesquisa todas as mensagens na caixa de correio do usuário conectado para localizar as que contêm uma extensão correspondente a um filtro e as expande incluindo a extensão. O filtro retorna extensões que tem o Id combinando o nome da extensão Com.Contoso.Referral.

Para sua conveniência, a solicitação é mostrada abaixo com a codificação de URL do caractere reservado, espaço.

GET https://outlook.office.com/api/v2.0/me/messages?$filter=Extensions/any(f:f/Id%20eq%20'Com.Contoso.Referral')&$expand=Extensions($filter=Id%20eq%20'Com.Contoso.Referral')

Exemplo de resposta

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

O corpo da resposta inclui todas as mensagens que possuem uma extensão correspondente e todas as propriedades da mensagem. Neste exemplo, a resposta contém duas mensagens.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages",
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.EventMessage",
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')",
            "@odata.etag": "W/\"DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn\"",
            "Id": "AAMkADIyDREAAA=",
            "CreatedDateTime": "2016-01-06T02:20:17Z",
            "LastModifiedDateTime": "2016-01-13T02:13:54Z",
            "ChangeKey": "DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:18Z",
            "SentDateTime": "2016-01-06T02:20:18Z",
            "HasAttachments": false,
            "InternetMessageId": "<BY1PR19MB0023E92E0B43F5E268406F0DF5F40@BY1PR19MB0023.namprd19.prod.outlook.com>",
            "Subject": "Accepted: Latin American Product Manual Group",
            "Body": {
                "ContentType": "Text",
                "Content": ""
            },
            "BodyPreview": "",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAAEJAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyWejUoYAg=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": true,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyDREAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "MeetingMessageType": "MeetingAccepted",
            "StartDateTime": {
                "DateTime": "2015-01-05T19:00:00.0000000",
                "TimeZone": "UTC"
            },
            "EndDateTime": {
                "DateTime": "2015-01-05T20:30:00.0000000",
                "TimeZone": "UTC"
            },
            "Location": {
                "DisplayName": "Mt. Adams"
            },
            "Type": "SeriesMaster",
            "Recurrence": {
                "Pattern": {
                    "Type": "RelativeMonthly",
                    "Interval": 2,
                    "Month": 0,
                    "DayOfMonth": 0,
                    "DaysOfWeek": [
                        "Monday"
                    ],
                    "FirstDayOfWeek": "Sunday",
                    "Index": "First"
                },
                "Range": {
                    "Type": "NoEnd",
                    "StartDate": "2015-01-05",
                    "EndDate": "0001-01-01",
                    "RecurrenceTimeZone": "tzone://Microsoft/Utc",
                    "NumberOfOccurrences": 0
                }
            },
            "IsOutOfDate": false,
            "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkADIyDREAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500300,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ],
            "Event@odata.associationLink": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')/$ref",
            "Event@odata.navigationLink": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')"
        },
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')",
            "@odata.etag": "W/\"CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq\"",
            "Id": "AAMkADIyAHVAAA=",
            "CreatedDateTime": "2016-01-06T02:20:02Z",
            "LastModifiedDateTime": "2016-01-13T02:24:50Z",
            "ChangeKey": "CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:02Z",
            "SentDateTime": "2016-01-06T02:20:01Z",
            "HasAttachments": false,
            "InternetMessageId": "<CY1PR19MB0032531C620A46068FDDD45DE3F40@CY1PR19MB0032.namprd19.prod.outlook.com>",
            "Subject": "International Launch Planning for XT2000",
            "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\nWe will be ready to ship XT 2000 on 10/1, how's the International launch plan going?<br>\r\n<div style=\"display:inline-block\">\r\n<table border=\"0\" cellspacing=\"0\" style=\"background-color:#F4F4F4\">\r\n<tbody>\r\n<tr>\r\n<td style=\"padding:20px; font-size:12px; color:#666666\">You're receiving this message because you're a subscribed member of the Engineering group.<br>\r\n<a href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=conversations&amp;source=EscalatedMessage\">View group conversations</a> |\r\n<a href=\"https://adatumltd.sharepoint.com/_layouts/groupstatus.aspx?id=dbcbe107-6244-40ba-b0f1-1c46ad35435d&amp;target=documents\">\r\nView group files</a> | <a id=\"BD5134C6-8D33-4ABA-A0C4-08581FDF89DB\" href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=unsubscribe&amp;source=EscalatedMessage\">\r\nUnsubscribe</a></td>\r\n</tr>\r\n</tbody>\r\n</table>\r\n</div>\r\n</body>\r\n</html>\r\n"
            },
            "BodyPreview": "We will be ready to ship XT 2000 on 10/1, how's the International launch plan going?\r\nYou're receiving this message because you're a subscribed member of the Engineering group.\r\nView group conversations | View group files | Unsubscribe",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAEMAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "Engineering",
                    "Address": "engineering@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "Garret Vargas",
                    "Address": "GarretV@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyLESZnSPc=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": false,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyAHVAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkADIyAHVAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500050,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ]
        }
    ]
}

Adicionar ou modificar dados em uma extensão

Atualizar uma extensão com as propriedades no corpo da solicitação:

  • Se uma propriedade no corpo da solicitação corresponder ao nome de uma propriedade existente na extensão, os dados na extensão serão atualizados.
  • Caso contrário, essa propriedade e seus dados serão adicionados à extensão.

O recurso pode ser uma mensagem, um evento de calendário ou um contato no Office 365 ou no Outlook.com. Pode ser referenciado por nome ou ID e, de qualquer forma, retorna a mesma resposta. Os dados na carga do JSON podem ser tipos primitivos ou matrizes de tipos primitivos.

PATCH https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extensionId}')

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âmetro de URL
extensionId sequência de caracteres Pode ser um nome de extensão que seja um identificador de texto exclusivo entre todas as extensões em uma instância de recurso ou um nome completo que concatene o tipo de extensão e o identificador de texto exclusivo. O nome totalmente qualificado é retornado na propriedade id quando você cria a extensão. Obrigatório.
Parâmetros de corpo
ExtensionName sequência de caracteres Um identificador de texto exclusivo para uma extensão. Obrigatório.

Exemplo de solicitação

Cada um dos dois exemplos nesta seção usa a extensão no Exemplo de extensão GET acima. A primeira referencia a extensão por nome, a segunda por ID. Seus corpos de solicitação e respostas são os mesmos.

Cada exemplo atualiza a extensão acima:

  • Alterando CompanyName de Wingtip Toys para Wingtip Toys (USA)
  • Alterando DealValue de 500050 para 500100
  • Adicionar novos dados como a propriedade personalizada Updated

Este exemplo faz referência à extensão por seu nome:

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

Este exemplo faz referência à extensão por sua ID (nome totalmente qualificado):

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

Exemplo de resposta

Uma resposta bem sucedida é indicada por um HTTP 200 OK código de resposta e a extensão atualizada no corpo da resposta.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": 500100,
    "ExpirationDate": "2015-12-03T10:00:00Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

Excluir uma extensão

Excluir uma extensão da instância especificada de um recurso. O recurso pode ser uma mensagem, um evento de calendário ou um contato no Office 365 ou no Outlook.com.

Para excluir uma extensão em uma instância de cada um dos recursos suportados:

DELETE https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extension_name}')

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 URL
extension_name sequência de caracteres Um identificador de texto exclusivo para uma extensão. Obrigatório.

Exemplo de solicitação

O exemplo a seguir referencia uma extensão pelo nome e exclui a extensão da mensagem especificada.

DELETE https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

Exemplo de resposta

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 204 No Content.

Entidades de extensão

Extensão

Tipo: Microsoft.OutlookServices.Entity

Uma entidade abstrata com a entidade Entity como tipo base.

OpenTypeExtension

Tipo: Microsoft.OutlookServices.Extension

Um tipo aberto e abstrato do OData v4 que suporta especificar propriedades e dados dinamicamente em uma carga útil JSON para atualizar uma instância de um tipo de entidade.

Propriedade Tipo Descrição Gravável? Filtrável?
ExtensionName sequência de caracteres Nome exclusivo da extensão. Use um sistema de nome de domínio reverso com base em seu próprio domínio, por exemplo, Com.Contoso.Contact. Sim Não

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: