Configuración de notificaciones para cambios en los datos de recursos
Las notificaciones de cambio permiten que las aplicaciones reciban alertas cuando un recurso de Microsoft Graph les interesen los cambios; es decir, creado, actualizado o eliminado. Microsoft Graph envía notificaciones al punto de conexión de cliente especificado y el servicio cliente procesa las notificaciones según los requisitos empresariales. Por ejemplo, el servicio puede capturar más datos, actualizar su caché y vistas, etc.
¿Por qué obtener notificaciones de cambio?
Las notificaciones de cambio siguen un modelo controlado por eventos en el que los clientes reciben alertas cuando se producen cambios en lugar de sondear Microsoft Graph. En función de la lógica de negocios, las notificaciones de cambio son adecuadas cuando:
- Se suscribe a un recurso que cambia con frecuencia.
- Debe reaccionar ante los cambios casi en tiempo real.
- Quiere evitar sondeos frecuentes de Microsoft Graph, lo que podría provocar que se alcancen los límites de limitación.
Tipos de notificaciones de cambio
Microsoft Graph admite tres tipos de notificaciones de cambio:
- Notificaciones básicas: cambie las notificaciones que no contengan datos de recursos distintos del identificador del recurso que ha cambiado. Cuando una aplicación recibe una notificación básica, el servicio puede usar el identificador para consultar el objeto modificado.
- Notificaciones enriquecidas: cambie las notificaciones que incluyen los datos de recursos del objeto que cambió. Para obtener más información sobre las notificaciones enriquecidas, consulte Notificaciones enriquecidas.
- Notificaciones de ciclo de vida: notificaciones que alertan al cliente cuando corren el riesgo de que falten notificaciones de cambio debido al ciclo de vida de su suscripción. Para obtener más información sobre las notificaciones de ciclo de vida, consulte Notificaciones de ciclo de vida.
Recepción de notificaciones de cambio
Microsoft Graph puede entregar notificaciones de cambios a los clientes a través de los siguientes canales.
- Webhooks. Para obtener más información, consulte Recepción de notificaciones de cambio a través de webhooks.
- Azure Event Hubs. Para obtener más información, consulte Recepción de notificaciones de cambios a través de Azure Event Hubs.
- Azure Event Grid (versión preliminar). Para obtener más información, consulte Recepción de notificaciones de cambios a través de Azure Event Grid.
Administrar suscripciones
Los clientes pueden crear suscripciones, renovar suscripciones y eliminar suscripciones. Mientras la suscripción está activa y cuando se producen cambios en el recurso suscrito, Microsoft Graph envía notificaciones de cambio al punto de conexión de notificación especificado.
La suscripción se administra mediante el tipo de recurso de suscripción y sus métodos relacionados. Microsoft Graph envía notificaciones de cambio en una estructura definida en el tipo de recurso changeNotificationCollection.
Recursos admitidos
Una aplicación puede suscribirse a los cambios en los recursos de Microsoft Graph enumerados en la tabla.
Nota:
Las suscripciones a recursos marcadas con un asterisco (*) solo están disponibles en el punto de /beta conexión.
| Recurso | Rutas de acceso de recursos admitidas | Limitaciones |
|---|---|---|
| Impresora para impresión en la nube | Cambia cuando un trabajo de impresión está listo para descargarse (evento jobFetchable): /print/printers/{id}/jobs |
- |
| Impresión en la nube printTaskDefinition | Cambia cuando hay un trabajo válido en la cola (evento jobStarted): /print/printtaskdefinition/{id}/tasks |
- |
| driveItem en OneDrive (personal) | Cambios en el contenido de la jerarquía de cualquier carpeta: /users/{id}/drive/root |
- |
| driveItem en OneDrive para el trabajo o la escuela | Cambios en el contenido dentro de la jerarquía de la carpeta raíz: /drives/{id}/root , /users/{id}/drive/root |
- |
| group | Cambios en todos los grupos: /groups Cambios en un grupo específico: /groups/{id} Cambios en los propietarios de un grupo específico: /groups/{id}/owners Cambios en los miembros de un grupo específico: /groups/{id}/members |
Cuotas de suscripción permitidas: No se admite para inquilinos de Azure AD B2C. NOTA: La creación y eliminación temporal de grupos también desencadenan changeType updated. |
| lista en un sitio de SharePoint | Cambios en el contenido de la lista: /sites/{site-id}/lists/{list-id} |
- |
| conversación de grupo de Microsoft 365 | Cambios en las conversaciones de un grupo: groups/{id}/conversations |
- |
| mensaje de Outlook | Cambios en todos los mensajes del buzón de un usuario: /users/{id}/messages , /me/messages Cambios en los mensajes de la Bandeja de entrada de un usuario: /users/{id}/mailFolders('inbox')/messages , /me/mailFolders('inbox')/messages |
Se permite un máximo de 1000 suscripciones activas por buzón para todas las aplicaciones. |
| evento de Outlook | Cambios en todos los eventos del buzón de un usuario: /users/{id}/events , /me/events |
Se permite un máximo de 1000 suscripciones activas por buzón para todas las aplicaciones. |
| contacto personal de Outlook | Cambios en todos los contactos personales del buzón de un usuario: /users/{id}/contacts , /me/contacts |
Se permite un máximo de 1000 suscripciones activas por buzón para todas las aplicaciones. |
| alerta de seguridad | Cambios en una alerta específica: /security/alerts/{id} Cambios en las alertas filtradas: /security/alerts/?$filter={parameters} |
Para obtener más información, consulte alertas de API para seguridad. |
| Aprobaciones de Teams | Cambios en todas las aprobaciones de un inquilino: /solutions/approval/approvalItems |
Cuotas de suscripción permitidas: |
| callRecord de Teams | Cambios en todos los registros de llamadas: /communications/callRecords Cambios en los registros de llamada filtrados: /communications/callRecords?$filter={parameters} |
Para obtener más información, vea Cambiar notificaciones para registros de llamadas. Cuotas de suscripción permitidas: NOTA: La creación de registros de llamadas también desencadena changeType updated. |
| Llamada de TeamsRegistro | Todas las grabaciones de una organización: communications/onlineMeetings/getAllRecordings Todas las grabaciones de una reunión específica: communications/onlineMeetings/{onlineMeetingId}/recordings Una grabación de llamadas que está disponible en una reunión organizada por un usuario específico: users/{id}/onlineMeetings/getAllRecordings Grabación de llamadas que está disponible en una reunión en la que se instala una aplicación de Teams determinada: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings * |
Cuotas de suscripción permitidas: |
| Llamada de TeamsTranscript | Todas las transcripciones de una organización: communications/onlineMeetings/getAllTranscripts Todas las transcripciones de una reunión específica: communications/onlineMeetings/{onlineMeetingId}/transcripts Transcripción de llamadas que está disponible en una reunión organizada por un usuario específico: users/{id}/onlineMeetings/getAllTranscripts Transcripción de llamadas que está disponible en una reunión en la que se instala una aplicación de Teams determinada: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts * |
Cuotas de suscripción permitidas: |
| Chat de Teams | Cambios en cualquier chat del inquilino: /chats Cambios en un chat específico: /chats/{id} Cambios en un chat específico con el parámetro de consulta notifyOnUserSpecificProperties : /chats/{id}?notifyOnUserSpecificProperties={Boolean} Cambios en todos los chats de una organización donde está instalada una aplicación de Teams determinada: /appCatalogs/teamsApps/{id}/installedToChats Cambios en todos los chats de los que forma parte un usuario determinado: /users/{id}/chats Cambios en todos los chats de los que forma parte un usuario determinado con el parámetro de consulta notifyOnUserSpecificProperties : /users/{id}/chats?notifyOnUserSpecificProperties={Boolean} |
Cuotas de suscripción permitidas: |
| chatmessage de Teams | Cambios en los mensajes de chat en todos los canales de todos los equipos: /teams/getAllMessages Cambios en los mensajes de chat en un canal específico: /teams/{id}/channels/{id}/messages Cambios en los mensajes de chat en todos los chats: /chats/getAllMessages Cambios en los mensajes de chat en un chat específico: /chats/{id}/messages Los cambios en los mensajes de chat de todos los chats de los que forma parte un usuario determinado son parte de: /users/{id}/chats/getAllMessages Cambios en los mensajes de chat de todos los chats de una organización donde se instala una aplicación de Teams determinada: /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages |
Cuotas de suscripción permitidas: |
| Canal de Teams | Cambios en los canales de todos los equipos: /teams/getAllChannels Cambios en el canal en un equipo específico: /teams/{id}/channels |
Cuotas de suscripción permitidas: |
| conversationMember de Teams | Cambios en la pertenencia a un equipo específico: /teams/{id}/members Cambios en la pertenencia a todos los canales de un equipo específico: teams/{id}/channels/getAllMembers Cambios en la pertenencia a un chat específico: /chats/{id}/members Cambios en la pertenencia a todos los chats de una organización donde se instala una aplicación de Teams determinada: /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers Cambios en la pertenencia a todos los chats: /chats/getAllMembers |
Cuotas de suscripción permitidas: |
| Microsoft Teams onlineMeeting* | Cambios en una reunión en línea: /communications/onlineMeetings(joinWebUrl='{encodedJoinWebUrl}')/meetingCallEvents |
No admite el uso $select de para devolver solo las propiedades seleccionadas. La notificación enriquecida consta de todas las propiedades de la instancia modificada. Una suscripción permitida por aplicación por reunión en línea. Para obtener más información, consulte Obtención de notificaciones de cambio para las actualizaciones de eventos de llamadas a reuniones de Microsoft Teams. |
| Presencede Teams | Cambios en la presencia de un solo usuario: /communications/presences/{id} Cambios en la presencia de varios usuarios: /communications/presences?$filter=id in ({id},{id}...) |
La suscripción para la presencia de varios usuarios está limitada a 650 usuarios distintos. No admite el uso $select de para devolver solo las propiedades seleccionadas. La notificación enriquecida consta de todas las propiedades de la instancia modificada. Una suscripción permitida por aplicación por usuario delegado. Para obtener más información, consulte Obtención de notificaciones de cambios para las actualizaciones de presencia en Microsoft Teams. |
| Equipo de Teams | Cambios en cualquier equipo del inquilino: /teams Cambios en un equipo específico: /teams/{id} |
Cuotas de suscripción permitidas: |
| Oferta de turnos de TeamsMayúsRequest | Cambios en cualquier solicitud de turno de oferta en un equipo: /teams/{id}/schedule/offerShiftRequests |
Cuotas de suscripción permitidas: |
| Turnos de Teams openShiftChangeRequest | Cambios en cualquier solicitud de turno abierta en un equipo: /teams/{id}/schedule/openShiftChangeRequests |
Cuotas de suscripción permitidas: |
| Turnos de Turnos de Teams | Cambios en cualquier turno de un equipo: /teams/{id}/schedule/shifts |
Cuotas de suscripción permitidas: |
| Intercambio de turnos de TeamsShiftsChangeRequest | Cambios en cualquier solicitud de cambio de turno en un equipo: /teams/{id}/schedule/swapShiftsChangeRequests |
Cuotas de suscripción permitidas: |
| Teams Desplaza timeOffRequest | Cambios en cualquier solicitud de tiempo de descuento en un equipo: /teams/{id}/schedule/timeOffRequests |
Cuotas de suscripción permitidas: |
| todoTask | Cambios en todas las tareas de una lista de tareas específica: /me/todo/lists/{todoTaskListId}/tasks |
- |
| user | Cambios en todos los usuarios: /users Cambios en un usuario específico: /users/{id} |
Cuotas de suscripción permitidas: No se admite para cuentas personales de Microsoft como outlook.com. No se admite para inquilinos de Azure AD B2C. NOTA: La creación y eliminación temporal de usuarios también desencadenan changeType updated. |
Nota:
Muchos recursos tienen límites o cuotas sobre cuántas suscripciones se pueden realizar en ese recurso. Cuando se supera ese límite, los intentos de crear una suscripción producirán una 403 Forbidden respuesta de error. La propiedad message de la respuesta de error explicará el límite que se ha superado.
Algunos de estos recursos admiten notificaciones enriquecidas (notificaciones con datos de recursos). Para obtener más información sobre los recursos que admiten notificaciones enriquecidas, consulte Configuración de notificaciones de cambio que incluyen datos de recursos.
Duración de la suscripción
Las suscripciones tienen una duración limitada. Las aplicaciones deben renovar sus suscripciones antes de la hora de expiración; De lo contrario, deben crear una nueva suscripción. Las aplicaciones también pueden cancelar la suscripción en cualquier momento para dejar de recibir notificaciones.
En la tabla siguiente se muestran los tiempos máximos de expiración de las suscripciones por recurso en Microsoft Graph.
| Resource | Tiempo de expiración máximo |
|---|---|
| Alerta de seguridad | 43 200 minutos (menos de 30 días) |
| Aprobaciones de Teams | 43 200 minutos (menos de 30 días) |
| callRecord de Teams | 4.230 minutos (menos de tres días) |
| Llamada de TeamsRegistro | 4.320 minutos (tres días) |
| Llamada de TeamsTranscript | 4.320 minutos (tres días) |
| Canal de Teams | 4.320 minutos (tres días) |
| Chat de Teams | 4.320 minutos (tres días) |
| chatmessage de Teams | 4.320 minutos (tres días) |
| conversationMember de Teams | 4.320 minutos (tres días) |
| onlineMeeting de Teams | 4.320 minutos (tres días) |
| Equipo de Teams | 4.320 minutos (tres días) |
| Teams teamsAppInstallation | 4.320 minutos (3 días) |
| Oferta de turnos de TeamsMayúsRequest | 360 minutos (6 horas) |
| Turnos de Teams openShiftChangeRequest | 360 minutos (6 horas) |
| Turnos de Turnos de Teams | 360 minutos (6 horas) |
| Intercambio de turnos de TeamsShiftsChangeRequest | 360 minutos (6 horas) |
| Teams Desplaza timeOffRequest | 360 minutos (6 horas) |
| Conversación de grupo | 4.230 minutos (menos de tres días) |
| driveItem de OneDrive | 42 300 minutos (menos de 30 días) |
| lista de SharePoint | 42 300 minutos (menos de 30 días) |
| Mensaje, evento, contacto de Outlook | 10 080 minutos (menos de siete días) |
| usuario, grupo, otros recursos del directorio | 41 760 minutos (menos de 29 días) |
| onlineMeeting | 4.230 minutos (menos de tres días) |
| presencia | 60 minutos (1 hora) |
| Imprimir printer | 4.230 minutos (menos de tres días) |
| Imprimir printTaskDefinition | 4.230 minutos (menos de tres días) |
| todoTask | 4.230 minutos (menos de tres días) Los webhooks para este recurso solo están disponibles en el punto de conexión global y no en las nubes nacionales. |
| baseTask (en desuso) | 4.230 minutos (menos de tres días) |
Nota: Las nuevas aplicaciones y las aplicaciones existentes no deben superar el valor admitido. En el futuro, se producirá un error en las solicitudes para crear o renovar una suscripción si se supera el valor máximo.
Latencia
En la siguiente tabla se muestra una lista de la latencia esperada entre el momento en que ocurren los eventos en el servicio y el envío de la notificación de cambios.
| Recurso | Latencia promedio | Latencia máxima |
|---|---|---|
| alerta1 | Menos de 3 minutos | 5 minutos |
| Aprobaciones | Menos de 10 segundos | 40 segundos |
| calendar | Menos de 1 minuto | 3 minutos |
| callRecord | Menos de 15 minutos | 60 minutos |
| callRecording | Menos de 10 segundos | 60 minutos |
| callTranscript | Menos de 10 segundos | 60 minutos |
| channel | Menos de 10 segundos | 60 minutos |
| chat | Menos de 10 segundos | 60 minutos |
| chatMessage | Menos de 10 segundos | 1 minuto |
| contact | Menos de 1 minuto | 3 minutos |
| conversation | Unknown | Unknown |
| conversationMember | Menos de 10 segundos | 60 minutos |
| driveItem | Menos de 1 minuto | 5 minutos |
| event | Unknown | Unknown |
| group | Unknown | Unknown |
| list | Menos de 1 minuto | 5 minutos |
| message | Menos de 1 minuto | 3 minutos |
| offerShiftRequest | Menos de 1 minuto | 60 minutos |
| onlineMeeting | Menos de 10 segundos | 1 minuto |
| openShiftChangeRequest | Menos de 1 minuto | 60 minutos |
| presencia | Menos de 10 segundos | 1 minuto |
| printer | Menos de 1 minuto | 5 minutos |
| printTaskDefinition | Menos de 1 minuto | 5 minutos |
| shift | Menos de 1 minuto | 60 minutos |
| swapShiftsChangeRequest | Menos de 1 minuto | 60 minutos |
| team | Menos de 10 segundos | 60 minutos |
| teamsAppInstallation | Menos de 10 segundos | 60 minutos |
| timeOffRequest | Menos de 1 minuto | 60 minutos |
| todoTask | Menos de 2 minutos | 15 minutos |
| user | Unknown | Unknown |
1 La latencia proporcionada para el recurso de alerta solo es aplicable después de crear la alerta. No incluye el tiempo que tarda una regla en crear una alerta a partir de los datos.
Ejemplos de código
Los siguientes ejemplos de código están disponibles en GitHub.
- Módulo de aprendizaje de Microsoft Graph: Uso de Notificaciones de cambios y Control de cambios en Microsoft Graph
- Ejemplo de webhooks de Microsoft Graph para Node.js
- Muestra de webhooks de Microsoft Graph para ASP.NET Core
- Muestra de webhooks de Microsoft Graph para Java Spring