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 pode criar subscrições e as limitações das subscrições, veja Configurar notificações para alterações nos dados de recursos: Recursos suportados.

Alguns recursos suportam notificações avançadas, ou seja, notificações que incluem dados de recursos. Para obter mais informações sobre estes recursos, veja Configurar notificações de alteração que incluem dados de recursos: Recursos suportados.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Permissões

A criação de uma subscrição requer permissão de leitura para o recurso. Por exemplo, para receber notificações de alteração em mensagens, a sua aplicação 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

chatMessage assinaturas podem ser especificadas para incluir dados de recurso. Se especificado para incluir dados de recurso (includeResourceData definido como true), encryption é necessária. A criação de assinatura falhará se um encryptionCertificate não for especificado para tais assinaturas.

Tem de utilizar o cabeçalho do Prefer: include-unknown-enum-members pedido para obter os seguintes valores no chatMessagemessageTypeenum evoluível: systemEventMessage para /teams/{id}/channels/{id}/messages e /chats/{id}/messages recurso.

conversationMember

conversationMember subscriptions can be specified to include resource data. Se especificado para incluir dados de recurso (includeResourceData definido como true), encryption é necessária. A criação de assinatura falhará se um encryptionCertificate não for especificado.

equipa, canal e chat

as subscrições de equipa, canal e chat podem ser especificadas para incluir dados de recursos. Se especificado para incluir dados de recurso (includeResourceData definido como true), encryption é necessária. A criação de assinatura falhará se um encryptionCertificate não for especificado.

Pode utilizar o parâmetro de cadeia de consulta notifyOnUserSpecificProperties quando subscrever alterações num chat específico ou ao nível do utilizador. Quando define o parâmetro de cadeia de consulta notifyOnUserSpecificProperties como durante a true criação da subscrição, são enviados dois tipos de payloads para o subscritor. Um tipo contém propriedades específicas do utilizador e o outro é enviado sem eles. Para obter mais informações, consulte Obter notificações de alteração para conversas com o Microsoft Graph.

Exemplo de solicitação

Especifique o parâmetro de consulta model na propriedade recurso no corpo da solicitação.

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

{
   "changeType": "created",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "chats/getAllMessages?model=A",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue",
   "latestSupportedTlsVersion": "v1_2"
}

driveItem

Aplicam-se mais limitações às subscrições 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 para trabalho ou escola, pode subscrever apenas a pasta raiz. As notificações de alteração são enviadas para as alterações pedidas na pasta subscrita ou em qualquer ficheiro, pasta ou outras instâncias driveItem na respetiva hierarquia. Não pode subscrever instâncias drive ou driveItem que não sejam pastas, como ficheiros individuais.

O OneDrive para trabalho ou escola e o SharePoint suportam o envio de notificações de eventos de segurança da sua aplicação que ocorrem num 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 aplica-se ao SharePoint e ao OneDrive para contas escolares ou profissionais, mas não para consumidores do OneDrive.

contato, evento e mensagem

Pode subscrever alterações nos recursos de contactos, eventos ou mensagens do Outlook e, opcionalmente, especificar no payload do pedido POST se pretende incluir dados de recursos encriptados em 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, não pode utilizar a permissão delegada Calendários.Ler para subscrever eventos na caixa de correio de outro utilizador.

• 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 utilize as permissões de partilha do Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared e os seus homólogos de leitura/escrita), uma vez que não suportam a subscrição para alterar notificações de itens em pastas partilhadas ou delegadas.

onlineMeetings, presença

As subscrições em onlineMeetings e presença requerem a propriedade encryptionCertificate e encryptionCertificateId ao criar uma subscrição para notificações com dados de recursos encriptados. Para obter mais informações, veja Configurar notificações de alteração para incluir dados de recursos. Para obter detalhes sobre subscrições de reuniões online, consulte Obter notificações de alteração para reuniões online.

virtualEventWebinar

As subscrições em eventos virtuais suportam apenas notificações básicas e estão limitadas a algumas entidades de um evento virtual. Para obter mais informações sobre os tipos de subscrição suportados, veja 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, este método devolve um 201 Created código de resposta e um objeto de subscrição 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.

Este pedido cria uma subscrição para notificações de alteração sobre o novo e-mail recebido pelo utilizador atualmente com sessão iniciada.

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://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Subscriptions.PostAsync(requestBody);

mgc-beta subscriptions create --body '{\
   "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 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://video2.skills-academy.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://video2.skills-academy.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 duplicado da subscrição

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

Exemplos de recursos

Seguem-se valores válidos para a propriedade do 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"
}

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

O ponto final de notificação da subscrição (especificado na propriedade notificationUrl ) tem de ser capaz de responder a um pedido de validação, conforme descrito em Configurar notificações para alterações nos dados do utilizador. Se a validação falhar, a solicitação para criar a assinatura retornará um erro de Solicitação Incorreta 400.