Obter as alterações incrementais para as mensagens em uma pasta

  • Artigo

A consulta delta permite consultar adições, exclusões ou atualizações de mensagens em uma pasta, por meio de uma série de chamadas de função delta. Os dados delta permitem manter e sincronizar um armazenamento local de mensagens do usuário, sem ter de buscar todo o conjunto de mensagens do usuário no servidor a cada vez que precise deles.

Sincronizar itens de mensagem em um repositório local pode usar a consulta delta para a sincronização completa inicial e sincronizações incrementais subsequentes. Normalmente, você faria uma sincronização total inicial de todas as mensagens em uma pasta (por exemplo, a caixa de entrada do usuário) e, em seguida, obteria alterações incrementais nessa pasta periodicamente.

Para obter alterações incrementais de apenas um determinado tipo - mensagens que são criadas, atualizadas ou excluídas desde a sincronização inicial - faça uma rodada inicial de sincronização de todas as mensagens na pasta e, em seguida, obtenha alterações incrementais de um tipo desejado específico nas rodadas subsequentes. Especifique o tipo de alteração desejado como uma opção de consulta na solicitação delta inicial; O Microsoft Graph codifica automaticamente todas as opções de consulta personalizada e OData @odata.nextLink no ou @odata.deltaLink fornecido na resposta.

Controlar mensagens de alterações em uma pasta

A consulta delta é uma operação por pasta. Para controlar as alterações das mensagens em uma hierarquia de pastas, você precisa controlar cada pasta individualmente.

O rastreamento de alterações de mensagem em uma paste de email corresponde a uma série de solicitações GET com a função delta. A solicitação GET inicial é muito semelhante à maneira como você obtém mensagens, exceto se você incluir a função delta:

GET https://graph.microsoft.com/v1.0/me/mailFolders/{id}/messages/delta

Uma solicitação GET com a função delta retorna:

  • Uma @odata.nextLink (que contém uma URL com chamada de função delta e um skipToken) ou
  • Uma @odata.deltaLink (que contém uma URL com chamada de função delta e deltaToken).

Esses tokens são tokens de estado opacos para o cliente. Para prosseguir com uma rodada de controle de alterações, copie e aplique a URL retornada da última solicitação GET para a próxima chamada de função delta para a mesma pasta. Um @odata.deltaLink retornado em uma resposta significa que a fase atual do rastreamento de alterações está concluída. Você pode salvar e usar a URL @odata.deltaLink quando começar a próxima fase.

O restante deste artigo inclui dois exemplos:

  • Confira o exemplo 1 para saber como usar as @odata.nextLink URLs e @odata.deltaLink .
  • Confira o exemplo 2 para saber como obter somente mensagens criadas incrementalmente desde a rodada inicial.

Use os parâmetros de consulta em uma consulta delta para mensagens

  • Você pode usar um parâmetro de consulta $select como em qualquer solicitação GET para especificar somente as propriedades necessárias para obter melhor desempenho. A id propriedade sempre é retornada.
  • Suporte à consulta delta $select, $top e $expand para mensagens.
  • Há suporte limitado para $filter e $orderby:
    • As únicas expressões $filter com suporte são $filter=receivedDateTime+ge+{value} ou $filter=receivedDateTime+gt+{value}.
    • A aplicação de $filter em uma consulta Delta retorna apenas até 5.000 mensagens.
    • A única expressão $orderby suportada é $orderby=receivedDateTime+desc. Se você não incluir uma expressão $orderby , a ordem de retorno não será garantida.
  • Não há suporte para $search.

Além disso, para retornar apenas determinado tipo de alterações (criadas, atualizadas ou excluídas) na resposta da consulta delta, você pode, opcionalmente, filtrar o tipo de alteração desejado usando uma opção changeTypede consulta personalizada . Os valores possíveis são created, updated ou deleted.

GET /me/mailfolders/{id}/messages/delta?changeType=created
GET /me/mailfolders/{id}/messages/delta?changeType=updated
GET /me/mailfolders/{id}/messages/delta?changeType=deleted

Cabeçalhos de solicitação opcionais

Cada solicitação GET de consulta delta retorna um conjunto de um ou mais mensagens na resposta. Como alternativa, você pode especificar o cabeçalho de solicitação, Prefer: odata.maxpagesize={x}, para configurar o máximo de mensagens em uma resposta.

Exemplo 1: sincronizar mensagens em uma pasta

O exemplo a seguir mostra 2 sessões de sincronização de uma pasta específica que, inicialmente, contém 5 mensagens.

A primeira sessão envolve uma série de 3 solicitações para sincronizar todas as 5 mensagens na pasta:

Após a primeira sessão, uma das mensagens é excluída e outra é marcada como lida. A segunda sessão da sincronização retorna apenas o intervalo (a exclusão e atualização) sem retornar as demais mensagens que permaneceram as mesmas.

Solicitação inicial de exemplo

Neste exemplo, a pasta especificada está sendo sincronizada pela primeira vez, portanto, a solicitação de sincronização inicial não inclui nenhum token de estado. Essa rodada retorna todas as mensagens nessa pasta.

A primeira solicitação especifica o seguinte:

  • Um parâmetro $select para retornar as propriedades subject, sender e isRead de cada mensagem na resposta.
  • O cabeçalho de solicitação opcional, odata.maxpagesize, retornando 2 mensagens de cada vez.
GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$select=subject,sender,isRead HTTP/1.1
Prefer: odata.maxpagesize=2

Resposta inicial de exemplo

A resposta inclui duas mensagens e um cabeçalho de resposta @odata.nextLink. A URL @odata.nextLink indica que há mais mensagens na pasta para obter.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$skiptoken=GwcBoTmPuoTQWfcsAbkYM",
  "value": [
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAASsKZz\"",
      "subject": "Holiday hours update",
      "isRead": false,
      "sender": {
        "emailAddress": {
          "name": "Dana Swope",
          "address": "danas@contoso.com"
        }
      },
      "id": "AAMkADNkNAAASq35xAAA="
    },
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB/\"",
      "subject": "Holiday promotion sale",
      "isRead": true,
      "sender": {
        "emailAddress": {
          "name": "Samantha Booth",
          "address": "samanthab@contoso.com"
        }
      },
      "id": "AQMkADNkNAAAVRMKAAAAA=="
    }
  ]
}

Segundo exemplo de solicitação

A segunda solicitação especifica a URL @odata.nextLink retornada na resposta anterior. Observe que não é mais necessário especificar o mesmo parâmetro $select como na solicitação inicial, pois o skipToken na URL @odata.nextLink os codifica e inclui.

GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$skiptoken=GwcBoTmPuoTQWfcsAbkYM HTTP/1.1
Prefer: odata.maxpagesize=2

Segunda resposta de exemplo

A segunda resposta retorna as 2 próximas mensagens na pasta e outro @odata.nextLink, indicando que há mais mensagens a ser lidas na pasta.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$skiptoken=GwcBoTmPKILK4jLH7mAd1lLU",
  "value": [
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlqfdAAAEfYB+\"",
      "subject": "Microsoft Virtual Academy at Contoso",
      "isRead": true,
      "sender": {
        "emailAddress": {
          "name": "Elliot Hyde",
          "address": "elliot-hyde@tailspintoys.com"
        }
      },
      "id": "AQMkADNkNAAAgWkAAAA"
    },
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB+\"",
      "subject": "New or modified user account information",
      "isRead": true,
      "sender": {
        "emailAddress": {
          "name": "Randi Welch",
          "address": "randiw@contoso.com"
        }
      },
      "id": "AQMkADNkNAAAgWJAAAA"
    }
  ]
}

Terceira solicitação de exemplo

A terceira solicitação continua a usar a última URL do @odata.nextLink retornada da última solicitação de sincronização.

GET https://graph.microsoft.com/v1.0/me/mailFolders/AQMkADNkNAAAgEMAAAA/messages/delta?$skiptoken=GwcBoTmPKILK4jLH7mAd1lLU HTTP/1.1
Prefer: odata.maxpagesize=2

Terceira e última resposta de exemplo

A terceira resposta retorna a única mensagem restante na pasta e uma @odata.deltaLink URL que indica que a sincronização está concluída por enquanto para esta pasta. Salvar e usar a URL @odata.deltaLink para sincronizar a mesma pasta na próxima fase.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY",
  "value": [
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzFPjSbaPPxzjlzOTAAAEfYB+\"",
      "subject": "Fabric CDN now available",
      "isRead": true,
      "sender": {
        "emailAddress": {
          "name": "Jodie Sharp",
          "address": "Jodie.Sharp@contoso.com"
        }
      },
      "id": "AAMkADk0MGFkODE3LWEAAA="
    }
  ]
}

Sincronizar mensagens na mesma pasta na próxima sessão

Usando a @odata.deltaLink da última solicitação na última rodada, você é capaz de obter apenas as mensagens que foram alteradas (sendo adicionadas, excluídas ou atualizadas) nessa pasta desde então. Sua primeira solicitação na próxima fase terá aparência semelhante à seguinte, supondo que você prefira manter o mesmo tamanho máximo de página na resposta:

GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY HTTP/1.1
Prefer: odata.maxpagesize=2

A resposta contém um @odata.deltaLink. Isso indica que todas as alterações na pasta de email remoto agora estão sincronizadas. Uma mensagem foi excluída e a mensagem foi alterada.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY",
  "value": [
    {
      "@odata.type": "#microsoft.graph.message",
      "id": "AAMkADk0MGFkODE3LWE4MmYtNDRhOS0Dh_6qB-pB2Sa2pUum19a6YAAKnLuxoAAA=",
      "@removed": {
        "reason": "deleted"
      }
    },
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAASsKZz\"",
      "subject": "Holiday hours update",
      "isRead": "true",
      "sender": {
        "emailAddress": {
          "name": "Dana Swope",
          "address": "danas@contoso.com"
        }
      },
      "id": "AAMkADNkNAAASq35xAAA="
    }
  ]
}

Exemplo 2: sincronizar mensagens em uma pasta com base no tipo de alteração

O exemplo a seguir mostra a obtenção apenas de mensagens que são criadas em uma pasta específica desde a sincronização inicial. O exemplo envolve duas rodadas de sincronização dessa pasta que inicialmente contém 4 mensagens.

A primeira rodada envolve uma série de duas solicitações para sincronizar todas as 4 mensagens na pasta:

Após a primeira rodada, mais duas mensagens são criadas, uma mensagem é excluída e outra é marcada como leitura.

A segunda rodada de sincronização retorna apenas as alterações na pasta do tipo de created alteração (as duas novas mensagens criadas), sem retornar as outras mensagens que permaneceram as mesmas, excluídas ou atualizadas desde a última sincronização.

Solicitação inicial de exemplo com o tipo de alteração especificado

Neste exemplo, a pasta especificada está sendo sincronizada pela primeira vez, portanto, a solicitação de sincronização inicial não inclui nenhum token de estado. Essa rodada retorna todas as mensagens nessa pasta.

A primeira solicitação especifica o seguinte:

  • Um changeType parâmetro para retornar apenas as mensagens criadas na resposta delta subsequente.
  • Um parâmetro $select para retornar as propriedades subject, sender e isRead de cada mensagem na resposta.
  • O cabeçalho de solicitação opcional, odata.maxpagesize, retornando 2 mensagens de cada vez.
GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?changeType=created&$select=subject,sender,isRead HTTP/1.1
Prefer: odata.maxpagesize=2

Exemplo de resposta inicial com o tipo de alteração especificado

A resposta inclui duas mensagens e um cabeçalho de resposta @odata.nextLink. A URL @odata.nextLink indica que há mais mensagens na pasta para obter.

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=P4lmXpjPRrjB6haAQzSkpK89jYTVD2kVtOeXNRnfYzPbCs",
    "value": [
        {
            "@odata.type": "#microsoft.graph.message",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBP\"",
            "subject": "Inline Attachments Again",
            "isRead": true,
            "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LT2fKdhq8oSKEDSVrdi3lRAAIei5gdAAA=",
            "sender": {
                "emailAddress": {
                    "name": "Megan Brown",
                    "address": "Megan.Brown@contoso.com"
                }
            }
        },
        {
            "@odata.type": "#microsoft.graph.message",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBR\"",
            "subject": "RE: Test Outlook TimeZone",
            "isRead": true,
            "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMKdhq8oSKEDSVrdi3lRAAIei5geAAA=",
            "sender": {
                "emailAddress": {
                    "name": "Megan Brown",
                    "address": "Megan.Brown@contoso.com"
                }
            }
        }
    ]
}

Exemplo de segunda solicitação com o tipo de alteração especificado

A segunda solicitação especifica a URL @odata.nextLink retornada na resposta anterior. Observe que ele não precisa mais especificar o mesmo $select ou o changeType parâmetro que na solicitação inicial, como o skipToken na URL codifica e o @odata.nextLink inclui.

GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=P4lmXpjPRrjB6haAQzSkpK89jYTVD2kVtOeXNRnfYzPbCs HTTP/1.1
Prefer: odata.maxpagesize=2

Exemplo de segunda resposta com o tipo de alteração especificado

A segunda resposta retorna as próximas duas mensagens na pasta e @odata.deltaLink na URL que indica que a sincronização está concluída por enquanto para esta pasta. Salvar e usar a URL @odata.deltaLink para sincronizar a mesma pasta na próxima fase.

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$deltatoken=P4lmXpjPRrjB6haAQ_37roqIbjXe66KoV7SMlLH--Jgi8",
    "value": [
        {
            "@odata.type": "#microsoft.graph.message",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBu\"",
            "subject": "Your preview of the new Briefing email",
            "isRead": true,
            "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwBIJ",
            "sender": {
                "emailAddress": {
                    "name": "Cortana",
                    "address": "cortana@contoso.com"
                }
            }
        },
        {
            "@odata.type": "#microsoft.graph.message",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBw\"",
            "subject": "Char Coding HTML",
            "isRead": true,
            "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwBA=",
            "sender": {
                "emailAddress": {
                    "name": "John Doe",
                    "address": "John.Doe@contoso.com"
                }
            }
        }
    ]
}

Sincronizar mensagens na mesma pasta na próxima rodada com base no tipo de alteração especificado

Usando a @odata.deltaLink da última resposta na última rodada, você é capaz de obter apenas as mensagens que foram adicionadas nessa pasta desde então. Sua primeira solicitação na próxima fase terá aparência semelhante à seguinte, supondo que você prefira manter o mesmo tamanho máximo de página na resposta:

GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$deltatoken=P4lmXpjPRrjB6haAQ_37roqIbjXe66KoV7SMlLH--Jgi8 HTTP/1.1
Prefer: odata.maxpagesize=2

A resposta contém um @odata.deltaLink. Isso indica que todas as alterações na pasta de email remoto agora estão sincronizadas. Duas mensagens foram adicionadas desde a última sincronização. As mensagens atualizadas & excluídas desde a última sincronização não são retornadas nesta resposta delta.

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=EPuhZPRDHo-r3EBfscYE444fuGSBRV1eXex3JZkLzT9fRM",
    "value": [
        {
            "@odata.type": "#microsoft.graph.message",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MCP\"",
            "subject": "Nested Attachment",
            "isRead": true,
            "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwBIJ",
            "sender": {
                "emailAddress": {
                    "name": "Patti Fernandez",
                    "address": "PattiF@contoso.com"
                }
            }
        },
        {
            "@odata.type": "#microsoft.graph.message",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MCN\"",
            "subject": "Attachment Testing",
            "isRead": true,
            "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwZA=",
            "sender": {
                "emailAddress": {
                    "name": "Patti Fernandez",
                    "address": "PattiF@contoso.com"
                }
            }
        }
    ]
}

Conteúdo relacionado