event: delta
Espacio de nombres: microsoft.graph
Importante
Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.
Obtenga un conjunto de recursos de eventos que se han agregado, eliminado o actualizado en uno o varios calendarios.
Puede obtener tipos específicos de estos cambios incrementales en los eventos de todos los calendarios de un buzón de correo o en un calendario específico, o en una colección de eventos de un calendarView (intervalo de eventos definido por fechas de inicio y finalización) de un calendario. El calendario puede ser el calendario predeterminado o algún otro calendario especificado del usuario. En el caso de obtener cambios incrementales en calendarView, el calendario también puede ser un calendario de grupo.
Normalmente, la sincronización de eventos en un calendario o calendarView en un almacén local implica una ronda de varias llamadas a funciones delta . La llamada inicial es una sincronización completa y cada llamada delta posterior en la misma ronda obtendrá los cambios incrementales (adiciones, eliminaciones o actualizaciones). Esto permite mantener y sincronizar un almacén local de eventos en el calendario especificado, sin tener que capturar todos los eventos de ese calendario del servidor cada vez.
En la tabla siguiente se enumeran las diferencias entre la función delta en eventos y la función delta en un calendarView de un calendario.
| Función Delta en eventos | Función Delta en calendarView |
|---|---|
| Obtiene los cambios incrementales de todos los eventos de un calendario no delimitados por un intervalo de fechas de inicio y finalización. Como alternativa, puede obtener cambios incrementales de los eventos en un calendario delimitado por una hora de inicio, a partir de esa fecha o hora. | Obtiene los cambios incrementales de eventos dentro de la fecha y hora de inicio y finalización de calendarView. |
Devuelve solo un conjunto limitado de propiedades de evento por motivos de rendimiento. Cliente que se usará GET /events/{id} posteriormente para expandir los eventos. |
La expansión del lado servidor devuelve un conjunto más completo de propiedades de evento . |
| La respuesta incluye instancias únicas y patrón de serie periódica. | La respuesta incluye instancias únicas y repeticiones y excepciones de series periódicas. |
| Se aplica a eventos en calendarios de usuario, pero no a calendarios de grupo. | Se aplica a eventos en calendarios de usuarios y grupos. |
| Actualmente solo está disponible en la versión beta. | Disponible en las versiones v1.0 y beta. |
Esta API está disponible en las siguientes implementaciones nacionales de nube.
| Servicio global | Gobierno de EE. UU. L4 | Us Government L5 (DOD) | China operada por 21Vianet |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
Permissions
Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.
| Tipo de permiso | Permisos con privilegios mínimos | Permisos con privilegios más altos |
|---|---|---|
| Delegado (cuenta profesional o educativa) | Calendars.ReadBasic | Calendars.Read, Calendars.ReadWrite |
| Delegado (cuenta personal de Microsoft) | Calendars.ReadBasic | Calendars.Read, Calendars.ReadWrite |
| Aplicación | Calendars.Read | Calendars.ReadBasic, Calendars.ReadWrite |
Solicitud HTTP
En esta sección se muestra la sintaxis de solicitud HTTP de la llamada de función delta inicial para iniciar una sincronización completa que recupera todos los eventos de la vista de calendario o calendario especificada. Esta sintaxis no contiene ningún token de estado.
La dirección URL de consulta devuelta en o @odata.nextLink@odata.deltaLink de una respuesta correcta incluye un token de estado. Para cualquier llamada a función delta posterior, use la dirección URL de consulta de o @odata.nextLink@odata.deltaLink anterior.
Función Delta en eventos de un calendario de usuario (versión preliminar)
Aplique la función delta en todos los eventos o eventos a partir o después de una fecha y hora específicas, en los calendarios de usuario especificados:
Para obtener cambios incrementales de todos los eventos o de eventos que comienzan en o después de la fecha y hora especificadas en el buzón del usuario:
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 obtener cambios incrementales de todos los eventos, o de eventos que comienzan en o después de la fecha y hora especificadas en el calendario predeterminado del usuario:
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 obtener cambios incrementales de todos los eventos, o de eventos que comienzan en o después de la fecha y hora especificadas en el calendario de usuario 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 obtener cambios incrementales de todos los eventos, o de eventos que comienzan en o después de la fecha y hora especificadas en el grupo de calendario y el calendario 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}
Función Delta en calendarView en un calendario de usuario
Aplique la función delta en un intervalo de eventos delimitado por fecha y hora de inicio y finalización, en el calendario de usuario especificado:
Para obtener cambios incrementales en una vista de calendario del calendario predeterminado del usuario:
GET /me/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime} GET /users/{id}/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}Para obtener cambios incrementales en una vista de calendario del calendario de usuario 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}
Función Delta en calendarView en un calendario de grupo
- Para obtener cambios incrementales en una vista de calendario del calendario de un grupo:
GET /groups/{id}/calendarView?startDateTime={start_datetime}&endDateTime={end_datetime}
Parámetros de consulta
El seguimiento de los cambios genera una ronda de una o varias llamadas de función delta . Si usa cualquier parámetro de consulta (distinto de $deltatoken y $skiptoken), debe especificarlo en la solicitud delta inicial. Microsoft Graph codifica automáticamente cualquier parámetro especificado en la parte del token de la URL @odata.nextLink o @odata.deltaLink proporcionada en la respuesta. Solo debe especificar una vez por adelantado los parámetros de consulta deseados.
En solicitudes posteriores, simplemente copie y aplique la @odata.nextLink dirección URL o @odata.deltaLink de la respuesta anterior, ya que esa dirección URL ya incluye los parámetros codificados y deseados.
| Parámetro de consulta | Tipo | Descripción |
|---|---|---|
| startDateTime | String | La fecha y hora de inicio del intervalo de tiempo, representada en formato ISO 8601. Por ejemplo, "2019-11-08T19:00:00-08:00". La zona horaria se especifica en la parte de desplazamiento de zona horaria del valor del parámetro y no se ve afectada por el Prefer: outlook.timezone encabezado si está presente. Si no se incluye ningún desplazamiento entre zonas en el valor, será interpretado como hora UTC.Opcional para delta en eventos de un calendario. Necesario para delta en calendarView. |
| endDateTime | String | La fecha y hora de finalización del intervalo de tiempo, representada en formato ISO 8601. Por ejemplo, "2019-11-08T20:00:00-08:00". La zona horaria se especifica en la parte de desplazamiento de zona horaria del valor del parámetro y no se ve afectada por el Prefer: outlook.timezone encabezado si está presente. Si no se incluye ningún desplazamiento entre zonas en el valor, será interpretado como hora UTC.No es compatible condelta en eventos de un calendario. Necesario para delta en calendarView. |
| $deltatoken | string | Un token de estado devuelto en la @odata.deltaLink dirección URL de la llamada de función delta anterior para la misma vista de calendario, que indica la finalización de esa ronda de seguimiento de cambios. Guarde y aplique toda @odata.deltaLink la dirección URL, incluido este token, en la primera solicitud de la siguiente ronda de seguimiento de cambios para esa vista de calendario. |
| $skiptoken | string | Token de estado que se devuelve en la dirección URL de @odata.nextLink de la llamada de función delta. Indica que debe realizarse el seguimiento de más cambios en la misma vista del calendario. |
Parámetros de consulta de OData
Esperar que una llamada de función delta en un calendarView devuelva las mismas propiedades que normalmente obtendría de una solicitud
GET /calendarView. No puede usar$selectpara obtener solo un subconjunto de esas propiedades.La función delta no admite los siguientes parámetros de consulta para los eventos de un calendario de usuario, ni los eventos de un calendarView:
$expand,$filter,$orderby$search, y .$select
Encabezados de solicitud
| Nombre | Tipo | Descripción |
|---|---|---|
| Authorization | string | {token} de portador. Obligatorio. |
| Content-Type | string | application/json. Necesario. |
| Prefer | string | odata.maxpagesize={x}. Opcional. |
| Prefer | string | outlook.timezone={Cadena de zona horaria}. Opcional, se supone hora UTC si no se encuentra. |
Respuesta
Función Delta en eventos (versión preliminar)
Si se ejecuta correctamente, este método devuelve un 200 OK código de respuesta y una colección de eventos en el cuerpo de la respuesta. Cada evento de la respuesta contiene solo las propiedades id, type, start y end por motivos de rendimiento. Use GET /events/{id} posteriormente para expandir los eventos de la respuesta.
Función Delta en calendarView
Si se ejecuta correctamente, este método devuelve un 200 OK código de respuesta y una colección de eventos en el cuerpo de la respuesta.
Espere obtener todas las propiedades que normalmente obtendría de una GET /calendarView solicitud.
Dentro de una ronda de llamadas de función delta enlazadas por el intervalo de fechas de un calendarView, es posible que encuentre una llamada delta que devuelva dos tipos de eventos en @removed con el motivo deleted:
- Eventos que están dentro del intervalo de fechas y que se han eliminado desde la llamada a delta anterior.
- Eventos que están fuera del intervalo de fechas y que fueron agregados, eliminados o actualizados desde la llamada delta anterior.
Filtre los eventos en @removed para el intervalo de fechas que requiera el escenario.
Ejemplos
Ejemplo 1: Función Delta en eventos de un calendario (versión preliminar)
Solicitud
En el ejemplo siguiente se muestra la solicitud de sincronización inicial para obtener eventos en el calendario predeterminado del usuario que ha iniciado sesión, que se producen en o después del parámetro especificado startDateTime . La solicitud inicial no incluye ningún token de estado.
La solicitud usa el Prefer: odata.maxpagesize encabezado para limitar el número máximo de eventos de cada respuesta a 1.
Siga llamando a la delta función mediante la consulta devuelta en @odata.nextLink hasta que obtenga una @odata.deltaLink en la respuesta.
GET https://graph.microsoft.com/beta/me/calendar/events/delta?startDateTime=2020-06-12T00:00:00Z
Prefer: odata.maxpagesize=1
Respuesta
Si la solicitud se realiza correctamente, la respuesta incluye un token de estado, que es un skipToken (en un encabezado de respuesta @odata.nextLink ) o un deltaToken (en un encabezado de respuesta @odata.deltaLink ). Respectivamente, indican si debe continuar con la ronda o si ha completado la obtención de todos los cambios para esa ronda.
La respuesta siguiente muestra un skipToken en un encabezado de respuesta de @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"
}
}
]
}
Ejemplo 2: Función Delta en calendarView
Solicitud
En el ejemplo siguiente se muestra la solicitud de sincronización inicial para obtener eventos en el calendario especificado del usuario que ha iniciado sesión, dentro del intervalo de fechas indicado por calendarView. La solicitud inicial no incluye ningún token de estado.
La solicitud usa el Prefer: odata.maxpagesize encabezado para limitar el número máximo de eventos de cada respuesta a 2. Siga llamando a la delta función mediante la consulta devuelta en @odata.nextLink hasta que obtenga todos los eventos de esa vista de calendario y un @odata.deltaLink elemento en la respuesta.
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
Respuesta
Si la solicitud se realiza correctamente, la respuesta incluye un token de estado, que es un skipToken (en un encabezado de respuesta @odata.nextLink ) o un deltaToken (en un encabezado de respuesta @odata.deltaLink ). Respectivamente, indican si debe continuar con la ronda o si ha completado la obtención de todos los cambios para esa ronda.
La respuesta siguiente muestra un skipToken en un encabezado de respuesta de @odata.nextLink.
Nota: el objeto de respuesta que se muestra aquí puede haberse acortado para mejorar la legibilidad.
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"
}
}
}
]
}
Contenido relacionado
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de