Compartilhar via

Obter identificações imutáveis para recursos do Outlook

  • Artigo

Itens do Outlook (mensagens, eventos, contatos, tarefas) têm um comportamento interessante que você provavelmente nunca percebeu ou que lhe causou frustração significativa: suas IDs se alteram. Isso não acontece com frequência, somente se o item é movido, mas pode causar problemas reais para aplicativos que armazenam IDs offline para uso posterior. IDs (identificadores imutáveis) permitem que seu aplicativo obtenha uma ID que não seja alterada durante o tempo de vida do item.

Observação

Identificadores imutáveis, como todos os identificadores no Microsoft Graph, diferenciam maiúsculas de minúsculas. Lembre-se disso se você estiver comparando IDs.

Como funciona

A ID imutável é um recurso opcional do Microsoft Graph. Para aceitar, seu aplicativo deve enviar um cabeçalho HTTP adicional em suas solicitações de API:

Prefer: IdType="ImmutableId"

Esse cabeçalho só se aplica à solicitação com a qual ele está incluído. Se quiser usar IDs imutáveis, você deverá incluir esse cabeçalho com todas as solicitações de API.

Tempo de vida das IDs imutáveis

A ID imutável de um item não será alterada desde que o item permaneça na mesma caixa de correio. Isso significa que a ID imutável NÃO será alterada se o item for movido para uma pasta diferente na caixa de correio. No entanto, a ID imutável será alterada se:

  • O usuário mover o item para uma caixa de correio de arquivo morto.
  • O usuário exportar o item (para um PST, como um arquivo MSG, etc.) e importá-lo novamente na sua caixa de correio.

Itens que dão suporte a IDs imutáveis

Os seguintes itens dão suporte a IDs imutáveis:

Os tipos de contêiner (mailFolder, calendário etc.) não dão suporte à ID imutável, mas suas IDs regulares já eram constantes.

ID imutável com o envio de e-mails

Você pode usar IDs imutáveis para localizar uma mensagem na pasta Itens enviados após ela ter sido enviada, usando as seguintes etapas:

  1. Crie uma mensagem de rascunho usando o Prefer: IdType="ImmutableId"cabeçalho e salve a id propriedade da mensagem na resposta.
  2. Envie a mensagem usando a ID da etapa anterior.
  3. Obtenha a mensagem usando a ID da primeira etapa. Esta é a cópia em Itens Enviados.

Observação

Obter a mensagem em Itens Enviados pode não ter êxito imediatamente após o envio da mensagem. A cópia da mensagem não será criada até que a mensagem seja enviada com êxito, o que pode levar algum tempo.

ID imutável com notificações de alteração

Você pode solicitar que o Microsoft Graph envie IDs imutáveis em notificações de alteração, incluindo o cabeçalho Prefer: IdType="ImmutableId" ao criar uma assinatura. As assinaturas existentes criadas sem o cabeçalho continuam a usar o formato de ID padrão. Para fazer com que as assinaturas existentes passem a usar IDs imutáveis, você precisa excluí-las e recriá-las usando o cabeçalho.

ID imutável com a consulta delta

Ao incluir o cabeçalho Prefer: IdType="ImmutableId", você pode solicitar que o Microsoft Graph retorne IDs imutáveis em respostas de consulta delta para tipos de recursos compatíveis. Os @odata.nextLink valores e @odata.deltaLink retornados por consultas delta são compatíveis com ambos os formatos de ID, portanto, seu aplicativo não precisa sincronizar novamente para aproveitar a ID imutável. Você pode usar o cabeçalho para obter as IDs imutáveis de agora em diante e pode atualizar o armazenamento do aplicativo separadamente.

Atualização de dados existentes

Se você já tem um banco de dados preenchido com milhares de IDs normais, pode migrar essas IDs para o formato imutável usando a função translateExchangeIds. Você pode fornecer uma matriz de até 1.000 IDs para serem convertidas em um formato de destino.

Observação

Você também pode usar translateExchangeIds para migrar aplicativos dos Serviços Web do Exchange para o Microsoft Graph.

Exemplo

O exemplo a seguir transforma uma ID normal do Microsoft Graph em imutável.

Solicitação

POST https://graph.microsoft.com/v1.0/me/translateExchangeIds

{
  "inputIds" :
  [
    "AQMkAGM2…"
  ],
  "targetIdType" : "restImmutableEntryId",
  "sourceIdType" : "restId"
}

Resposta

HTTP 200 OK

{
  "value": [
    {
      "targetId": "AAkALgAA...",
      "sourceId": "AQMkAGM2..."
    }
  ]
}