evento: delta

Artigo
06/22/2024

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 eventos que foram adicionados, eliminados ou atualizados num ou mais calendários.

Pode obter tipos específicos destas alterações incrementais nos eventos em todos os calendários de uma caixa de correio ou num calendário específico ou numa coleção de eventos de um calendárioVer (intervalo de eventos definidos por datas de início e de fim) de um calendário. O calendário pode ser o calendário predefinido ou outro calendário especificado do utilizador. No caso de obter alterações incrementais no calendárioVer, o calendário também pode ser um calendário de grupo.

Normalmente, sincronizar eventos num calendário ou calendárioVer num arquivo local implica uma ronda 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). Isto permite-lhe manter e sincronizar um arquivo local de eventos no calendário especificado, sem ter de obter sempre todos os eventos desse calendário a partir do servidor.

A tabela seguinte lista as diferenças entre a função delta nos eventos e a função delta num calendárioVer num calendário.

Função Delta em eventos	Função Delta no calendarView
Obtém alterações incrementais de todos os eventos num calendário não vinculados por um intervalo de datas de início e de fim. Em alternativa, pode obter alterações incrementais dos eventos num calendário vinculado por uma hora de início, começando em ou depois dessa data/hora.	Obtém alterações incrementais de eventos na data/hora de início e de fim do calendárioVer.
Devolve apenas um conjunto limitado de propriedades de eventos por motivos de desempenho. Cliente a utilizar `GET /events/{id}` posteriormente para expandir quaisquer eventos.	A expansão do lado do servidor devolve um conjunto mais completo de propriedades de eventos .
A resposta inclui instâncias individuais e modelos globais de séries periódicas.	A resposta inclui instâncias individuais e ocorrências e exceções de séries periódicas.
Aplica-se a eventos em calendários de utilizadores, mas não a calendários de grupo.	Aplica-se a eventos em calendários de utilizadores e grupos.
Atualmente disponível apenas na versão beta.	Disponível nas versões v1.0 e beta.

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)	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 secção mostra a sintaxe do pedido HTTP para a chamada inicial da função delta para iniciar uma sincronização completa que obtém todos os eventos na vista de calendário ou calendário especificada. Esta sintaxe não contém tokens de estado.

O URL de consulta devolvido numa @odata.nextLink resposta com êxito ou @odata.deltaLink inclui um token de estado. Para qualquer chamada de função delta subsequente, utilize o URL de consulta num @odata.nextLink ou @odata.deltaLink anterior.

Função Delta em eventos num calendário de utilizador (pré-visualização)

Aplique a função delta em todos os eventos ou eventos que começam em ou depois de uma data/hora específica, nos calendários de utilizadores especificados:

Para obter alterações incrementais de todos os eventos ou de eventos a partir de ou após a data/hora especificada na caixa de correio do utilizador:

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 a partir de ou após a data/hora especificada no calendário predefinido do utilizador:

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 a partir de ou após a data/hora especificada no calendário de utilizador 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 a todos os eventos ou eventos a partir de ou após a data/hora especificada no grupo e calendário do 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 calendárioVer num calendário de utilizador

Aplique a função delta num intervalo de eventos delimitados por data/hora de início e de fim, no calendário de utilizador especificado:

Para obter alterações incrementais numa vista de calendário do calendário predefinido do utilizador:

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 numa vista de calendário do calendário de utilizador 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 calendárioVer num calendário de grupo

Para obter alterações incrementais numa vista de calendário do calendário de um grupo:

GET /groups/{id}/calendarView?startDateTime={start_datetime}&endDateTime={end_datetime}

Parâmetros de consulta

As alterações de controlo incorrem numa ronda 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. 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
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 do 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 num 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 do 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 suportado pela diferença em eventos num calendário. Necessário para delta no calendarView.
$deltatoken	string	Um token de estado devolvido no `@odata.deltaLink` URL da chamada da função delta anterior para a mesma vista de calendário, indicando a conclusão dessa ronda de controlo de alterações. Guarde e aplique todo `@odata.deltaLink` o URL, incluindo este token, no primeiro pedido da próxima ronda de controlo de alterações para essa vista 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 /calendarView solicitação. Você não pode usar $select para obter apenas um subconjunto dessas propriedades.
A função delta não suporta os seguintes parâmetros de consulta para eventos num calendário de utilizador ou eventos num calendárioVer: $expand, ,$filter$orderby, $searche $select.

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.
Preferir	string	outlook.timezone={Cadeia de fuso horário}. Opcional, supõe-se o UTC se estiver ausente.

Resposta

Função Delta em eventos (pré-visualização)

Se for bem-sucedido, este método devolve 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 de ID, tipo, início e fim por motivos de desempenho. Utilize GET /events/{id} posteriormente para expandir quaisquer eventos da resposta.

Função Delta no calendarView

Se for bem-sucedido, este método devolve um 200 OK código de resposta e uma coleção de eventos no corpo da resposta.

Espere obter todas as propriedades que normalmente obteria de um GET /calendarView pedido.

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 num calendário (pré-visualização)

Solicitação

O exemplo seguinte mostra o pedido de sincronização inicial para obter eventos no calendário predefinido do utilizador com sessão iniciada, que ocorrem no ou após o parâmetro especificado startDateTime . O pedido inicial não inclui nenhum token de estado.

O pedido utiliza o Prefer: odata.maxpagesize cabeçalho para limitar o número máximo de eventos em cada resposta a 1. Continue a chamar a delta função através da consulta devolvida @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



mgc-beta users calendar events delta get --user-id {user-id} --start-date-time "2020-06-12T00:00:00Z"

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.


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/calendar/events/delta?startDateTime=2020-06-12T00:00:00Z')
	.version('beta')
	.get();

Importante

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 inclui 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 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 seguinte mostra o pedido de sincronização inicial para obter eventos no calendário especificado do utilizador com sessão iniciada, dentro do intervalo de datas indicado pelo calendarView. O pedido inicial não inclui nenhum token de estado.

O pedido utiliza o Prefer: odata.maxpagesize cabeçalho para limitar o número máximo de eventos em cada resposta a 2. Continue a chamar a delta função utilizando a consulta devolvida até @odata.nextLink obter todos os eventos nessa vista 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



mgc-beta users calendars calendar-view delta get --user-id {user-id} --calendar-id {calendar-id} --start-date-time "2020-06-01T00:00:00Z" --end-date-time "2020-06-10T00:00:00Z"

Importante

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


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/calendars/AAMkADI5M1BbeAAA=/calendarView/delta?startDateTime=2020-06-01T00:00:00Z&endDateTime=2020-06-10T00:00:00Z')
	.version('beta')
	.get();

Importante

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

Resposta

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\">&nbsp;</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\">&nbsp;</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"
                }
            }
        }
    ]
}

Compartilhar via

evento: delta

Permissões

Solicitação HTTP

Função Delta em eventos num calendário de utilizador (pré-visualização)

Função Delta no calendárioVer num calendário de utilizador

Função Delta no calendárioVer num calendário de grupo

Parâmetros de consulta

Parâmetros de consulta OData

Cabeçalhos de solicitação

Resposta

Função Delta em eventos (pré-visualização)

Função Delta no calendarView

Exemplos

Exemplo 1: função Delta em eventos num calendário (pré-visualização)

Solicitação

Resposta

Exemplo 2: função Delta no calendarView

Solicitação

Resposta

Comentários

Recursos adicionais

Compartilhar via

evento: delta

Permissões

Solicitação HTTP

Função Delta em eventos num calendário de utilizador (pré-visualização)

Função Delta no calendárioVer num calendário de utilizador

Função Delta no calendárioVer num calendário de grupo

Parâmetros de consulta

Parâmetros de consulta OData

Cabeçalhos de solicitação

Resposta

Função Delta em eventos (pré-visualização)

Função Delta no calendarView

Exemplos

Exemplo 1: função Delta em eventos num calendário (pré-visualização)

Solicitação

Resposta

Exemplo 2: função Delta no calendarView

Solicitação

Resposta

Conteúdo relacionado

Comentários

Recursos adicionais