Configuración de notificaciones para cambios en los datos de recursos

  • Artículo

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.

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 la Empresa 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:
  • Por aplicación (para todos los inquilinos combinados): 50 000 suscripciones totales.
  • Por inquilino (para todas las aplicaciones combinadas): 1000 suscripciones totales en todas las aplicaciones.
  • Por combinación de aplicaciones e inquilinos: 100 suscripciones totales.

    No se admite para inquilinos de Azure AD B2C.

    NOTA: La creación y eliminación temporal de grupos también desencadenan changeTypeupdated.
    		•
    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.
    callRecord de Teams Cambios en todos los registros de llamadas: /communications/callRecords Cuotas de suscripción permitidas:
  • Por organización: 100 suscripciones totales.

    NOTA: La creación de registros de llamadas también desencadena el updatedchangeType.
    		•
    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:
  • Por aplicación y combinación de reuniones en línea: 1
  • Por aplicación y combinación de usuario: 1
  • Por usuario (para las suscripciones que realizan el seguimiento de las grabaciones en todas las aplicaciones en línea organizadas por el usuario): 10 suscripciones.
  • Por organización: 10 000 suscripciones totales.
    		•
    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:
  • Por aplicación y combinación de reuniones en línea: 1
  • Por aplicación y combinación de usuario: 1
  • Por usuario (para las transcripciones de seguimiento de suscripciones en todas las webMeetings organizadas por el usuario): 10 suscripciones.
  • Por organización: 10 000 suscripciones totales.
    		•
    Chat de Teams Cambios en cualquier chat del inquilino: /chats

    Cambios en un chat específico: /chats/{id}

    Cambios en todos los chats de una organización donde está instalada una aplicación de Teams determinada: /appCatalogs/teamsApps/{id}/installedToChats    		 Cuotas de suscripción permitidas:
  • Por aplicación y combinación de chat: 1 suscripción.
  • Por organización: 10 000 suscripciones totales.
    		•
    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:
  • Por aplicación y canal o combinación de chat: 1 suscripción.
  • Por usuario (para suscripciones que realiza el seguimiento de mensajes de chat en todos los chats de los que el usuario forma parte): 10 suscripciones.
  • Por organización: 10 000 suscripciones totales.
    		•
    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:
  • Por aplicación y combinación de equipo: 1 suscripción.
  • Por organización: 10 000 suscripciones totales.
    		•
    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:
  • Por aplicación y combinación de equipo: 1 suscripción.
  • Por organización: 10 000 suscripciones totales.
    		•
    Microsoft Teams onlineMeeting* Cambios en una reunión en línea: /communications/onlineMeetings/?$filter=JoinWebUrl eq {joinWebUrl}
    Presencede Teams Cambios en la presencia de un solo usuario: /communications/presences/{id}

    Cambios en varias presencias de usuario: /communications/presences?$filter=id in ({id},{id}...)
    Equipo de Teams Cambios en cualquier equipo del inquilino: /teams

    Cambios en un equipo específico: /teams/{id}    		 Cuotas de suscripción permitidas:
  • Por aplicación y combinación de equipo: 1 suscripción.
  • Por organización: 10 000 suscripciones totales.
    		•
    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:
  • Por aplicación (para todos los inquilinos combinados): 50 000 suscripciones totales.
  • Por empresa (para todas las aplicaciones combinadas): 1000 suscripciones totales en todas las aplicaciones
  • Por combinación de aplicaciones e inquilinos: 100 suscripciones totales.

    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 changeTypeupdated.
    		•

    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)
    callRecord de Teams 4.230 minutos (menos de 3 días)
    Llamada de TeamsRegistro 4.320 minutos (3 días)
    Llamada de TeamsTranscript 4.320 minutos (3 días)
    Canal de Teams 4.320 minutos (3 días)
    Chat de Teams 4.320 minutos (3 días)
    chatmessage de Teams 4.320 minutos (3 días)
    conversationMember de Teams 4.320 minutos (3 días)
    onlineMeeting de Teams 4.320 minutos (3 días)
    Equipo de Teams 4.320 minutos (3 días)
    Conversación de grupo 4.230 minutos (menos de 3 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 4.230 minutos (menos de 3 días)
    usuario, grupo, otros recursos del directorio 41 760 minutos (menos de 29 días)
    onlineMeeting 4.230 minutos (menos de 3 días)
    presencia 60 minutos (1 hora)
    Imprimir printer 4.230 minutos (menos de 3 días)
    Imprimir printTaskDefinition 4.230 minutos (menos de 3 días)
    todoTask 4.230 minutos (menos de 3 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 3 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
    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
    onlineMeeting Menos de 10 segundos 1 minuto
    presencia Menos de 10 segundos 1 minuto
    printer Menos de 1 minuto 5 minutos
    printTaskDefinition Menos de 1 minuto 5 minutos
    team Menos de 10 segundos 60 minutos
    todoTask Menos de 2 minutos 15 minutos
    user Menos de 2 minutos 15 minutos

    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.

    Contenido relacionado