message: delta

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Obtenha um conjunto de mensagens que foram adicionadas, eliminadas ou atualizadas numa pasta especificada.

Uma chamada de função delta para mensagens numa pasta é semelhante a um pedido GET, exceto que ao aplicar adequadamente tokens de estado numa ou mais destas chamadas, pode consultar alterações incrementais nas mensagens nessa pasta. A utilização de deltas permite-lhe manter e sincronizar de forma toincremental um arquivo local das mensagens de um utilizador.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global	US Government L4	US Government L5 (DOD)	China operada pela 21Vianet
✅	✅	✅	✅

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão	Permissões com menos privilégios	Permissões com privilégios superiores
Delegado (conta corporativa ou de estudante)	Mail.ReadBasic	Mail.Read, Mail.ReadWrite
Delegado (conta pessoal da Microsoft)	Mail.ReadBasic	Mail.Read, Mail.ReadWrite
Aplicativo	Mail.ReadBasic.All	Mail.Read, Mail.ReadWrite

Solicitação HTTP

Para obter todas as alterações nas mensagens na mailFolder especificada:

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

Para obter especificamente apenas mensagens criadas, atualizadas ou eliminadas na mailFolder especificada:

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 registo de alterações nas mensagens implica uma ronda de uma ou mais chamadas de função delta . Se utilizar qualquer opção de consulta do sistema OData ou a opção de consulta personalizada, changeType, tem de especificá-la no pedido 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. Nos pedidos subsequentes, basta copiar e aplicar o @odata.nextLink URL ou @odata.deltaLink da resposta anterior, uma vez que esse URL já inclui os parâmetros codificados e pretendidos.

Parâmetro de consulta	Tipo	Descrição
$deltatoken	cadeia de caracteres	Um token de estado devolvido no @odata.deltaLink URL da chamada da função delta anterior para a mesma coleção de mensagens, indicando a conclusão dessa ronda de controlo de alterações. Salve e aplique toda a URL @odata.deltaLink, incluindo esse token na primeira solicitação da próxima série de controle de alterações desse conjunto.
$skiptoken	string	Um token de estado retornado na URL @odata.nextLink da chamada de função delta anterior indicando que não há mais alterações a serem controladas na mesma coleção de mensagens.
changeType	string	Uma opção de consulta personalizada para filtrar a resposta delta com base no tipo de alteração. Os valores suportados são created, updatedou deleted.

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.
• Existe 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 não incluir uma expressão $orderby , a ordem de devolução não é garantida.
• Não existe suporte para $search.

Cabeçalhos de solicitação

Nome	Tipo	Descrição
Autorização	string	{token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type	string	application/json. Obrigatório.
Preferir	cadeia de caracteres	odata.maxpagesize={x}. Opcional.

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 numa pasta, 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 ronda de chamadas de consulta delta, veja Obter alterações incrementais a mensagens numa pasta.

HTTP

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

Prefer: odata.maxpagesize=2

CLI

mgc-beta users mail-folders messages delta get --user-id {user-id} --mail-folder-id {mailFolder-id}

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/mailFolders/{id}/messages/delta')
	.version('beta')
	.get();

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

Resposta

Se o pedido for bem-sucedido, a resposta incluirá um token de estado, que é um skipToken (num cabeçalho de resposta @odata.nextLink ) ou um deltaToken (num cabeçalho de resposta @odata.deltaLink ). Respetivamente, indicam se deve continuar com a ronda ou se concluiu a obtenção de todas as alterações para essa ronda.

A resposta seguinte mostra um skipToken num 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/beta/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

• Consulta delta do Microsoft Graph
• Obter as alterações incrementais para as mensagens em uma pasta