Reduzir assinaturas ausentes e alterar notificações

No tempo de vida de uma assinatura, o Microsoft Graph envia tipos especiais de notificações para ajudar você a minimizar o risco de assinaturas ausentes e alterar notificações. Essas notificações são chamadas de notificações de ciclo de vida.

Há três tipos de eventos de ciclo de vida:

• reautorizaçãoRequiram notificações
• Notificações removidas por assinatura
• notificações perdidas

Se você ignorar esses eventos, ele poderá interromper o fluxo de notificação de alteração; você pode lidar com os eventos implementando a lógica em seu aplicativo para retomar um fluxo de notificação de alteração contínua.

Este artigo apresenta notificações de ciclo de vida em 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 ciclo de vidaNotificationUrl ao criar uma assinatura em qualquer tipo de recurso, no momento, há suporte para notificações de ciclo de vida apenas para os tipos de recursos a seguir.

• reauthorizationRequired notifications – Todos os recursos
• subscriptionRemoved notifications - Mensagem do Outlook, evento do Outlook, contato pessoal do Outlook, chatMessage do Teams
• notificações perdidas – mensagem do Outlook, evento do Outlook, contato pessoal do Outlook

Configurar sua assinatura para receber notificações de 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 .

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do 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>"\
}\
'

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do 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)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do 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);

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do 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);

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do 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();

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do 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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do 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)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

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

As assinaturas existentes sem uma propriedade lifecycleNotificationUrl não recebem as notificações do ciclo de vida. Para adicionar a propriedade lifecycleNotificationUrl , você deve remover essas assinaturas existentes e criar novas assinaturas enquanto especifica a propriedade durante a criação da assinatura.

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

Estrutura de uma notificação de ciclo de vida

Uma carga de notificação do ciclo de vida segue a estrutura do changeNotificationCollection e os tipos de recurso changeNotification relacionados 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"
    }
  ]
}

O ciclo de vidaEvent pode ser subscriptionRemoved, missedou reauthorizationRequired, representando os tipos de notificação do ciclo de vida.

Uma notificação de ciclo de vida não contém nenhuma informação sobre um recurso específico, pois 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 de ciclo de vida possivelmente diferenteEvent . 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 notificaçãoUrl.

Respondendo a notificações reauthorizationRequired

reauthorizationRequired Eventos de ciclo de vida alertam quando o Microsoft Graph exige que o aplicativo reautorize a assinatura, por exemplo, nos seguintes casos:

• Quando o token de acesso está prestes a expirar.
• Quando uma assinatura está prestes a expirar.
• Quando um administrador de locatário revogou as permissões do 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 ciclo de vidaNotificationUrl.

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 ser alterados ao longo do tempo. Para manter a assinatura, você deve responder a um evento de reautorização, não importa o que a tenha causado.

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-lhe 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 acontecem quando a entrega de notificação de alteração é pausada e a hora em que o aplicativo cria a assinatura com êxito novamente seria perdida. Nesses casos, o aplicativo deve buscar separadamente essas alterações, por exemplo, usando a consulta delta.

Ações a serem executadas

1. Reconheça o recebimento da notificação do ciclo de vida respondendo à chamada POST com 202 - Accepted 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. Chamar uma das duas APIs a seguir. Se a chamada da API for bem-sucedida, o fluxo de notificação de mudança será retomado.

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

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

   • Execute uma ação regular de "renovação" para reautorizar 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 com êxito uma assinatura.

     Você pode tentar essa ações mais tarde, a qualquer momento e obter êxito se as condições de acesso mudarem.

Informações adicionais

• Os desafios de autorização não substituem a necessidade de renovar uma assinatura antes de expirar. 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 de sua assinatura. É importante estar preparado para reautorizar regularmente seu ponto de extremidade para atualizar seu token de acesso. Reautorizar seu ponto de extremidade não renovará sua assinatura. No entanto, a renovação da assinatura também reautorizará seu ponto de extremidade.

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

  Não suponha a frequência de desafios de autorização. Essas notificações de ciclo de vida dizem quando agir, salvando você de ter que controlar quais assinaturas exigem reautorização. Esteja pronto para lidar com desafios de autorização de uma vez a cada poucos minutos para cada assinatura raramente para algumas de suas assinaturas.

Responder a notificações subscriptionRemoved

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

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

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

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ções de ciclo de vida está disponível no período em que a notificação do subscriptionRemoved ciclo de vida foi enviada quando o aplicativo recria a assinatura com êxito. O aplicativo precisa buscar essas alterações por conta própria.

Ações a serem executadas

1. Reconheça o recebimento da notificação do ciclo de vida respondendo à chamada POST com 202 - Accepted 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 executadas pelo sistema podem negar o acesso do aplicativo ao recurso. Talvez seja necessário que o aplicativo obtenha um novo token de acesso para reautorizar com êxito uma assinatura. Você pode tentar essa ações mais tarde, a qualquer momento; por exemplo, quando as condições de acesso mudarem.

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.

Responder notificações perdidas

missed Eventos de ciclo de vida alertam que algumas notificações de alteração podem não ter sido entregues. Por exemplo, devido à limitação.

Ações a serem executadas

1. Reconheça o recebimento da notificação do ciclo de vida respondendo à chamada POST com 202 - Accepted 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