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

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.

A sincronização de itens de mensagens num arquivo local pode utilizar a consulta delta para a sincronização completa inicial e sincronizações incrementais subsequentes. Normalmente, faria uma sincronização completa inicial de todas as mensagens numa pasta (por exemplo, a Caixa de Entrada do utilizador) e, em seguida, obteria alterações incrementais a essa pasta periodicamente.

Para obter alterações incrementais de apenas um determinado tipo - mensagens que são criadas, atualizadas ou eliminadas desde a sincronização inicial - faça uma ronda inicial de sincronização de todas as mensagens na pasta e, em seguida, obtenha alterações incrementais de um tipo específico pretendido nas rondas subsequentes. Especifique o tipo de alteração pretendido como uma opção de consulta no pedido delta inicial; O Microsoft Graph codifica automaticamente qualquer OData e opções de consulta personalizadas no @odata.nextLink 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).

Estes tokens são tokens de estado opacos para o cliente. Para prosseguir com uma ronda de controlo de alterações, copie e aplique o URL devolvido do último pedido 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 resto deste artigo inclui dois exemplos:

• Veja o exemplo 1 para saber como utilizar os @odata.nextLink URLs e @odata.deltaLink .
• Veja o exemplo 2 para saber como obter incrementalmente apenas mensagens criadas desde a ronda 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 devolvida.
• 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 não incluir uma expressão $orderby , a ordem de devolução não é garantida.
• Não há suporte para $search.

Além disso, para devolver apenas determinado tipo de alterações (criadas, atualizadas ou eliminadas) na resposta da consulta delta, pode opcionalmente filtrar o tipo de alteração pretendido através de 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 numa 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:

• Solicitação inicial de exemplo e resposta
• Solicitação de segundo exemplo e resposta
• Terceiro exemplo de solicitação e resposta final

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á a ser sincronizada pela primeira vez, pelo que o pedido de sincronização inicial não inclui nenhum token de estado. Esta ronda devolve 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 devolve a única mensagem restante na pasta e um @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

Ao utilizar o @odata.deltaLink do último pedido na última ronda, só pode obter as mensagens que foram alteradas (ao ser adicionada, eliminada ou atualizada) 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 numa pasta com base no tipo de alteração

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

A primeira ronda envolve uma série de dois pedidos para sincronizar todas as quatro mensagens na pasta:

• Pedido inicial de exemplo com tipo de alteração e resposta especificados
• Segundo pedido de exemplo com o tipo de alteração e a resposta especificados

Após a primeira ronda, são criadas mais duas mensagens, uma é eliminada e outra é marcada como lida.

A segunda ronda de sincronização devolve apenas as alterações na pasta do tipo de created alteração (as duas novas mensagens criadas), sem devolver as outras mensagens que permaneceram iguais, eliminadas ou atualizadas desde a última sincronização.

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

Neste exemplo, a pasta especificada está a ser sincronizada pela primeira vez, pelo que o pedido de sincronização inicial não inclui nenhum token de estado. Esta ronda devolve todas as mensagens nessa pasta.

A primeira solicitação especifica o seguinte:

• Um changeType parâmetro para devolver 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

Resposta inicial de exemplo 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"
                }
            }
        }
    ]
}

Segundo pedido de exemplo com o tipo de alteração especificado

A segunda solicitação especifica a URL @odata.nextLink retornada na resposta anterior. Repare que já não tem de especificar o mesmo $select parâmetro ou o changeType mesmo que no pedido inicial, como o skipToken no @odata.nextLink URL codifica e inclui.

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

Segunda resposta de exemplo com o tipo de alteração especificado

A segunda resposta devolve as duas mensagens seguintes na pasta e @odata.deltaLink o 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 ronda com base no tipo de alteração especificado

Ao utilizar a @odata.deltaLink da última resposta na última ronda, só pode obter as mensagens que foram adicionadas a essa 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. Foram adicionadas duas mensagens desde a última sincronização. As mensagens atualizadas & eliminadas desde a última sincronização não são devolvidas 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

• Consulta delta do Microsoft Graph
• Obter as alterações incrementais para os eventos em um modo de exibição de calendário
• Obter as alterações incrementais para grupos
• Obter as alterações incrementais para usuários