Nota
L'accés a aquesta pàgina requereix autorització. Podeu provar d'iniciar la sessió o de canviar els directoris.
L'accés a aquesta pàgina requereix autorització. Podeu provar de canviar els directoris.
Las notificaciones de cambios permiten a las aplicaciones recibir alertas cuando cambia un recurso de Microsoft Graph en el que están interesadas; es decir, crear, actualizar o eliminar. Microsoft Graph envía notificaciones al punto de conexión de cliente especificado y el servicio de cliente procesa las notificaciones de acuerdo con los requisitos empresariales. Por ejemplo, el servicio puede capturar más datos, actualizar su caché y vistas, etc.
Importante
La característica de notificaciones de cambios no se admite en el Id. externo de Microsoft Entra en inquilinos externos y de Azure AD B2C.
¿Por qué recibir notificaciones de cambios?
Las notificaciones de cambios siguen un modelo basado en 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 cambios son adecuadas cuando:
- Se está suscribiendo a un recurso que cambia con frecuencia.
- Debe reaccionar a los cambios casi en tiempo real.
- Desea evitar sondear con frecuencia Microsoft Graph, lo que podría hacer que alcance los límites de limitación.
La imagen siguiente muestra cómo funcionan las notificaciones de cambios y cómo se compara con el seguimiento de cambios.
En el siguiente vídeo se proporciona información general sobre las notificaciones de cambios en Microsoft Graph.
Tipos de notificaciones de cambios
Microsoft Graph admite tres tipos de notificaciones de cambio:
- Notificaciones básicas: notificaciones de cambio que no contienen datos de recursos distintos del identificador del recurso que cambió. Cuando una aplicación recibe una notificación básica, el servicio puede usar el identificador para consultar el objeto cambiado.
- Notificaciones enriquecidas: notificaciones de cambio que incluyen los datos de recursos del objeto que cambió. Para obtener más información sobre las notificaciones enriquecidas, vea Notificaciones enriquecidas.
- Notificaciones de ciclo de vida: notificaciones que alertan al cliente cuando corre el riesgo de que no se reciba ninguna notificación de cambio debido al ciclo de vida de su suscripción. Para obtener más información sobre las notificaciones del ciclo de vida, consulte Notificaciones del ciclo de vida.
Recibir notificaciones de cambios
Microsoft Graph puede enviar notificaciones de cambios a los clientes a través de los siguientes canales.
- Webhooks. Para obtener más información, consulte Recibir notificaciones de cambios 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. 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 cambios al punto de conexión de notificación especificado.
Puede administrar la suscripción mediante el tipo de recurso de suscripción y sus métodos relacionados. Microsoft Graph envía notificaciones de cambios 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. Las suscripciones a recursos marcados con un asterisco (*) solo están disponibles en el punto de /beta conexión.
Nota:
Para los recursos de Microsoft Teams, el límite por organización de 10 000 suscripciones totales se comparte acumulativamente entre todas las suscripciones de notificación de cambio de Teams en el inquilino. Incluye suscripciones creadas para diferentes recursos de Teams, como chats, mensajes de chat, transcripciones de llamadas, grabaciones de llamadas, canales, equipos y miembros de conversaciones, que cuentan para la misma cuota organizativa. Cuando el número combinado de suscripciones activas de Teams alcanza este límite, se produce un 403 Forbidden error en cualquier solicitud de creación de suscripción adicional para un recurso de Teams.
| Recurso | Rutas de acceso de recursos admitidas | Limitaciones |
|---|---|---|
| Impresora para impresión en la nube | Cambios 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 |
- |
| Copilot aiInsights | Información de IA de Copilot de las reuniones de las que forma parte un usuario determinado: /copilot/users/{userId}/onlineMeetings/getAllAiInsights Información de IA de Copilot para una reunión en particular: /copilot/users/{userId}/onlineMeetings/{onlineMeetingId}/aiInsights |
Cuotas de suscripción máximas para AI Insights en todas las reuniones de un usuario:
Cuotas de suscripción máximas para obtener información de IA de una reunión específica:
|
| Copilot aiInteraction | Interacciones de IA de Copilot de las que forma parte un usuario concreto: copilot/users/{userId}/interactionHistory/getAllEnterpriseInteractions Interacciones de IA de Copilot en una organización: copilot/interactionHistory/getAllEnterpriseInteractions |
Cuotas de suscripción permitidas:
|
| driveItem en OneDrive (personal) | Cambios en el contenido dentro 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 la eliminación temporal de grupos también activan changeType updated. |
| Alerta de supervisión de mantenimiento de Microsoft Entra | Cambios en todas las alertas de supervisión de estado: /reports/healthmonitoring/alerts Cambios en un tipo específico de alerta: /reports/healthmonitoring/alert con la propiedad en Carga útil notificationQueryOptions de la solicitud establecida como $filter=alertType eq '{alertType}' |
- |
| 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 la API para seguridad. |
| Aprobaciones de Teams | Cambios en todas las aprobaciones de un espacio empresarial: /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 llamadas filtrados: /communications/callRecords?$filter={parameters} |
Para obtener más información, consulte Cambiar notificaciones para registros de llamadas. Cuotas de suscripción permitidas:
NOTA: La creación de registros de llamada también activa el updatedchangeType. |
| Grabación de llamadas de Teams | 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 llamada que está disponible en una reunión organizada por un usuario específico: users/{id}/onlineMeetings/getAllRecordings Una grabación de llamada que está disponible en una reunión en la que está instalada una aplicación de Teams determinada: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings * |
Cuotas de suscripción permitidas:
|
| Teams callTranscript | Todas las transcripciones de una organización: communications/onlineMeetings/getAllTranscripts Todas las transcripciones de una reunión específica: communications/onlineMeetings/{onlineMeetingId}/transcripts Una transcripción de llamada que está disponible en una reunión organizada por un usuario específico: users/{id}/onlineMeetings/getAllTranscripts Una transcripción de llamada que está disponible en una reunión en la que está instalada una aplicación de Teams determinada: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts * |
Cuotas de suscripción permitidas:
|
| Chat de Teams | Cambios en cualquier chat del espacio empresarial: /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 concreto: /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 Cambios en los mensajes de chat en todos los chats de los que forma parte un usuario determinado: /users/{id}/chats/getAllMessages Cambios en los mensajes de chat para todos los chats de una organización donde está instalada 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 de 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 de todos los chats de una organización donde está instalada 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:
|
| Reunión en línea de Teams* | Cambios en una reunión en línea: /communications/onlineMeetings(joinWebUrl='{encodedJoinWebUrl}')/meetingCallEvents |
No se admite el uso $select 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 Obtener notificaciones de cambios para las actualizaciones de eventos de llamadas de reunión 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 se admite el uso $select 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 Obtener 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 TeamsShiftRequest | Cambios en cualquier oferta solicitud de turno en un equipo: /teams/{id}/schedule/offerShiftRequests |
Cuotas de suscripción permitidas:
|
| Turnos de Teams openShiftChangeRequest | Cambios en cualquier solicitud de turno abierto en un equipo: /teams/{id}/schedule/openShiftChangeRequests |
Cuotas de suscripción permitidas:
|
| Turno de Turnos de Teams | Cambios en cualquier turno de un equipo: /teams/{id}/schedule/shifts |
Cuotas de suscripción permitidas:
|
| Cambios de turnos de Teams swapShiftsChangeRequest | Cambios en cualquier solicitud de cambio de turno en un equipo: /teams/{id}/schedule/swapShiftsChangeRequests |
Cuotas de suscripción permitidas:
|
| Turnos de Teams timeOffRequest | Cambios en cualquier solicitud de tiempo libre 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 para todos los usuarios: /users Cambios en un usuario específico: /users/{id} |
Cuotas de suscripción permitidas:
No se admite con cuentas personales de Microsoft como outlook.com. No se admite para inquilinos de Azure AD B2C. NOTA: La creación y la eliminación temporal de usuarios también activan changeType updated. |
Nota:
Muchos recursos tienen límites o cuotas en el número de suscripciones que se pueden realizar en ese recurso. Cuando se supere ese límite, los intentos de crear una suscripción producirán una respuesta de 403 Forbidden error.
La propiedad message de la respuesta de error explicará el límite que se ha excedido.
Algunos de estos recursos admiten notificaciones enriquecidas (notificaciones con datos de recursos). Para obtener más información, consulte Configurar notificaciones de cambios que incluyan 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, tendrán que 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 |
|---|---|
| Copilot aiInteraction | 4,320 minutos (tres días) |
| 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) |
| Grabación de llamadas de Teams | 4,320 minutos (tres días) |
| Teams callTranscript | 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 TeamsShiftRequest | 360 minutos (6 horas) |
| Turnos de Teams openShiftChangeRequest | 360 minutos (6 horas) |
| Turno de Turnos de Teams | 360 minutos (6 horas) |
| Cambios de turnos de Teams swapShiftsChangeRequest | 360 minutos (6 horas) |
| Turnos de Teams 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) En el caso de las suscripciones con datos de recursos (suscripciones de notificación enriquecidas), la duración de la suscripción es de 1440 minutos (menos de un día). |
| 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. |
| Alerta de supervisión de mantenimiento de Microsoft Entra | 42.300 minutos (menos de 30 días) |
| baseTask (obsoleto) | 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 |
|---|---|---|
| aiInteracción | Menos de 10 segundos | 60 minutos |
| Alerta1 | Menos de 3 minutos | 5 minutos |
| Aprobaciones | Menos de 10 segundos | 40 segundos |
| calendar | Menos de 1 minuto | 3 minutos |
| callRecord2 | Menos de 30 minutos | 150 minutos |
| grabación de llamadas | Menos de 10 segundos | 240 minutos 3 |
| Transcripción de llamadas | Menos de 10 segundos | 240 minutos 3 |
| 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 | 6 horas |
| event | Unknown | Unknown |
| group | Unknown | Unknown |
| alerta de supervisión de mantenimiento | Unknown | Unknown |
| list | Menos de 1 minuto | 6 horas |
| 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.
2 La latencia proporcionada para el recurso callRecord solo es aplicable a la primera versión de un registro de llamada. Las versiones posteriores de un registro de llamada pueden actualizarse más allá de las latencias indicadas.
3 Las notificaciones de cambio para grabaciones de llamadas y transcripciones de llamadas generalmente se entregan dentro de los 10 segundos posteriores a la grabación y generación de la transcripción, lo que puede ocurrir varios minutos después de que finalice la llamada.
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