Criar assinatura

Namespace: microsoft.graph

Inscreve um aplicativo de ouvinte para receber notificações de alterações quando o tipo de alteração solicitado ocorrer no recurso especificado no Microsoft Graph.

Para identificar os recursos para os quais você pode criar assinaturas e as limitações de assinaturas, consulte Configurar notificações de alterações nos dados do recurso: Recursos com suporte.

Alguns recursos dão suporte a notificações avançadas, ou seja, notificações que incluem dados de recursos. Para obter mais informações sobre esses recursos, consulte Configurar notificações de alteração que incluem dados de recursos: Recursos com suporte.

Essa API está disponível nas seguintes implantações de nuvem nacional.

Permissões

A criação de uma assinatura requer permissão de leitura para o recurso. Por exemplo, para receber notificações de alteração em mensagens, seu aplicativo precisa das permissões Mail.Read.

Dependendo do recurso e do tipo de permissão (delegado ou aplicativo) solicitado, a permissão especificada na tabela a seguir é a menos privilegiada necessária para fazer chamadas a esta API. Para saber mais, incluindo ter cuidado antes de escolher as permissões, pesquise as permissões a seguir em Permissões.

chatMessage

As assinaturas chatMessage podem ser especificadas para incluir dados de recursos (includeResourceData definido como true). Nesse caso, a criptografia é necessária e a criação da assinatura falhará se um encryptionCertificate não for especificado para essas assinaturas.

Use o cabeçalho da Prefer: include-unknown-enum-members solicitação para obter os seguintes valores em chatMessage, messageType, enumeração evolutiva: systemEventMessage for /teams/{id}/channels/{id}/messages e /chats/{id}/messages resource.

conversationMember

As assinaturas conversationMember podem ser especificadas para incluir dados de recursos (includeResourceData definido como true). Nesse caso, a criptografia é necessária e a criação da assinatura falhará se um encryptionCertificate não for especificado para essas assinaturas.

Equipe, canal e chat

As assinaturas de equipe, canal e chat podem ser especificadas para incluir dados de recursos (includeResourceData definido como true). Nesse caso, a criptografia é necessária e a criação da assinatura falhará se um encryptionCertificate não for especificado para essas assinaturas.

Você pode usar o parâmetro da cadeia de caracteres de consulta notifyOnUserSpecificProperties ao assinar alterações em um chat específico ou no nível do usuário. Quando você define o parâmetro de cadeia de caracteres de consulta notifyOnUserSpecificProperties durante true a criação da assinatura, dois tipos de conteúdo são enviados ao assinante. Um tipo contém propriedades específicas do usuário e o outro é enviado sem elas. Para obter mais informações, consulte Obter notificações de alteração para chats usando o Microsoft Graph.

aiInsights

As assinaturas no Copilot AI Insights exigem uma licença válida do Copilot que inclua o seguinte plano de serviço do Copilot:

• Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960

aiInteraction

As assinaturas nas interações de IA do Copilot exigem uma licença válida do Copilot que inclua o seguinte plano de serviço do Copilot:

• Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960

Para assinaturas direcionadas a interações de IA do Copilot das quais um determinado usuário faz parte, o usuário no caminho do recurso deve ter os planos de serviço anteriores atribuídos a ele em um estado válido.

Para assinaturas que direcionam interações de IA do Copilot para todo o locatário, o locatário deve ter licenças válidas provisionadas que incluam todos os planos de serviço anteriores do Copilot.

driveItem

Mais limitações se aplicam a assinaturas em itens do OneDrive. As limitações se aplicam para criação e gerenciamento de assinaturas (receber, atualizar e excluir assinaturas).

No OneDrive pessoal, você pode se inscrever em qualquer pasta raiz ou qualquer subpasta da unidade. No OneDrive corporativo ou de estudante, você pode assinar apenas a pasta raiz. As notificações de alteração são enviadas para as alterações solicitadas na pasta assinada ou em qualquer arquivo, pasta ou outras instâncias de driveItem em sua hierarquia. Você não pode se inscrever em instâncias de drive ou driveItem que não sejam pastas, como arquivos individuais.

OneDrive para trabalho ou escola e suporte do SharePoint enviando ao seu aplicativo notificações de eventos de segurança que ocorrem em um driveItem. Para se inscrever nestes eventos, adicionar o cabeçalho prefer:includesecuritywebhooks a sua solicitação para criar uma assinatura. Após a criação da assinatura, você receberá notificações quando as permissões sobre uma mudança de item forem alteradas. Esse cabeçalho se aplica ao SharePoint e ao OneDrive corporativo ou de estudante, mas não a contas de consumidor do OneDrive.

contato, evento e mensagem

Você pode assinar as alterações nos recursos de contato, evento ou mensagem do Outlook e, opcionalmente, especificar no conteúdo da solicitação POST se deseja incluir dados de recursos criptografados nas notificações.

Criar e gerenciar (obter, atualizar e excluir) uma assinatura requer um escopo de leitura para o recurso. Por exemplo, para receber notificações de alteração nas mensagens, seu aplicativo precisa da permissão Mail.Read. As notificações de alteração do Outlook dão suporte a escopos de permissão de aplicativo e delegados. Observe as seguintes limitações:

• A permissão delegada dá suporte a inscrição de itens em pastas apenas na caixa de correio do usuário conectado. Por exemplo, você não pode usar a permissão delegada Calendars.Read para assinar eventos na caixa de correio de outro usuário.

• Se inscrever para alterar as notificações de contatos, eventos no Outlook ou mensagens em pastascompartilhadas ou delegadas:

  • Usar a permissão de aplicativos correspondentes para inscrever as alterações dos itens em uma pasta ou uma caixa de correio de qualquer usuários no locatário.
  • Não use as permissões de compartilhamento do Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared e suas contrapartes de leitura/gravação), pois elas não dão suporte à assinatura para notificações de alteração em itens em pastas compartilhadas ou delegadas.

onlineMeetings, presença

As assinaturas em onlineMeetingse presença exigem a propriedade encryptionCertificate e encryptionCertificateId ao criar uma assinatura para notificações com dados de recursos criptografados. Para obter mais informações, consulte Configuração de notificações de alteração para incluir dados de recursos. Para obter detalhes sobre assinaturas de reuniões online, consulte Obter notificações de alteração para reuniões online.

virtualEventWebinar e virtualEventTownhall

As assinaturas em eventos virtuais dão suporte apenas a notificações básicas e estão limitadas a algumas entidades de um evento virtual. Para obter mais informações sobre os tipos de assinatura com suporte, consulte Obter notificações de alteração para atualizações de eventos virtuais do Microsoft Teams.

Solicitação HTTP

POST /subscriptions

Cabeçalhos de solicitação

Corpo da solicitação

No corpo da solicitação, forneça uma representação JSON do objeto de assinatura.

Resposta

Se for bem-sucedido, esse método retornará um código de 201 Created resposta e um objeto de assinatura no corpo da resposta.

Para detalhes sobre como os erros são retornados, confira Respostas de erro.

Exemplo

Solicitação

No corpo da solicitação, forneça uma representação JSON do objeto subscription. Os campos clientState e latestSupportedTlsVersion são opcionais.

Essa solicitação cria uma assinatura para notificações de alteração sobre novos emails recebidos pelo usuário conectado no momento.

POST https://graph.microsoft.com/beta/subscriptions
Content-type: application/json

{
   "changeType": "created",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "me/mailFolders('Inbox')/messages",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue",
   "latestSupportedTlsVersion": "v1_2"
}

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

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = new Subscription
{
	ChangeType = "created",
	NotificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient",
	Resource = "me/mailFolders('Inbox')/messages",
	ExpirationDateTime = DateTimeOffset.Parse("2016-11-20T18:23:45.9356913Z"),
	ClientState = "secretClientValue",
	LatestSupportedTlsVersion = "v1_2",
};

// 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 $v0.*

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

requestBody := graphmodels.NewSubscription()
changeType := "created"
requestBody.SetChangeType(&changeType) 
notificationUrl := "https://webhook.azurewebsites.net/api/send/myNotifyClient"
requestBody.SetNotificationUrl(&notificationUrl) 
resource := "me/mailFolders('Inbox')/messages"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2016-11-20T18:23:45.9356913Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "secretClientValue"
requestBody.SetClientState(&clientState) 
latestSupportedTlsVersion := "v1_2"
requestBody.SetLatestSupportedTlsVersion(&latestSupportedTlsVersion) 

// 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");
subscription.setNotificationUrl("https://webhook.azurewebsites.net/api/send/myNotifyClient");
subscription.setResource("me/mailFolders('Inbox')/messages");
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2016-11-20T18:23:45.9356913Z");
subscription.setExpirationDateTime(expirationDateTime);
subscription.setClientState("secretClientValue");
subscription.setLatestSupportedTlsVersion("v1_2");
Subscription result = graphClient.subscriptions().post(subscription);

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
   changeType: 'created',
   notificationUrl: 'https://webhook.azurewebsites.net/api/send/myNotifyClient',
   resource: 'me/mailFolders(\'Inbox\')/messages',
   expirationDateTime: '2016-11-20T18:23:45.9356913Z',
   clientState: 'secretClientValue',
   latestSupportedTlsVersion: 'v1_2'
};

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

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


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

$requestBody = new Subscription();
$requestBody->setChangeType('created');
$requestBody->setNotificationUrl('https://webhook.azurewebsites.net/api/send/myNotifyClient');
$requestBody->setResource('me/mailFolders(\'Inbox\')/messages');
$requestBody->setExpirationDateTime(new \DateTime('2016-11-20T18:23:45.9356913Z'));
$requestBody->setClientState('secretClientValue');
$requestBody->setLatestSupportedTlsVersion('v1_2');

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

Import-Module Microsoft.Graph.Beta.ChangeNotifications

$params = @{
	changeType = "created"
	notificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient"
	resource = "me/mailFolders('Inbox')/messages"
	expirationDateTime = [System.DateTime]::Parse("2016-11-20T18:23:45.9356913Z")
	clientState = "secretClientValue"
	latestSupportedTlsVersion = "v1_2"
}

New-MgBetaSubscription -BodyParameter $params

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.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",
	notification_url = "https://webhook.azurewebsites.net/api/send/myNotifyClient",
	resource = "me/mailFolders('Inbox')/messages",
	expiration_date_time = "2016-11-20T18:23:45.9356913Z",
	client_state = "secretClientValue",
	latest_supported_tls_version = "v1_2",
)

result = await graph_client.subscriptions.post(request_body)

No corpo da solicitação, forneça uma representação JSON do objeto subscription. Os campos clientState e latestSupportedTlsVersion são opcionais.

Comportamento de assinatura duplicada

Assinaturas duplicadas não são permitidas. Quando uma solicitação de assinatura contém os mesmos valores para changeType e resource que uma assinatura existente contém, a solicitação falha com um código 409 Conflictde erro HTTP e a mensagem Subscription Id <> already exists for the requested combinationde erro .

Exemplos de recursos

A seguir estão os valores válidos para a propriedade de recurso.

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "created",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2",
  "notificationContentType": "application/json"
}

Exemplo 2: criar uma assinatura direcionada a um ponto de extremidade de Push da Web

O exemplo a seguir cria uma assinatura que fornece notificações de alteração criptografadas para um ponto de extremidade de Push da Web nativo do navegador (como web.push.apple.com, fcm.googleapis.com, ou updates.push.services.mozilla.com).

Antes de criar essa assinatura, o aplicativo baseado em navegador deve:

1. Chame a função getVapidPublicKey na coleção de assinaturas para obter a chave pública VAPID do Microsoft Graph (RFC 8292).
2. Ligue PushManager.subscribe({ applicationServerKey: <vapidPublicKey> }) para se registrar no serviço de push do navegador. O navegador retorna um PushSubscription contendo endpoint, p256dh, e auth valores.

Em seguida, o aplicativo cria a assinatura com a notificationUrl definida como a URL do ponto de extremidade do serviço de push simples e as propriedades vapidPublicKey, webPushEncryptionP256dhPublicKey e webPushEncryptionSecret definidas para os valores retornados pelo navegador. Após a criação, o Microsoft Graph criptografa cada notificação por RFC 8291 usando as chaves armazenadas e assina a solicitação com VAPID antes de postar no serviço de push.

Solicitação

POST https://graph.microsoft.com/beta/subscriptions
Content-type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://web.push.apple.com/QKmFUwSBFK8g7iY4t1...",
  "resource": "me/mailFolders('Inbox')/messages",
  "expirationDateTime": "2026-12-31T11:00:00.0000000Z",
  "clientState": "secretClientValue",
  "vapidPublicKey": "BNKm...base64url-encoded-server-vapid-public-key...",
  "webPushEncryptionP256dhPublicKey": "BNcR...base64url-encoded-client-public-key...",
  "webPushEncryptionSecret": "tBHI...base64url-encoded-auth-secret..."
}

Observação: A propriedade webPushEncryptionSecret é somente gravação. Nunca é retornado nas GET respostas (retornado como null). Trate o valor como um segredo.

Validação de ponto de extremidade de notificação

O ponto de extremidade de notificação de assinatura (especificado na propriedade notificationUrl ) deve ser capaz de responder a uma solicitação de validação, conforme descrito em Configurar notificações para alterações nos dados do usuário. Se a validação falhar, a solicitação para criar a assinatura retornará um erro de Solicitação Incorreta 400.