event: delta

Artículo
07/05/2024

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 $select para 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. Obtenga más información sobre la autenticación y la autorización.
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



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

Importante

Los SDK de Microsoft Graph usan la versión v1.0 de la API de manera predeterminada y no admiten todos los tipos, propiedades y API disponibles en la versión beta. Para obtener más información sobre cómo acceder a la API beta con el SDK, consulte Uso de los SDK de Microsoft Graph con la API beta.

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

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



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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

Respuesta

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

Compartir a través de

event: delta

Permissions

Solicitud HTTP

Función Delta en eventos de un calendario de usuario (versión preliminar)

Función Delta en calendarView en un calendario de usuario

Función Delta en calendarView en un calendario de grupo

Parámetros de consulta

Parámetros de consulta de OData

Encabezados de solicitud

Respuesta

Función Delta en eventos (versión preliminar)

Función Delta en calendarView

Ejemplos

Ejemplo 1: Función Delta en eventos de un calendario (versión preliminar)

Solicitud

Respuesta

Ejemplo 2: Función Delta en calendarView

Solicitud

Respuesta

Comentarios

Recursos adicionales

Compartir a través de

event: delta

Permissions

Solicitud HTTP

Función Delta en eventos de un calendario de usuario (versión preliminar)

Función Delta en calendarView en un calendario de usuario

Función Delta en calendarView en un calendario de grupo

Parámetros de consulta

Parámetros de consulta de OData

Encabezados de solicitud

Respuesta

Función Delta en eventos (versión preliminar)

Función Delta en calendarView

Ejemplos

Ejemplo 1: Función Delta en eventos de un calendario (versión preliminar)

Solicitud

Respuesta

Ejemplo 2: Función Delta en calendarView

Solicitud

Respuesta

Contenido relacionado

Comentarios

Recursos adicionales