Reduzir assinaturas ausentes e alterar notificações

Durante o tempo de vida de uma assinatura, o Microsoft Graph envia tipos especiais de notificações para o ciclo de vida especificadoNotificationUrl para sinalizar a ação necessária. Essas notificações são chamadas de notificações de ciclo de vida e ajudam a minimizar o risco de assinaturas perdidas e notificações de alteração.

Há três tipos de notificações de ciclo de vida:

• reauthorizationNotificações necessárias
• Notificações removidas da assinatura
• Notificações perdidas

Se você ignorar esses eventos, isso poderá interromper o fluxo de notificação de alteração; Você pode manipular os eventos implementando a lógica em seu aplicativo para retomar um fluxo contínuo de notificação de alterações.

Este artigo apresenta notificações de ciclo de vida nas notificações de alteração do Microsoft Graph e fornece diretrizes para lidar com as notificações.

Recursos com suporte

Embora você possa fornecer um lifecycleNotificationUrl ao criar uma assinatura em qualquer tipo de recurso, no momento, as notificações de ciclo de vida têm suporte apenas para os seguintes tipos de recurso.

• Notificações reauthorizationRequired - Todos os recursos
• subscriptionNotificações removidas - mensagem do Outlook, evento do Outlook, contato pessoal do Outlook, chat do TeamsMessage
• notificações perdidas - mensagem do Outlook, evento do Outlook, contato pessoal do Outlook

Configurar sua assinatura para receber notificações do ciclo de vida

Para receber notificações de ciclo de vida, você deve fornecer um ponto de extremidade lifecycleNotificationUrl válido ao criar a assinatura. A solicitação de criação de assinatura a seguir define os pontos de extremidade notificationUrl e lifecycleNotificationUrl .

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>"
}

// 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);

// 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)

// 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);

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);

<?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();

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

# 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)

O ponto de extremidade lifecycleNotificationUrl pode ser o mesmo que notificationUrl.

As assinaturas existentes sem uma propriedade lifecycleNotificationUrl não recebem as notificações do ciclo de vida. Você também não pode adicionar a propriedade lifecycleNotificationUrl a uma assinatura existente atualizando a assinatura. Para adicionar a propriedade lifecycleNotificationUrl , você deve excluir a assinatura existente e criar uma nova assinatura ao especificar a propriedade durante a criação da assinatura.

Ao usar o canal de entrega de webhooks, você deve validar os pontos de extremidade lifecycleNotificationUrl e notificationUrl.

Estrutura de uma notificação de ciclo de vida

Uma carga de notificação de ciclo de vida segue a estrutura do objeto changeNotificationCollection e do objeto changeNotification relacionado da seguinte maneira:

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

Onde o lifecycleEvent pode ser subscriptionRemoved, missed, ou reauthorizationRequired, representando os tipos de notificação do ciclo de vida.

Uma notificação de ciclo de vida não contém informações sobre um recurso específico, pois ela não está relacionada a uma alteração de recurso, mas à alteração do estado da assinatura. Semelhante às notificações de alteração, as notificações de ciclo de vida podem ser agrupadas em lote e recebidas como uma coleção, cada uma com um valor lifecycleEvent possivelmente diferente. Processe cada notificação de ciclo de vida no lote adequadamente.

Quando você processa a notificação do ciclo de vida e retoma o fluxo de notificações de alteração, as notificações de alteração começam a fluir para a notificationUrl.

reauthorizationNotificações necessárias

reauthorizationRequired Os eventos do ciclo de vida alertam você quando o Microsoft Graph exige que o aplicativo autorize novamente a assinatura, por exemplo, nos seguintes casos:

• Quando o token de acesso estiver prestes a expirar.
• Quando uma assinatura está prestes a expirar.
• Quando um administrador revogou as permissões do seu aplicativo para ler um recurso.

Antes que qualquer uma dessas condições se torne verdadeira, o Microsoft Graph envia um desafio de autorização para o lifecycleNotificationUrl.

O exemplo de código a seguir ilustra como o serviço de notificações de alteração do Microsoft Graph pode calcular o intervalo dessas notificações.

    //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
    }

As etapas a seguir representam o fluxo de um desafio de autorização para uma assinatura ativa:

1. O Microsoft Graph exige que uma assinatura seja autorizada novamente.

   Os motivos podem variar de recurso para recurso e podem mudar ao longo do tempo. Para manter a assinatura, você deve responder a um evento de reautorização, independentemente do que o causou.

2. O Microsoft Graph envia uma notificação de desafio de autorização para lifecycleNotificationUrl.

   O fluxo de notificações de alteração pode continuar por um tempo, dando a você tempo extra para responder. No entanto, eventualmente a alteração na entrega de notificação fará uma pausa até você executar a ação necessária. Todas as notificações sobre alterações de recursos que ocorrem quando a entrega da notificação de alteração é pausada e a hora em que o aplicativo cria a assinatura com êxito novamente são perdidas. Nesses casos, o aplicativo deve buscar separadamente essas alterações, por exemplo, usando a consulta delta.

Respondendo a notificações reauthorizationRequired

1. Confirme o recebimento da notificação de ciclo de vida respondendo à chamada POST com 202 - Accepted o código de resposta.

2. Valide a autenticidade da notificação do ciclo de vida.

3. Certifique-se de que o aplicativo tenha um token de acesso válido para a próxima etapa.

4. Chame uma das duas APIs a seguir. Se a chamada da API for bem-sucedida, o fluxo de notificação de mudança será retomado.

   Importante

   Não emita uma solicitação de reautorização (POST /subscriptions/{id}/reauthorize) e uma solicitação de atualização (PATCH /subscriptions/{id}) para a mesma assinatura em uma janela de 10 minutos. Enviar essas solicitações simultaneamente ou em rápida sucessão pode resultar em inconsistências no estado da assinatura. Para autorizar e renovar novamente uma assinatura na mesma solicitação, use uma única PATCH /subscriptions/{id} solicitação com uma expirationDateTime atualizada, que executa ambas as ações em uma operação.

   • Chame a /reauthorize ação para autorizar novamente a assinatura sem estender sua data de validade.

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

   • Execute a operação de atualização para autorizar novamente e renovar a assinatura ao mesmo tempo.

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

     A renovação poderá falhar se o aplicativo não estiver mais autorizado a acessar o recurso. Em seguida, pode ser necessário que o aplicativo obtenha um novo token de acesso para reautorizar uma assinatura com êxito.

     Você poderá repetir essas ações mais tarde, a qualquer momento, e obter êxito se as condições de acesso forem alteradas.

Informações adicionais

• Os desafios de autorização não substituem a necessidade de renovar uma assinatura antes que ela expire. Os ciclos de vida dos tokens de acesso e da expiração da assinatura não são os mesmos. Seu token de acesso pode expirar antes da sua assinatura. É importante estar preparado para reautorizar regularmente seu ponto de extremidade para atualizar seu token de acesso. A reautorização do ponto de extremidade não renova a assinatura. No entanto, renovar sua assinatura também autoriza novamente seu ponto de extremidade.

• A frequência dos desafios de autorização está sujeita a mudanças.

  Não assuma a frequência dos desafios de autorização. Essas notificações de ciclo de vida informam quando agir, evitando que você tenha que acompanhar quais assinaturas exigem reautorização. Esteja pronto para lidar com desafios de autorização de uma vez a cada poucos minutos para cada assinatura para raramente para algumas de suas assinaturas.

notificações de subscriptionRemoved

subscriptionRemoved Os eventos de ciclo de vida alertam você quando o Microsoft Graph remove uma assinatura. Nesses casos, se quiser continuar recebendo notificações de alteração para o recurso relacionado, você precisará recriar a assinatura.

Mesmo que você tenha uma assinatura de longa duração, as condições de acesso aos dados do recurso podem mudar ao longo do tempo. Por exemplo, pode ocorrer um evento no serviço que exija que o aplicativo autentique novamente o usuário. Nesse caso, o Microsoft Graph envia uma notificação subscriptionRemoved.

O fluxo a seguir mostra o fluxo de um evento subscriptionRemoveu :

1. O serviço detecta que uma assinatura precisa ser removida do Microsoft Graph.

   Não há cadência definida para esses eventos. Eles podem ocorrer com frequência para alguns recursos e quase nunca para outros.

2. O Microsoft Graph envia uma notificação subscriptionRemoved de ciclo de vida para lifecycleNotificationUrl (se especificado).

   Nenhuma notificação de ciclo de vida está disponível desde o período em que a subscriptionRemoved notificação de ciclo de vida foi enviada até quando o aplicativo recria a assinatura com êxito. O aplicativo precisa buscar essas alterações por conta própria.

Responder a notificações subscriptionRemoved

1. Confirme o recebimento da notificação de ciclo de vida respondendo à chamada POST com 202 - Accepted o código de resposta.

2. Valide a autenticidade da notificação do ciclo de vida.

3. Certifique-se de que o aplicativo tenha um token de acesso válido para a próxima etapa.

4. Crie uma nova assinatura.

   Essa ação pode falhar, pois as verificações de autorização realizadas pelo sistema podem negar o acesso do aplicativo ao recurso. Pode ser necessário que o aplicativo obtenha um novo token de acesso para reautorizar uma assinatura com êxito. Você pode repetir essas ações mais tarde, a qualquer momento; por exemplo, quando as condições de acesso forem alteradas.

5. Depois de criar a nova assinatura, você pode sincronizar os dados do recurso para identificar quaisquer notificações de alteração perdidas; Por exemplo, usando a consulta delta.

Notificações perdidas

missed Os eventos do ciclo de vida alertam você de que algumas notificações de alteração não foram entregues. Por exemplo, devido à limitação.

Responder notificações perdidas

1. Confirme o recebimento da notificação de ciclo de vida respondendo à chamada POST com 202 - Accepted o código de resposta.
2. Valide a autenticidade da notificação do ciclo de vida.
3. Execute uma ressincronização completa de dados do recurso para identificar as alterações que não foram entregues como notificações; Por exemplo, usando a consulta delta.

Conteúdo relacionado

• Tipo de recurso de assinatura