evento: 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 recursos de evento que foram adicionados, excluídos ou atualizados em um ou mais calendários.
Você pode obter tipos específicos dessas alterações incrementais nos eventos em todos os calendários de uma caixa de correio ou em um calendário específico ou em uma coleção de eventos de uma CalendarView (intervalo de eventos definidos por datas de início e término) de um calendário. O calendário pode ser o calendário padrão ou algum outro calendário especificado do usuário. No caso de obter alterações incrementais no calendarView, o calendário também pode ser um calendário de grupo.
Normalmente, sincronizar eventos em um calendário ou calendárioView em um repositório local implica uma rodada de várias chamadas de função delta . A chamada inicial é uma sincronização completa, e cada chamada delta subsequente na mesma rodada recebe as alterações incrementais (acréscimos, exclusões ou atualizações). Isso permite manter e sincronizar um repositório local de eventos no calendário especificado, sem precisar buscar todos os eventos desse calendário do servidor todas as vezes.
A tabela a seguir lista as diferenças entre a função delta em eventos e a função delta em um calendarView em um calendário.
| Função Delta em eventos | Função Delta no calendarView |
|---|---|
| Obtém alterações incrementais de todos os eventos em um calendário não limitado por um intervalo de datas de início e de término. Como alternativa, você pode obter alterações incrementais dos eventos em um calendário delimitado por uma hora de início, iniciando ou após essa data/hora. | Obtém alterações incrementais de eventos na data/hora de início e término do calendárioView. |
Retorna apenas um conjunto limitado de propriedades de evento por motivos de desempenho. Cliente a ser usado GET /events/{id} posteriormente para expandir qualquer evento. |
A expansão do lado do servidor retorna um conjunto mais completo de propriedades de evento . |
| A resposta inclui instâncias individuais e séries recorrentes master. | A resposta inclui instâncias individuais, ocorrências e exceções de séries recorrentes. |
| Aplica-se a eventos em calendários de usuário, mas não a calendários de grupo. | Aplica-se a eventos em calendários de usuário e de grupo. |
| Atualmente disponível apenas na versão beta. | Disponível nas versões v1.0 e beta. |
Essa API está disponível nas seguintes implantações nacionais de nuvem.
| Serviço global | Governo dos EUA L4 | GOVERNO DOS EUA L5 (DOD) | China operada pela 21Vianet |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
Permissões
Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas 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.
| Tipo de permissão | Permissões menos privilegiadas | Permissões privilegiadas mais altas |
|---|---|---|
| Delegado (conta corporativa ou de estudante) | Calendars.ReadBasic | Calendars.Read, Calendars.ReadWrite |
| Delegado (conta pessoal da Microsoft) | Calendars.ReadBasic | Calendars.Read, Calendars.ReadWrite |
| Aplicativo | Calendars.Read | Calendars.ReadBasic, Calendars.ReadWrite |
Solicitação HTTP
Esta seção mostra a sintaxe de solicitação HTTP para a chamada de função delta inicial para iniciar uma sincronização completa que recupera todos os eventos no calendário ou na exibição de calendário especificada. Essa sintaxe não contém nenhum token de estado.
A URL de consulta retornada em um @odata.nextLink ou @odata.deltaLink de uma resposta bem-sucedida inclui um token de estado. Para qualquer chamada de função delta subsequente, use a URL de consulta em uma @odata.nextLink ou @odata.deltaLink anterior a ela.
Função Delta em eventos em um calendário de usuário (versão prévia)
Aplique a função delta em todos os eventos ou eventos que começam em ou após uma data/hora específica, nos calendários de usuário especificados):
Para obter alterações incrementais de todos os eventos ou de eventos que começam em ou após a data/hora especificada na caixa de correio do usuário:
GET /me/events/delta GET /users/{id | userPrincipalName}/events/delta GET /me/events/delta?startDateTime={start_datetime} GET /users/{id | userPrincipalName}/events/delta?startDateTime={start_datetime}Para obter alterações incrementais de todos os eventos ou de eventos que começam em ou após a data/hora especificada no calendário padrão do usuário:
GET /me/calendar/events/delta GET /users/{id | userPrincipalName}/calendar/events/delta GET /me/calendar/events/delta?startDateTime={start_datetime} GET /users/{id | userPrincipalName}/calendar/events/delta?startDateTime={start_datetime}Para obter alterações incrementais de todos os eventos ou de eventos que começam em ou após a data/hora especificada no calendário de usuário especificado:
GET /me/calendars/{id}/events/delta GET /users/{id | userPrincipalName}/calendars/{id}/events/delta GET /me/calendars/{id}/events/delta?startDateTime={start_datetime} GET /users/{id | userPrincipalName}/calendars/{id}/events/delta?startDateTime={start_datetime}Para obter alterações incrementais em todos os eventos ou eventos que começam em ou após a data/hora especificada no grupo de calendário e calendário especificados:
GET /me/calendarGroups/{id}/calendars/{id}/events/delta GET /users/{id | userPrincipalName}/calendarGroups/{id}/calendars/{id}/events/delta GET /me/calendarGroups/{id}/calendars/{id}/events/delta?startDateTime={start_datetime} GET /users/{id | userPrincipalName}/calendarGroups/{id}/calendars/{id}/events/delta?startDateTime={start_datetime}
Função Delta no calendarView em um calendário de usuário
Aplique a função delta em um intervalo de eventos delimitados pela data/hora de início e término, no calendário de usuário especificado:
Para obter alterações incrementais em uma exibição de calendário do calendário padrão do usuário:
GET /me/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime} GET /users/{id}/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}Para obter alterações incrementais em uma exibição de calendário do calendário de usuário especificado:
GET /me/calendars/{id}/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime} GET /users/{id}/calendars/{id}/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}
Função Delta no calendarView em um calendário de grupo
- Para obter alterações incrementais em uma exibição de calendário do calendário de um grupo:
GET /groups/{id}/calendarView?startDateTime={start_datetime}&endDateTime={end_datetime}
Parâmetros de consulta
O acompanhamento de alterações incorre em uma rodada de uma ou mais chamadas de função delta . Se você usar qualquer parâmetro de consulta (diferente de $deltatoken e $skiptoken), especifique-o na primeira solicitação delta. 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.
Nas 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âmetro de consulta | Tipo | Descrição |
|---|---|---|
| startDateTime | String | A data e a hora de início do intervalo de tempo, representadas no formato ISO 8601. Por exemplo, "2019-11-08T19:00:00-08:00". O fuso horário é especificado na parte de deslocamento de fuso horário do valor do parâmetro e não é afetado pelo Prefer: outlook.timezone cabeçalho se estiver presente. Se nenhum deslocamento de fuso horário estiver incluído no valor, ele será interpretado como UTC.Opcional para delta em eventos em um calendário. Necessário para delta no calendarView. |
| endDateTime | String | A data e a hora de término do intervalo de tempo, representadas no formato ISO 8601. Por exemplo, "2019-11-08T20:00:00-08:00". O fuso horário é especificado na parte de deslocamento de fuso horário do valor do parâmetro e não é afetado pelo Prefer: outlook.timezone cabeçalho se estiver presente. Se nenhum deslocamento de fuso horário estiver incluído no valor, ele será interpretado como UTC.Não há suporte paradelta em eventos em um calendário. Necessário para delta no calendarView. |
| $deltatoken | string | Um token de estado retornado na @odata.deltaLink URL da chamada de função delta anterior para a mesma exibição de calendário, indicando a conclusão dessa rodada de controle de alterações. Salve e aplique toda @odata.deltaLink a URL, incluindo esse token, na primeira solicitação da próxima rodada de controle de alterações para essa exibição de calendário. |
| $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 no mesmo modo de exibição de calendário. |
Parâmetros de consulta OData
Esperar uma delta chamada de função em um calendárioView para retornar as mesmas propriedades que você normalmente obteria de um
GET /calendarViewsolicitação. Você não pode usar$selectpara obter apenas um subconjunto dessas propriedades.A função delta não dá suporte aos seguintes parâmetros de consulta para eventos em um calendário de usuário ou eventos em um calendárioView:
$expand,$filter,$orderby,$searche$select.
Cabeçalhos de solicitação
| Nome | Tipo | Descrição |
|---|---|---|
| Autorização | string | {token} de portador. Obrigatório. |
| Content-Type | string | application/json. Obrigatório. |
| Preferir | cadeia de caracteres | odata.maxpagesize={x}. Opcional. |
| Preferir | cadeia de caracteres | outlook.timezone={Cadeia de caracteres de fuso horário}. Opcional, supõe-se o UTC se estiver ausente. |
Resposta
Função Delta em eventos (versão prévia)
Se for bem-sucedido, esse método retornará um 200 OK código de resposta e uma coleção de eventos no corpo da resposta. Cada evento na resposta contém apenas as propriedades id, type, start e end por motivos de desempenho. Use GET /events/{id} posteriormente para expandir todos os eventos da resposta.
Função Delta no calendarView
Se for bem-sucedido, esse método retornará um 200 OK código de resposta e uma coleção de eventos no corpo da resposta.
Espere obter todas as propriedades que você normalmente obteria de uma solicitação GET /calendarView .
Dentro de uma rodada de delta chamadas de função associadas ao intervalo de datas de um calendárioView, você pode encontrar uma delta chamada retornando dois tipos de eventos em @removed com o motivo deleted:
- Eventos que estejam dentro do intervalo de datas e que tenham sido excluídos desde a chamada anterior delta.
- Eventos que estejam fora do intervalo de datas e que tenham sido adicionados, excluídos ou atualizados desde a chamada anterior delta.
Filtre os eventos sob @removed para o intervalo de datas que seu cenário requer.
Exemplos
Exemplo 1: função Delta em eventos em um calendário (versão prévia)
Solicitação
O exemplo a seguir mostra a solicitação de sincronização inicial para obter eventos no calendário padrão do usuário conectado, que ocorrem no ou após o parâmetro especificado startDateTime . A solicitação inicial não inclui nenhum token de estado.
A solicitação usa o Prefer: odata.maxpagesize cabeçalho para limitar o número máximo de eventos em cada resposta a 1.
Continue chamando a delta função usando a consulta retornada @odata.nextLink até obter um @odata.deltaLink na resposta.
GET https://graph.microsoft.com/beta/me/calendar/events/delta?startDateTime=2020-06-12T00:00:00Z
Prefer: odata.maxpagesize=1
Resposta
Se a solicitação for bem-sucedida, a resposta inclui 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 você concluiu a obtenção de todas as alterações para essa rodada.
A resposta abaixo mostra um skipToken em um cabeçalho de resposta @odata.nextLink.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.nextLink":"https://graph.microsoft.com/beta/me/calendar/events/delta?$skiptoken=R0usmcdvmMu7jxWP8",
"value": [
{
"id": " AAMkADllMWMwNDkzLWJlY2EtNDIyOS1iZjAA=",
"type": "singleInstance",
"start": {
"DateTime": "2020-02-19T10:00:00.0000000",
"TimeZone": "UTC"
},
"end": {
"DateTime": "2020-02-19T11:00:00.0000000",
"TimeZone": "UTC"
}
}
]
}
Exemplo 2: função Delta no calendarView
Solicitação
O exemplo a seguir mostra a solicitação de sincronização inicial para obter eventos no calendário especificado do usuário conectado, dentro do intervalo de datas indicado pelo calendarView. A solicitação inicial não inclui nenhum token de estado.
A solicitação usa o Prefer: odata.maxpagesize cabeçalho para limitar o número máximo de eventos em cada resposta a 2. Continue chamando a delta função usando a consulta retornada @odata.nextLink até obter todos os eventos nessa exibição de calendário e um @odata.deltaLink na resposta.
GET https://graph.microsoft.com/beta/me/calendars/AAMkADI5M1BbeAAA=/calendarView/delta?startDateTime=2020-06-01T00:00:00Z&endDateTime=2020-06-10T00:00:00Z
Prefer: odata.maxpagesize=2
Resposta
Se a solicitação for bem-sucedida, a resposta inclui 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 você concluiu a obtenção de todas as alterações para essa rodada.
A resposta abaixo mostra um skipToken em um cabeçalho de resposta @odata.nextLink.
Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(event)",
"@odata.nextLink": "https://graph.microsoft.com/beta/me/calendars/AAMkADI5M1BbeAAA=/calendarView/delta?$skiptoken=R0usmcdvmMu7jxWP8",
"value": [
{
"@odata.type": "#microsoft.graph.event",
"@odata.etag": "W/\"Jdsb3FEkPk2qoUHCdliYowACwixTgw==\"",
"createdDateTime": "2020-06-16T04:05:43.8668791Z",
"lastModifiedDateTime": "2020-06-16T04:08:27.354268Z",
"changeKey": "Jdsb3FEkPk2qoUHCdliYowACwixTgw==",
"categories": [],
"transactionId": null,
"originalStartTimeZone": "Pacific Standard Time",
"originalEndTimeZone": "Pacific Standard Time",
"uid": "040000008200E00074C5B7101A82E00800000000F088B8B95843D601000000000000000010000000165CD5547CFC9545B6492B261750B48C",
"reminderMinutesBeforeStart": 15,
"isReminderOn": false,
"hasAttachments": false,
"subject": "Summer party",
"bodyPreview": "",
"importance": "normal",
"sensitivity": "normal",
"isAllDay": false,
"isCancelled": false,
"isOrganizer": true,
"IsRoomRequested": false,
"AutoRoomBookingStatus": "None",
"responseRequested": true,
"seriesMasterId": null,
"showAs": "busy",
"type": "singleInstance",
"webLink": "https://outlook.office365.com/owa/?itemid=AAMkADI5MAAKkeE1QAAA%3D&exvsurl=1&path=/calendar/item",
"onlineMeetingUrl": null,
"isOnlineMeeting": false,
"onlineMeetingProvider": "unknown",
"allowNewTimeProposals": true,
"OccurrenceId": null,
"isDraft": false,
"recurrence": null,
"AutoRoomBookingOptions": null,
"onlineMeeting": null,
"id": "AAMkADI5MAAKkeE1QAAA=",
"responseStatus": {
"response": "none",
"time": "0001-01-01T00:00:00Z"
},
"body": {
"contentType": "html",
"content": "<html>\r\n<head></head>\r\n<body lang=\"EN-US\" link=\"#0563C1\" vlink=\"#954F72\" style=\"\">\r\n<div class=\"WordSection1\">\r\n<p class=\"MsoNormal\"> </p>\r\n</div>\r\n</body>\r\n</html>\r\n"
},
"start": {
"dateTime": "2020-06-02T20:00:00.0000000",
"timeZone": "UTC"
},
"end": {
"dateTime": "2020-06-02T22:30:00.0000000",
"timeZone": "UTC"
},
"location": {
"displayName": "",
"locationType": "default",
"uniqueIdType": "unknown",
"address": {
"type": "unknown"
},
"coordinates": {}
},
"locations": [],
"attendees": [
{
"type": "required",
"status": {
"response": "none",
"time": "0001-01-01T00:00:00Z"
},
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
}
],
"organizer": {
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
}
},
{
"@odata.type": "#microsoft.graph.event",
"@odata.etag": "W/\"Jdsb3FEkPk2qoUHCdliYowACwixTfw==\"",
"createdDateTime": "2020-06-16T04:06:18.386713Z",
"lastModifiedDateTime": "2020-06-16T04:08:19.5694048Z",
"changeKey": "Jdsb3FEkPk2qoUHCdliYowACwixTfw==",
"categories": [],
"transactionId": null,
"originalStartTimeZone": "Pacific Standard Time",
"originalEndTimeZone": "Pacific Standard Time",
"uid": "040000008200E00074C5B7101A82E0080000000060074BC55843D6010000000000000000100000002D33A89F36B10D43A12FD990B62858B2",
"reminderMinutesBeforeStart": 15,
"isReminderOn": true,
"hasAttachments": false,
"subject": "Summer party part 2",
"bodyPreview": "",
"importance": "normal",
"sensitivity": "normal",
"isAllDay": false,
"isCancelled": false,
"isOrganizer": true,
"IsRoomRequested": false,
"AutoRoomBookingStatus": "None",
"responseRequested": true,
"seriesMasterId": null,
"showAs": "busy",
"type": "singleInstance",
"webLink": "https://outlook.office365.com/owa/?itemid=AAMkADI5MAAKkeE1RAAA%3D&exvsurl=1&path=/calendar/item",
"onlineMeetingUrl": null,
"isOnlineMeeting": false,
"onlineMeetingProvider": "unknown",
"allowNewTimeProposals": true,
"OccurrenceId": null,
"isDraft": false,
"recurrence": null,
"AutoRoomBookingOptions": null,
"onlineMeeting": null,
"id": "AAMkADI5MAAKkeE1RAAA=",
"responseStatus": {
"response": "none",
"time": "0001-01-01T00:00:00Z"
},
"body": {
"contentType": "html",
"content": "<html>\r\n<head></head>\r\n<body lang=\"EN-US\" link=\"#0563C1\" vlink=\"#954F72\" style=\"\">\r\n<div class=\"WordSection1\">\r\n<p class=\"MsoNormal\"> </p>\r\n</div>\r\n</body>\r\n</html>\r\n"
},
"start": {
"dateTime": "2020-06-04T19:30:00.0000000",
"timeZone": "UTC"
},
"end": {
"dateTime": "2020-06-04T22:30:00.0000000",
"timeZone": "UTC"
},
"location": {
"displayName": "",
"locationType": "default",
"uniqueIdType": "unknown",
"address": {
"type": "unknown"
},
"coordinates": {}
},
"locations": [],
"attendees": [
{
"type": "required",
"status": {
"response": "none",
"time": "0001-01-01T00:00:00Z"
},
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
}
],
"organizer": {
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
}
}
]
}
Conteúdo relacionado
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de