Usar la API de Microsoft Graph para obtener notificaciones de cambios

  • Artículo

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.

Precaución

Las aplicaciones existentes que usan esta característica con baseTask o baseTaskList deben actualizarse, ya que el conjunto de API de tareas pendientes basado en estos recursos está en desuso a partir del 31 de mayo de 2022. Ese conjunto de API dejará de devolver datos el 31 de agosto de 2022. Use el conjunto de API basado en todoTask.

La API REST de Microsoft Graph puede entregar notificaciones de cambios a los clientes a través de varios puntos de conexión, incluidos webhooks, Event Hubs y Event Grid. Para obtener información sobre cómo suscribirse y recibir notificaciones para la aplicación, consulte Configuración de notificaciones para cambios en los datos de usuario.

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.

    Nota: cualquiera de las rutas de acceso a los recursos que empiece por /users/{id} también pueden aceptar /me para hacer referencia al usuario que ha iniciado sesión.

    Permissions

    En general, las operaciones de suscripción requieren permiso de lectura en el recurso. Por ejemplo, para obtener notificaciones en mensajes, la aplicación necesita el permiso Mail.Read. En el artículo sobre cómo crear suscripciones se muestran los permisos necesarios para cada tipo de recurso. En la siguiente tabla aparecen los tipos de permisos que la aplicación puede solicitar para usar webhooks con tipos de recurso concretos.

    Tipo de permiso Tipos de recursos admitidos
    Delegado: cuenta profesional o educativa alert, callRecording, callTranscript, channel, chat, contact, conversation, conversationMember, driveItem, list, event, group, message, user, presence, chatMessage (preview), team, todoTask, baseTask (en desuso)
    Delegado: cuenta de Microsoft personal baseTask (en desuso), contact, driveItem, list, event, message, todoTask
    Aplicación alert, callRecording, callTranscript, channel, chat, contact, driveItem, list, event, group, message, user, callRecord, chatMessage, conversationMember, onlineMeeting, printer, printTaskDefinition, team

    Contenido relacionado