Reducir las suscripciones y las notificaciones de cambio que faltan

Durante la vigencia de una suscripción, Microsoft Graph envía tipos especiales de notificaciones para ayudarle a minimizar el riesgo de que falten suscripciones y notificaciones de cambio. Estas notificaciones se denominan notificaciones de ciclo de vida.

Hay tres tipos de eventos de ciclo de vida:

• reauthorizationRequired notifications
• Notificaciones eliminadas de la suscripción
• notificaciones perdidas

Si omite estos eventos, podría interrumpir el flujo de notificación de cambios; puede controlar los eventos implementando lógica en la aplicación para reanudar un flujo de notificación de cambios continuo.

En este artículo se presentan las notificaciones de ciclo de vida en las notificaciones de cambio de Microsoft Graph y se proporcionan instrucciones para controlar las notificaciones.

Recursos admitidos

Aunque puede proporcionar un lifecycleNotificationUrl al crear una suscripción en cualquier tipo de recurso, las notificaciones de ciclo de vida solo se admiten actualmente para los siguientes tipos de recursos.

• reauthorization Notificaciones requeridas: todos los recursos
• subscriptionRemoved notifications : mensaje de Outlook, evento de Outlook, contacto personal de Outlook, chatMessage de Teams
• Notificaciones perdidas: mensaje de Outlook, evento de Outlook, contacto personal de Outlook

Configuración de la suscripción para recibir notificaciones de ciclo de vida

Para recibir notificaciones de ciclo de vida, debe proporcionar un punto de conexión lifecycleNotificationUrl válido al crear la suscripción.

La siguiente solicitud de creación de suscripción define los puntos de conexión notificationUrl y lifecycleNotificationUrl .

HTTP

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "lifecycleNotificationUrl": "https://webhook.azurewebsites.net/api/lifecycleNotifications",
  "resource": "/users/{id}/messages",
  "expirationDateTime": "2020-03-20T11:00:00.0000000Z",
  "clientState": "<secretClientState>"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Subscription
{
	ChangeType = "created,updated",
	NotificationUrl = "https://webhook.azurewebsites.net/api/resourceNotifications",
	LifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications",
	Resource = "/users/{id}/messages",
	ExpirationDateTime = DateTimeOffset.Parse("2020-03-20T11:00:00.0000000Z"),
	ClientState = "<secretClientState>",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Subscriptions.PostAsync(requestBody);

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

CLI

mgc subscriptions create --body '{\
  "changeType": "created,updated",\
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",\
  "lifecycleNotificationUrl": "https://webhook.azurewebsites.net/api/lifecycleNotifications",\
  "resource": "/users/{id}/messages",\
  "expirationDateTime": "2020-03-20T11:00:00.0000000Z",\
  "clientState": "<secretClientState>"\
}\
'

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Ir

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  "time"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewSubscription()
changeType := "created,updated"
requestBody.SetChangeType(&changeType) 
notificationUrl := "https://webhook.azurewebsites.net/api/resourceNotifications"
requestBody.SetNotificationUrl(&notificationUrl) 
lifecycleNotificationUrl := "https://webhook.azurewebsites.net/api/lifecycleNotifications"
requestBody.SetLifecycleNotificationUrl(&lifecycleNotificationUrl) 
resource := "/users/{id}/messages"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2020-03-20T11:00:00.0000000Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "<secretClientState>"
requestBody.SetClientState(&clientState) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
subscriptions, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Subscription subscription = new Subscription();
subscription.setChangeType("created,updated");
subscription.setNotificationUrl("https://webhook.azurewebsites.net/api/resourceNotifications");
subscription.setLifecycleNotificationUrl("https://webhook.azurewebsites.net/api/lifecycleNotifications");
subscription.setResource("/users/{id}/messages");
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2020-03-20T11:00:00.0000000Z");
subscription.setExpirationDateTime(expirationDateTime);
subscription.setClientState("<secretClientState>");
Subscription result = graphClient.subscriptions().post(subscription);

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
  changeType: 'created,updated',
  notificationUrl: 'https://webhook.azurewebsites.net/api/resourceNotifications',
  lifecycleNotificationUrl: 'https://webhook.azurewebsites.net/api/lifecycleNotifications',
  resource: '/users/{id}/messages',
  expirationDateTime: '2020-03-20T11:00:00.0000000Z',
  clientState: '<secretClientState>'
};

await client.api('/subscriptions')
	.post(subscription);

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Subscription;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Subscription();
$requestBody->setChangeType('created,updated');
$requestBody->setNotificationUrl('https://webhook.azurewebsites.net/api/resourceNotifications');
$requestBody->setLifecycleNotificationUrl('https://webhook.azurewebsites.net/api/lifecycleNotifications');
$requestBody->setResource('/users/{id}/messages');
$requestBody->setExpirationDateTime(new \DateTime('2020-03-20T11:00:00.0000000Z'));
$requestBody->setClientState('<secretClientState>');

$result = $graphServiceClient->subscriptions()->post($requestBody)->wait();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PowerShell

Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	changeType = "created,updated"
	notificationUrl = "https://webhook.azurewebsites.net/api/resourceNotifications"
	lifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications"
	resource = "/users/{id}/messages"
	expirationDateTime = [System.DateTime]::Parse("2020-03-20T11:00:00.0000000Z")
	clientState = "<secretClientState>"
}

New-MgSubscription -BodyParameter $params

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.subscription import Subscription
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Subscription(
	change_type = "created,updated",
	notification_url = "https://webhook.azurewebsites.net/api/resourceNotifications",
	lifecycle_notification_url = "https://webhook.azurewebsites.net/api/lifecycleNotifications",
	resource = "/users/{id}/messages",
	expiration_date_time = "2020-03-20T11:00:00.0000000Z",
	client_state = "<secretClientState>",
)

result = await graph_client.subscriptions.post(request_body)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

El punto de conexión lifecycleNotificationUrl puede ser el mismo que notificationUrl.

Las suscripciones existentes sin una propiedad lifecycleNotificationUrl no reciben las notificaciones del ciclo de vida. Para agregar la propiedad lifecycleNotificationUrl , debe quitar dichas suscripciones existentes y crear nuevas suscripciones al tiempo que especifica la propiedad durante la creación de la suscripción.

Al usar el canal de entrega de webhooks, debe validar ambos puntos de conexión.

Estructura de una notificación de ciclo de vida

Una carga de notificación del ciclo de vida sigue la estructura de changeNotificationCollection y los tipos de recursos changeNotification relacionados como se indica a continuación:

{
  "value": [
    {
      "subscriptionId":"<subscription_guid>",
      "subscriptionExpirationDateTime":"2019-03-20T11:00:00.0000000Z",
      "tenantId": "<tenant_guid>",
      "clientState":"<secretClientState>",
      "lifecycleEvent": "subscriptionRemoved or missed or reauthorizationRequired"
    }
  ]
}

El objeto lifecycleEvent puede ser subscriptionRemoved, missedo reauthorizationRequired, que representa los tipos de notificación del ciclo de vida.

Una notificación de ciclo de vida no contiene información sobre un recurso específico, porque no está relacionada con un cambio de recurso, sino con el cambio de estado de la suscripción. De forma similar a las notificaciones de cambio, las notificaciones de ciclo de vida se pueden procesar por lotes y recibirse como una colección, cada una con un valor de lifecycleEvent posiblemente diferente. Procese cada notificación de ciclo de vida del lote de la forma correspondiente.

Al procesar la notificación de ciclo de vida y reanudar el flujo de notificaciones de cambios, las notificaciones de cambio comienzan a fluir a notificationUrl.

Responder a las notificaciones de reauthorizationRequired

reauthorizationRequired Los eventos de ciclo de vida le avisan cuando Microsoft Graph requiere que la aplicación vuelva a autenticar la suscripción, por ejemplo, en los casos siguientes:

• Cuando el token de acceso está a punto de expirar.
• Cuando una suscripción está a punto de expirar.
• Cuando un administrador de inquilinos ha revocado los permisos de la aplicación para leer un recurso.

Antes de que cualquiera de estas condiciones se cumpla, Microsoft Graph envía un desafío de autorización al lifecycleNotificationUrl.

En el ejemplo de código siguiente se muestra cómo el servicio de notificaciones de cambios de Microsoft Graph puede calcular el intervalo de estas notificaciones.

    //The following code is for illustrative purposes only
    var TokenTimeToExpirationInMinutes=(TokenExpirationTime-CurrentTime)/4;

    if((TokenTimeToExpirationInMinutes)<=180 && TokenTimeToExpirationInMinutes>60){
        //Microsoft Graph will send reauthorizationRequired notification
        TokenTimeToExpirationInMinutes=TokenTimeToExpirationInMinutes/2;
    }
    elseif(TokenTimeToExpirationInMinutes<60 && TokenTimeToExpirationInMinutes>=0){
            //Microsoft Graph will send reauthorizationRequired notification every 15 mins
            TokenTimeToExpirationInMinutes=TokenTimeToExpirationInMinutes-15;
    } else {
      //Microsoft Graph will stop sending reauthorizationRequired notifications
    }

Los siguientes pasos representan el flujo de una impugnación de autorización para una suscripción activa:

1. Microsoft Graph requiere una suscripción para volver a ser autorizado.

   Las razones pueden variar de un recurso a otro y pueden cambiar con el tiempo. Para mantener la suscripción, debe responder a un evento de reautorización independientemente de lo que la haya causado.

2. Microsoft Graph envía una notificación para impugnar la autorización a lifecycleNotificationUrl.

   El flujo de notificaciones de cambios puede continuar durante un tiempo, lo que le da tiempo adicional para responder. Sin embargo, el envío de notificaciones finalmente se detiene hasta que realice la acción requerida. Se perderán las notificaciones sobre los cambios de recursos que se produzcan cuando se pausa la entrega de notificaciones de cambios y el momento en que la aplicación vuelve a crear la suscripción correctamente. En tales casos, la aplicación debe capturar por separado esos cambios, por ejemplo, mediante la consulta delta.

Acciones a tomar

1. Confirme la recepción de la notificación del ciclo de vida respondiendo a la llamada POST con 202 - Accepted código de respuesta.

2. Valide la autenticidad de la notificación de ciclo de vida.

3. Asegúrese de que la aplicación tiene un token de acceso válido para dar el siguiente paso.

4. Llame a cualquiera de las dos API siguientes. Si la llamada a la API tiene éxito, se reanuda el flujo de notificación de cambios.

   • Llame a la /reauthorize acción para volver a autorizar la suscripción sin ampliar su fecha de expiración.

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

   • Realice una acción regular de "renovación" para volver a autorizar y renovar la suscripción al mismo tiempo.

     PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}
     Content-Type: application/json
     
     {
        "expirationDateTime": "2019-09-21T11:00:00.0000000Z"
     }
     

     La renovación puede producir un error si la aplicación ya no tiene autorización para acceder al recurso. A continuación, puede ser necesario que la aplicación obtenga un nuevo token de acceso para volver a autenticar correctamente una suscripción.

     Puede volver a intentar estas acciones más tarde, en cualquier momento, y tener éxito si las condiciones de acceso cambian.

Información adicional

• Los desafíos de autorización no reemplazan la necesidad de renovar una suscripción antes de que expire. Los ciclos de vida de los tokens de acceso y la expiración de la suscripción no son los mismos. El token de acceso puede expirar antes de la suscripción. Es importante estar preparado para volver a autenticar periódicamente el punto de conexión para actualizar el token de acceso. Volver a autorizar el punto de conexión no renovará la suscripción. Sin embargo, la renovación de la suscripción también volverá a autorizar el punto de conexión.

• La frecuencia de las impugnaciones de autorización está sujeta a cambios.

  No suponga la frecuencia de los desafíos de autorización. Estas notificaciones de ciclo de vida le indican cuándo tomar medidas, lo que evita que tenga que realizar un seguimiento de las suscripciones que requieren reautorización. Esté listo para controlar los desafíos de autorización de una vez cada pocos minutos para cada suscripción a raras veces para algunas de las suscripciones.

Responder a las notificaciones subscriptionRemoved

subscriptionRemoved los eventos de ciclo de vida le avisan cuando Microsoft Graph ha quitado una suscripción. En tales casos, si desea seguir recibiendo notificaciones de cambio para el recurso relacionado, debe volver a crear la suscripción.

Incluso si tiene una suscripción de larga duración, las condiciones de acceso a los datos de recursos pueden cambiar con el tiempo. Por ejemplo, puede producirse un evento en el servicio que requiera que la aplicación vuelva a autenticar al usuario. En tal caso, Microsoft Graph le envía una notificación subscriptionRemoved .

El flujo siguiente muestra el flujo de un evento subscriptionRemoved :

1. El servicio detecta que tiene que quitar una suscripción de Microsoft Graph.

   No hay ninguna cadencia establecida para estos eventos. Puede producirse con frecuencia para algunos recursos y casi nunca para otros.

2. Microsoft Graph envía una notificación subscriptionRemoved de ciclo de vida a lifecycleNotificationUrl (si se especificó).

   No hay ninguna notificación de ciclo de vida disponible desde el período en que se envió la subscriptionRemoved notificación de ciclo de vida a cuando la aplicación vuelve a crear la suscripción correctamente. La aplicación debe capturar esos cambios por sí sola.

Acciones a tomar

1. Confirme la recepción de la notificación del ciclo de vida respondiendo a la llamada POST con 202 - Accepted código de respuesta.

2. Valide la autenticidad de la notificación de ciclo de vida.

3. Asegúrese de que la aplicación tiene un token de acceso válido para dar el siguiente paso.

4. Cree una nueva suscripción.

   Esta acción podría producir un error, ya que las comprobaciones de autorización realizadas por el sistema podrían denegar el acceso de la aplicación al recurso. Es posible que sea necesario que la aplicación obtenga un nuevo token de acceso para volver a autenticar correctamente una suscripción. Puede repetir estas acciones en cualquier momento, por ejemplo, si cambian las condiciones de acceso.

5. Después de crear la nueva suscripción, puede sincronizar los datos del recurso para identificar las notificaciones de cambio perdidas; por ejemplo, mediante la consulta delta.

Responder a las notificaciones perdidas

missed los eventos de ciclo de vida le avisan de que es posible que algunas notificaciones de cambio no se hayan entregado. Por ejemplo, debido a la limitación.

Acciones a tomar

1. Confirme la recepción de la notificación del ciclo de vida respondiendo a la llamada POST con 202 - Accepted código de respuesta.
2. Valide la autenticidad de la notificación de ciclo de vida.
3. Realice una resincronización de datos completa del recurso para identificar los cambios que no se entregaron como notificaciones; por ejemplo, mediante la consulta delta.

Contenido relacionado

• Tipo de recurso de suscripción