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

Para criar uma assinatura, seu aplicativo deve ter permissões de leitura para o recurso. Por exemplo, para obter notificações de alteração de mensagens, seu aplicativo precisa da Mail.Read permissão.

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.

Recomendamos que você use as permissões conforme documentado na tabela anterior. Devido a restrições de segurança, as assinaturas do Microsoft Graph não dão suporte a permissões de acesso de gravação quando apenas as permissões de acesso de leitura são necessárias.

Observação: Permissões marcadas com * usam consentimento específico de recurso.

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.

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

As limitações adicionais se aplicam aos 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 for Business, você pode assinar somente a pasta raiz. As notificações de alteração são enviadas para os tipos de alterações solicitados na pasta assinada ou em qualquer arquivo, pasta ou outras instâncias 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 for Business e Microsoft Office SharePoint Online suportam o envio de notificações de aplicaçõ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. Este cabeçalho é aplicável às contas Microsoft Office SharePoint Online e OneDrive for Business, mas não às contas OneDrive de consumo.

contato, evento e mensagem

Você pode assinar alterações nos recursos de contato,evento ou mensagem doOutlook.

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.

presença

As assinaturas na presença exigem que todos os dados de recursos incluídos em uma notificação de alteração sejam criptografados. Sempre especifique o parâmetro encryptionCertificate ao criar uma assinatura para evitar falha. Veja mais informações sobre como configurar notificações de mudança para incluir dados de recursos.

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 bem-sucedido, este método retorna o código de resposta 201 Created e um objeto subscription no corpo da resposta. Para detalhes sobre como os erros são retornados, confira Respostas de erro.

Exemplo

Solicitação

O exemplo a seguir mostra uma solicitação para enviar uma notificação de alteração quando o usuário recebe um novo email.

POST https://graph.microsoft.com/v1.0/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.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 $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"
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')
	.post(subscription);

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\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.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-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",
	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

Estes são os valores válidos da propriedade de recurso da assinatura:

Observação: qualquer caminho iniciado por me também pode ser usado com users/{id} em vez de me para direcionar um usuário específico, em vez de usar o usuário atual.

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/v1.0/$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"
}

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

O ponto de extremidade da notificação da assinatura (especificado na notificationUrl propriedade) 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.