Reduzir assinaturas ausentes e alterar notificações

Durante a duração de uma subscrição, o Microsoft Graph envia tipos especiais de notificações para o ciclo de vida especificadoNotificationUrl para sinalizar a ação necessária. Estas notificações são denominadas notificações de ciclo de vida e ajudam-no a minimizar o risco de falta de subscrições e de notificações de alteração.

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

• reauthorizationRequired notifications (reautorização) Notificações necessárias
• Notificações removidas da subscrição
• notificações perdidas

Se ignorar estes eventos, este poderá interromper o fluxo de notificação de alteração; pode processar os eventos ao implementar lógica na sua aplicação para retomar um fluxo de notificação de alteração contínua.

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

Recursos com suporte

Embora possa fornecer um ciclo de vidaNotificationUrl ao criar uma subscrição em qualquer tipo de recurso, as notificações de ciclo de vida são atualmente suportadas apenas para os seguintes tipos de recursos.

• reauthorizationRequired notifications - All resources (reauthorizationRequired notifications - All resources)
• subscriptionRemoved notifications - Outlook message, Outlook event, Outlook personal contact, Teams chatMessage
• notificações perdidas – Mensagem do Outlook, evento do Outlook, contacto pessoal do Outlook

Configurar a sua subscrição para receber notificações de ciclo de vida

Para receber notificações de ciclo de vida, tem de fornecer um ponto final de lifecycleNotificationUrl válido ao criar a subscrição. O seguinte pedido de criação de subscrição define os pontos finais 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 projeto e criar uma instância 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 projeto e criar uma instância 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 projeto e criar uma instância 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 projeto e criar uma instância 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 projeto e criar uma instância 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 projeto e criar uma instância 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 projeto e criar uma instância 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 projeto e criar uma instância authProvider .

O ponto final lifecycleNotificationUrl pode ser o mesmo que o notificationUrl.

As subscrições existentes sem a propriedade lifecycleNotificationUrl não recebem as notificações de ciclo de vida. Também não pode adicionar a propriedade lifecycleNotificationUrl a uma subscrição existente ao atualizar a subscrição. Para adicionar a propriedade lifecycleNotificationUrl , tem de eliminar a subscrição existente e criar uma nova subscrição ao especificar a propriedade durante a criação da subscrição.

Ao utilizar o canal de entrega de webhooks, tem de validar os pontos finais de lifecycleNotificationUrl e notificationUrl.

Estrutura de uma notificação de ciclo de vida

Um payload de notificação de ciclo de vida segue a estrutura do objeto changeNotificationCollection e o objeto changeNotification relacionado da seguinte forma:

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

Em que o ciclo de vidaEvento pode ser subscriptionRemoved, missedou reauthorizationRequired, a representar 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, porque não está relacionada com uma alteração de recursos, mas sim com a alteração do estado da subscrição. À semelhança das notificações de alteração, as notificações de ciclo de vida podem ser agrupadas em conjunto e recebidas como uma coleção, cada uma com um valor de ciclo de vida Possivelmente diferenteEvento . Processe cada notificação de ciclo de vida no lote adequadamente.

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

reauthorizationRequired notifications (reautorização) Notificações necessárias

reauthorizationRequired Os eventos de ciclo de vida alertam-no quando o Microsoft Graph requer que a aplicação reautorize a subscrição, por exemplo, nos seguintes casos:

• Quando o token de acesso está prestes a expirar.
• Quando uma subscrição está prestes a expirar.
• Quando um administrador tiver revogado as permissões da sua aplicação para ler um recurso.

Antes de qualquer uma destas condições se tornar verdadeira, o Microsoft Graph envia um desafio de autorização para o ciclo de vidaNotificationUrl.

O seguinte exemplo de código ilustra como o serviço de notificações de alteração do Microsoft Graph pode calcular o intervalo destas 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 subscrição, tem de responder a um evento de reautorização, independentemente da causa.

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 durante algum 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. Quaisquer notificações sobre alterações de recursos que ocorram quando a entrega da notificação de alteração é interrompida e a hora em que a aplicação cria a subscrição novamente com êxito são perdidas. Nestes casos, a aplicação deve obter separadamente essas alterações, por exemplo, utilizando a consulta delta.

Respondendo a notificações reauthorizationRequired

1. Confirme a receção da notificação de ciclo de vida ao responder à 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. 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 subscrição sem prolongar a data de expiração.

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

   • Execute a operação de atualização para reautorizar e renovar a subscrição 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 a aplicação já não estiver autorizada a aceder ao recurso. Em seguida, poderá ser necessário que a aplicação obtenha um novo token de acesso para reautorizar uma subscrição com êxito.

     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 subscrição antes de esta expirar. Os ciclos de vida dos tokens de acesso e da expiração da subscrição não são os mesmos. O token de acesso pode expirar antes da sua subscrição. É importante estar preparado para reautorizar regularmente o ponto final para atualizar o token de acesso. Reautorizar o ponto final não renova a sua subscrição. No entanto, renovar a sua subscrição também reautoriza o ponto final.

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

  Não assuma a frequência dos desafios de autorização. Estas notificações de ciclo de vida indicam-lhe quando deve tomar medidas, impedindo-o de controlar quais as subscrições que necessitam de reautorização. Esteja pronto para lidar com desafios de autorização a cada poucos minutos para cada subscrição raramente para algumas das suas subscrições.

subscriptionRemoved notifications (notificações subscriptionRemoved)

subscriptionRemoved Os eventos de ciclo de vida alertam-no quando o Microsoft Graph removeu uma subscrição. Nesses casos, se quiser continuar a receber notificações de alteração para o recurso relacionado, terá de recriar a subscrição.

Mesmo que tenha uma subscrição de longa duração, as condições de acesso aos dados dos recursos podem mudar ao longo do tempo. Por exemplo, pode ocorrer um evento no serviço que requer que a aplicação reautentica o utilizador. Nesse caso, o Microsoft Graph envia-lhe uma notificação subscriptionRemoved .

O fluxo seguinte 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 estes 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).

   Não existem notificações de ciclo de vida disponíveis a partir do período em que a subscriptionRemoved notificação de ciclo de vida foi enviada para quando a aplicação recria a subscrição com êxito. A aplicação tem de obter essas alterações por si só.

Responder a notificações subscriptionRemoved

1. Confirme a receção da notificação de ciclo de vida ao responder à 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.

   Esta ação pode falhar porque as verificações de autorização realizadas pelo sistema podem negar o acesso da aplicação ao recurso. Poderá ser necessário que a aplicação obtenha um novo token de acesso para reautorizar uma subscrição com êxito. Pode repetir estas ações mais tarde, em qualquer altura; por exemplo, quando as condições de acesso mudam.

5. Depois de criar a nova subscrição, pode sincronizar os dados do recurso para identificar as notificações de alteração perdidas; por exemplo, com a consulta delta.

notificações perdidas

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

Responder notificações perdidas

1. Confirme a receção da notificação de ciclo de vida ao responder à 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 de dados completa do recurso para identificar as alterações que não foram entregues como notificações; por exemplo, com a consulta delta.

Conteúdo relacionado

• Tipo de recurso de assinatura