Configurar las notificaciones de cambios en los datos de usuarioSet up notifications for changes in user data

La API de Microsoft Graph utiliza un mecanismo webhook para entregar notificaciones a los clientes. Un cliente es un servicio web que configura su propia dirección URL para recibir notificaciones. Las aplicaciones cliente utilizan notificaciones para actualizar su estado cuando se producen cambios.The Microsoft Graph API uses a webhook mechanism to deliver notifications to clients. A client is a web service that configures its own URL to receive notifications. Client apps use notifications to update their state upon changes.

Microsoft Graph acepta la solicitud de suscripción y después envía las notificaciones a la dirección URL especificada en la suscripción.After Microsoft Graph accepts the subscription request, it pushes notifications to the URL specified in the subscription. La aplicación actúa entonces según su lógica de negocios.The app then takes action according to its business logic. Por ejemplo, captura más datos, actualiza la caché y las vistas, etc.For example, it fetches more data, updates its cache and views, etc.

Recursos admitidosSupported resources

Mediante la API de Microsoft Graph, una aplicación puede suscribirse a cambios en los siguientes recursos:Using the Microsoft Graph API, an app can subscribe to changes on the following resources:

Puede crear una suscripción a una carpeta específica de Outlook, como la Bandeja de entrada: me/mailFolders('inbox')/messagesYou can create a subscription to a specific Outlook folder such as the Inbox: me/mailFolders('inbox')/messages

O a un recurso de nivel superior: me/messages, me/contacts, me/events, users o groupsOr to a top-level resource: me/messages, me/contacts, me/events, users, or groups

O a una instancia de recurso específica: users/{id}, groups/{id}, groups/{id}/conversationsOr to a specific resource instance: users/{id}, groups/{id}, groups/{id}/conversations

O a cualquier carpeta de OneDrive personal de un usuario: /drives/{id}/root /drives/{id}/root/subfolderOr to any folder in a user's personal OneDrive: /drives/{id}/root /drives/{id}/root/subfolder

O a la carpeta raíz de una unidad de SharePoint u OneDrive para la Empresa: /drive/rootOr to the root folder of a SharePoint/OneDrive for Business drive: /drive/root

O a una nueva alerta de la API de seguridad: /security/alerts?$filter=status eq ‘New’, /security/alerts?$filter=vendorInformation/provider eq ‘ASC’Or to a new Security API alert: /security/alerts?$filter=status eq ‘New’, /security/alerts?$filter=vendorInformation/provider eq ‘ASC’

Limitaciones de los recursos de Azure ADAzure AD resource limitations

Se aplican ciertos límites a los recursos basados en Azure AD (usuarios y grupos), y generarán algunos errores si se superan:Certain limits apply to Azure AD based resources (users, groups) and will generate errors when exceeded:

Nota: estos límites no se aplican a recursos de servicios distintos de Azure AD.Note: These limits do not apply to resources from services other than Azure AD. Por ejemplo, una aplicación puede crear muchas más suscripciones a recursos de message o event, que son compatibles con el servicio de Exchange Online como parte de Microsoft Graph.For example, an app can create many more subscriptions to message or event resources, which are supported by the Exchange Online service as part of Microsoft Graph.

  • Cuotas de suscripción permitidas:Maximum subscription quotas:

    • Por aplicación: 50 000 suscripciones en totalPer app: 50,000 total subscriptions
    • Por espacio empresarial: 1000 suscripciones en total en todas las aplicacionesPer tenant: 1000 total subscriptions across all apps
    • Por aplicación y espacio empresarial: 100 suscripciones en totalPer app and tenant combination: 100 total subscriptions

Cuando se superan los límites, si se intenta crear una suscripción dará como resultado una respuesta de error - 403 Forbidden.When the limits are exceeded, attempts to create a subscription will result in an error response - 403 Forbidden. La propiedad message indica qué límite se ha superado.The message property will explain which limit has been exceeded.

  • No se admiten los espacios empresariales de Azure AD B2C.Azure AD B2C tenants are not supported.

  • No se admiten notificaciones de entidades de usuario en cuentas Microsoft personales.Notification for user entities are not supported for personal Microsoft accounts.

Duración de la suscripciónSubscription lifetime

Las suscripciones tienen una duración limitada.Subscriptions have a limited lifetime. Las aplicaciones tienen que renovar sus suscripciones antes de la fecha de expiración.Apps need to renew their subscriptions before the expiration time. De lo contrario tendrán que crear otra suscripción.Otherwise, they need to create a new subscription. Para obtener una lista de las fechas de expiración máximas, consulte Duración máxima de la suscripción por tipo de recurso.For a list of maximum expiration times, see Maximum length of subscription per resource type.

Las aplicaciones también pueden cancelar la suscripción en cualquier momento para dejar de recibir notificaciones.Apps can also unsubscribe at any time to stop getting notifications.

Administrar suscripcionesManaging subscriptions

Los clientes pueden crear suscripciones, renovar suscripciones y eliminar suscripciones.Clients can create subscriptions, renew subscriptions, and delete subscriptions.

Crear una suscripciónCreating a subscription

La creación de una suscripción es el primer paso para empezar a recibir notificaciones de un recurso. El proceso de suscripción es el siguiente:Creating a subscription is the first step to start receiving notifications for a resource. The subscription process is as follows:

  1. El cliente envía una solicitud de suscripción (POST) a un recurso específico.The client sends a subscription (POST) request for a specific resource.

  2. Microsoft Graph comprueba la solicitud.Microsoft Graph verifies the request.

    • Si la solicitud es válida, Microsoft Graph envía un token de validación a la dirección URL de notificación.If the request is valid, Microsoft Graph sends a validation token to the notification URL.
    • Si la solicitud no es válida, Microsoft Graph envía una respuesta de error con el código y los detalles.If the request is invalid, Microsoft Graph sends an error response with code and details.
  3. El cliente envía el token de validación a Microsoft Graph.The client sends the validation token back to Microsoft Graph.

  4. Microsoft Graph envía una respuesta al cliente.The Microsoft Graph sends a response back to the client.

El cliente debe almacenar el identificador de suscripción para establecer la correlación de las notificaciones con la suscripción.The client must store the subscription ID to correlate notifications with the subscription.

Ejemplo de solicitud de suscripciónSubscription request example

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json
{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/notificationClient",
  "resource": "/me/mailfolders('inbox')/messages",
  "expirationDateTime": "2016-03-20T11:00:00.0000000Z",
  "clientState": "SecretClientState"
}

Se necesitan las propiedades changeType, notificationUrl, resource y expirationDateTime.The changeType, notificationUrl, resource, and expirationDateTime properties are required. Vea las definiciones y los valores de las propiedades en Tipo de recurso de suscripción.See subscription resource type for property definitions and values.

La propiedad resource Especifica el recurso al que se le supervisarán los cambios.The resource property specifies the resource that will be monitored for changes. Por ejemplo, puede crear una suscripción a una carpeta de correo específica: me/mailFolders('inbox')/messages o en representación de otro usuario dado por el consentimiento de un administrador: users/john.doe@onmicrosoft.com/mailFolders('inbox')/messages.For example, you can create a subscription to a specific mail folder: me/mailFolders('inbox')/messages or on behalf of a user given by an administrator consent: users/john.doe@onmicrosoft.com/mailFolders('inbox')/messages.

Aunque clientState no se necesita, tiene que incluirse para cumplir nuestro proceso de control de notificaciones recomendado.Although clientState is not required, you must include it to comply with our recommended notification handling process. El establecimiento de esta propiedad le permitirá confirmar que las notificaciones que recibe proceden del servicio de Microsoft Graph.Setting this property will allow you to confirm that notifications you receive originate from the Microsoft Graph service. Por eso, el valor de la propiedad debe permanecer secreto y ser conocido solo por la aplicación y el servicio de Microsoft Graph.For this reason, the value of the property should remain secret and known only to your application and the Microsoft Graph service.

Si se ejecuta correctamente, Microsoft Graph muestra un código 201 Created y un objeto subscription en el cuerpo.If successful, Microsoft Graph returns a 201 Created code and a subscription object in the body.

Validación de extremo de notificaciónNotification endpoint validation

Microsoft Graph valida el extremo de notificación indicado en la propiedad notificationUrl de la solicitud de suscripción antes de crear la suscripción.Microsoft Graph validates the notification endpoint provided in the notificationUrl property of the subscription request before creating the subscription. El proceso de validación es el siguiente:The validation process occurs as follows:

  1. Microsoft Graph envía una solicitud POST a la dirección URL de notificación:Microsoft Graph sends a POST request to the notification URL:

    POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}
    

    Importante: Como el validationToken es un parámetro de consulta, el cliente debe descodificarlo correctamente, según las prácticas de codificación de HTTP.Important: Since the validationToken is a query parameter it must be properly decoded by the client, as per HTTP coding practices. Si el cliente no descodifica el token y usa en su lugar el valor codificado en el paso siguiente (respuesta), se producirá un error de validación.If the client does not decode the token, and instead uses the encoded value in the next step (response), validation will fail. Además, el cliente debe tratar el valor de token como opaco, ya que el formato de token puede cambiar en el futuro, sin aviso.Also, the client should treat the token value as opaque since the token format may change in the future, without notice.

  2. El cliente debe proporcionar una respuesta con las siguientes características en menos de 10 segundos:The client must provide a response with the following characteristics within 10 seconds:

    • Un código de estado 200 (Correcto).A 200 (OK) status code.
    • El tipo de contenido debe ser text/plain.The content type must be text/plain.
    • El cuerpo debe incluir el token de validación proporcionado por Microsoft Graph.The body must include the validation token provided by Microsoft Graph.

El cliente debe descartar el token de validación después de incluirlo en la respuesta.The client should discard the validation token after providing it in the response.

Renovar una suscripciónRenewing a subscription

El cliente puede renovar una suscripción con una fecha de expiración específica de hasta tres días desde el momento de la solicitud.The client can renew a subscription with a specific expiration date of up to three days from the time of request. La propiedad expirationDateTime es obligatoria.The expirationDateTime property is required.

Ejemplo de renovación de la suscripciónSubscription renewal example

PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}
Content-Type: application/json

{
  "expirationDateTime": "2016-03-22T11:00:00.0000000Z"
}

Si se ejecuta correctamente, Microsoft Graph muestra un código 200 OK y un objeto subscription en el cuerpo.If successful, Microsoft Graph returns a 200 OK code and a subscription object in the body. El objeto "suscription" incluye el nuevo valor de expirationDateTime.The subscription object includes the new expirationDateTime value.

Eliminar una suscripciónDeleting a subscription

El cliente puede dejar de recibir notificaciones al eliminar la suscripción con su identificador.The client can stop receiving notifications by deleting the subscription using its ID.

DELETE https://graph.microsoft.com/v1.0/subscriptions/{id}

Si se ejecuta correctamente, Microsoft Graph devuelve un código 204 No Content.If successful, Microsoft Graph returns a 204 No Content code.

NotificacionesNotifications

El cliente comienza a recibir notificaciones después de crear la suscripción.The client starts receiving notifications after creating the subscription. Microsoft Graph envía una solicitud POST a la dirección URL de notificación cuando cambia el recurso.Microsoft Graph sends a POST request to the notification URL when the resource changes. Las notificaciones solo se envían para los cambios del tipo especificado en la suscripción, por ejemplo, created.Notification are sent only for the changes of the type specified in the subscription, for example, created.

Nota: Cuando se utilizan varias suscripciones que supervisan el mismo tipo de recurso y usan la misma dirección URL de notificación, se puede enviar una solicitud POST que contenga varias notificaciones con distintos identificadores de suscripción.Note: When using multiple subscriptions that monitor the same resource type and use the same notification URL, a POST can be sent that will contain multiple notifications with different subscription IDs. No hay ninguna garantía de que todas las notificaciones de la solicitud POST pertenezcan a una única suscripción.There is no guarantee that all notifications in the POST will belong to a single subscription.

Propiedades de la notificaciónNotification properties

El objeto "notification" tiene las propiedades siguientes:The notification object has the following properties:

PropiedadProperty TipoType DescripciónDescription
subscriptionIdsubscriptionId stringstring Identificador de la suscripción que generó la notificación.The ID of the subscription that generated the notification.
subscriptionExpirationDateTimesubscriptionExpirationDateTime dateTimedateTime Fecha de expiración de la suscripción.The expiration time for the subscription.
clientStateclientState stringstring Propiedad clientState especificada en la solicitud de suscripción (en su caso).The clientState property specified in the subscription request (if any).
changeTypechangeType stringstring Tipo de evento que generó la notificación.The event type that caused the notification. Por ejemplo, created al recibir un correo o updated al marcar un mensaje como leído.For example, created on mail receive, or updated on marking a message read.
resourceresource stringstring URI del recurso relativo a https://graph.microsoft.com.The URI of the resource relative to https://graph.microsoft.com.
resourceDataresourceData objectobject El contenido de esta propiedad depende del tipo de recurso al que se suscriba.The content of this property depends on the type of resource being subscribed to.

Por ejemplo, para recursos de Outlook, resourceData contiene los siguientes campos:For example, for Outlook resources, resourceData contains the following fields:

PropiedadProperty TipoType DescripciónDescription
@odata.type@odata.type stringstring Tipo de entidad OData en Microsoft Graph que describe el objeto representado.The OData entity type in Microsoft Graph that describes the represented object.
@odata.id@odata.id stringstring Identificador OData del objeto.The OData identifier of the object.
@odata.etag@odata.etag stringstring Etiqueta de entidad HTTP que representa una versión del objeto.The HTTP entity tag that represents the version of the object.
idid stringstring Identificador del objeto.The identifier of the object.

Nota: El valor id proporcionado en resourceData es válido en el momento en que se genera la notificación.Note: The id value provided in resourceData is valid at the time the notification was generated. Algunas acciones, como mover un mensaje a otra carpeta, pueden dar lugar a que el id ya no sea válido cuando se procese la notificación.Some actions, such as moving a message to another folder, may result in the id no longer being valid when the notification is processed.

Ejemplo de notificaciónNotification example

Cuando el usuario recibe un correo electrónico, Microsoft Graph envía una notificación como la siguiente:When the user receives an email, Microsoft Graph sends a notification like the following:

{
  "value": [
    {
      "subscriptionId":"<subscription_guid>",
      "subscriptionExpirationDateTime":"2016-03-19T22:11:09.952Z",
      "clientState":"secretClientValue",
      "changeType":"created",
      "resource":"users/{user_guid}@<tenant_guid>/messages/{long_id_string}",
      "resourceData":
      {
        "@odata.type":"#Microsoft.Graph.Message",
        "@odata.id":"Users/{user_guid}@<tenant_guid>/Messages/{long_id_string}",
        "@odata.etag":"W/\"CQAAABYAAADkrWGo7bouTKlsgTZMr9KwAAAUWRHf\"",
        "id":"<long_id_string>"
      }
    }
  ]
}

Tenga en cuenta que el campo value es una matriz de objetos.Note the value field is an array of objects. Si hay muchas notificaciones en cola, puede que Microsoft Graph envíe varios elementos en una sola solicitud.When there are many queued notifications, Microsoft Graph may send multiple items in a single request. Pueden incluirse notificaciones de distintas suscripciones en una misma solicitud de notificación.Notifications from different subscriptions can be included in the same notification request.

Procesar la notificaciónProcessing the notification

Cada notificación que reciba la aplicación debe procesarse.Each notification received by your app should be processed. Estas son las tareas mínimas que debe realizar la aplicación para procesar una notificación:The following are the minimum tasks that your app must perform to process a notification:

  1. Validar la propiedad clientState.Validate the clientState property. Debe coincidir con el valor enviado originalmente con la solicitud de creación de suscripción.It must match the value originally submitted with the subscription creation request.

    Nota: Si no es así, no debe considerar la notificación como válida.Note: If this isn't true, you should not consider this a valid notification. Es posible que la notificación no se haya originado en Microsoft Graph y que haya sido enviada por un actor no autorizado.It is possible that the notification has not originated from Microsoft Graph and may have been sent by a rogue actor. También debe investigar de dónde proviene la notificación y tomar las medidas adecuadas.You should also investigate where the notification comes from and take appropriate action.

  2. Actualizar la aplicación según la lógica empresarial.Update your application based on your business logic.

  3. Enviar un código de estado 202 - Accepted en la respuesta a Microsoft Graph.Send a 202 - Accepted status code in your response to Microsoft Graph. Si Microsoft Graph no recibe un código de clase 2xx, intentará volver a enviar la notificación varias veces.If Microsoft Graph doesn't receive a 2xx class code, it will retry the notification a number of times.

    Nota: Debe enviar un código de estado 202 - Accepted, aunque la propiedad clientState no coincida con la enviada en la solicitud de suscripción.Note: You should send a 202 - Accepted status code even if the clientState property doesn't match the one submitted with the subscription request. Esto es recomendable, ya que evita que un posible actor no autorizado descubra que tal vez usted no confíe en sus notificaciones y usar esta información para adivinar el valor de la propiedad clientState.This is a good practice as it prevents a potential rogue actor from discovering the fact that you may not trust their notifications, and perhaps using that information to guess the value of the clientState property.

Repita esto para otras notificaciones de la solicitud.Repeat for other notifications in the request.

Ejemplos de códigoCode samples

Los siguientes ejemplos de código están disponibles en GitHub.The following code samples are available on GitHub.

Recursos adicionalesSee also