message: delta

Namespace: microsoft.graph

Receba um conjunto de mensagens adicionadas, excluídas ou atualizadas em uma pasta especificada.

Uma chamada de função delta para mensagens em uma pasta é semelhante a uma solicitação GET, exceto que, aplicando tokens de estado adequadamente em uma ou mais dessas chamadas, você pode consultar alterações incrementais nas mensagens dessa pasta. Ele permite que você mantenha e sincronize um armazenamento local das mensagens de um usuário sem ter que buscar todo o conjunto de mensagens do servidor todas as vezes.

Essa API está disponível nas seguintes implantações de nuvem nacional.

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Solicitação HTTP

Para obter todas as alterações nas mensagens na pasta de email especificada:

GET /me/mailFolders/{id}/messages/delta
GET /users/{id}/mailFolders/{id}/messages/delta

Para obter especificamente apenas mensagens criadas, atualizadas ou excluídas no mailFolder especificado:

GET /me/mailFolders/{id}/messages/delta?changeType=created
GET /users/{id}/mailfolders/{id}/messages/delta?changeType=created

GET /me/mailFolders/{id}/messages/delta?changeType=updated
GET /users/{id}/mailFolders/{id}/messages/delta?changeType=updated

GET /me/mailFolders/{id}/messages/delta?changeType=deleted
GET /users/{id}/mailFolders/{id}/messages/delta?changeType=deleted

Parâmetros de consulta

O acompanhamento de alterações em mensagens incorre em uma rodada de uma ou mais chamadas de função delta . Se você usar qualquer parâmetro de consulta (diferente de e $skiptoken) que seja uma opção de $deltatoken consulta do sistema OData ou a opção de consulta personalizada changeType, deverá especificá-lo na solicitação delta inicial. O Microsoft Graph codifica automaticamente todos os parâmetros especificados na parte do token da URL @odata.nextLink ou @odata.deltaLink fornecida na resposta. Você só precisa especificar uma vez os parâmetros de consulta desejados antecipadamente. Em solicitações subsequentes, basta copiar e aplicar a @odata.nextLink URL ou @odata.deltaLink da resposta anterior, pois essa URL já inclui os parâmetros codificados e desejados.

Parâmetros de consulta OData

• 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 propriedade id sempre será retornada.
• Suporte à consulta delta $select, $top e $expand para mensagens.
• Há suporte limitado para $filter e $orderby:
  • As únicas expressões $filter suportadas são $filter=receivedDateTime+ge+{value} ou $filter=receivedDateTime+gt+{value}.
  • A única expressão $orderby suportada é $orderby=receivedDateTime+desc. Se você não incluir uma $orderby expressão, a ordem de devolução não será garantida.
• Não há suporte para $search.

Cabeçalhos de solicitação

Resposta

Se bem-sucedido, este método retorna o código de resposta 200 OK e uma coleção de objetos message no corpo da resposta.

Exemplo

Solicitação

O exemplo a seguir mostra como fazer uma única chamada de função delta e limitar o número máximo de mensagens no corpo da resposta a dois.

Para controlar as alterações nas mensagens em uma pasta, você faria uma ou mais chamadas de função delta para obter o conjunto de alterações incrementais desde a última consulta delta. Para obter um exemplo que mostra uma rodada de chamadas de consulta delta, consulte Obter alterações incrementais nas mensagens em uma pasta.

GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGVmMDEzMTM4LTZmYWUtNDdkNC1hMDZiLTU1OGY5OTZhYmY4OAAuAAAAAAAiQ8W967B7TKBjgx9rVEURAQAiIsqMbYjsT5e-T7KzowPTAAAAAAFNAAA=/messages/delta
Prefer: odata.maxpagesize=2

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.MailFolders["{mailFolder-id}"].Messages.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.Headers.Add("Prefer", "odata.maxpagesize=2");
});

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "odata.maxpagesize=2")

configuration := &graphusers.MailFoldersItemMessagesDeltaRequestBuilderGetRequestConfiguration{
	Headers: headers,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Me().MailFolders().ByMailFolderId("mailFolder-id").Messages().Delta().GetAsDeltaGetResponse(context.Background(), configuration)

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.me().mailFolders().byMailFolderId("{mailFolder-id}").messages().delta().get(requestConfiguration -> {
	requestConfiguration.headers.add("Prefer", "odata.maxpagesize=2");
});

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/mailFolders/AAMkAGVmMDEzMTM4LTZmYWUtNDdkNC1hMDZiLTU1OGY5OTZhYmY4OAAuAAAAAAAiQ8W967B7TKBjgx9rVEURAQAiIsqMbYjsT5e-T7KzowPTAAAAAAFNAAA=/messages/delta')
	.header('Prefer','odata.maxpagesize=2')
	.get();

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\MailFolders\Item\Messages\Delta\DeltaRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$headers = [
		'Prefer' => 'odata.maxpagesize=2',
	];
$requestConfiguration->headers = $headers;


$result = $graphServiceClient->me()->mailFolders()->byMailFolderId('mailFolder-id')->messages()->delta()->get($requestConfiguration)->wait();

Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMailFolderMessageDelta -UserId $userId -MailFolderId $mailFolderId

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.mail_folders.item.messages.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

request_configuration = RequestConfiguration()
request_configuration.headers.add("Prefer", "odata.maxpagesize=2")


result = await graph_client.me.mail_folders.by_mail_folder_id('mailFolder-id').messages.delta.get(request_configuration = request_configuration)

Resposta

Se a solicitação for bem-sucedida, a resposta incluirá um token de estado, que é um skipToken (em um cabeçalho de resposta @odata.nextLink ) ou um deltaToken (em um cabeçalho de resposta @odata.deltaLink ). Respectivamente, eles indicam se você deve continuar com a rodada ou se concluiu a obtenção de todas as alterações para essa rodada.

A resposta mostra um skipToken em um cabeçalho de resposta @odata.nextLink .

Observação: O objeto de resposta exibido aqui pode ser encurtado para legibilidade.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/me/mailFolders/{id}/messages/delta?$skiptoken={_skipToken_}",
  "value": [
    {
      "receivedDateTime": "datetime-value",
      "sentDateTime": "datetime-value",
      "hasAttachments": true,
      "internetMessageId": "internetMessageId-value",
      "subject": "subject-value",
      "body": {
        "contentType": "contentType-value",
        "content": "content-value"
      }
    }
  ]
}

Conteúdo relacionado

• Usar a consulta delta para controlar alterações nos dados do Microsoft Graph
• Obter as alterações incrementais para as mensagens em uma pasta