Criar assinatura

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor de versão.

Cuidado

Os aplicativos existentes que usam esse recurso com baseTask ou baseTaskList devem ser atualizados, pois o conjunto de APIs de tarefas pendentes criado com base nesses recursos foi preterido a partir de 31 de maio de 2022. Esse conjunto de API deixará de retornar dados em 31 de agosto de 2022. Use o conjunto de API criado em todoTask.

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.

Consulte a tabela na seção Permissões para obter a lista de recursos que oferecem suporte à inscrição para alterar notificações.

Alguns recursos suportam a opção de incluir dados de recursos criptografados em notificações de alteração. Esses recursos incluem chatMessage, contato, evento, mensagem, onlineMeetings e presença. Para obter mais informações, consulte Configurar notificações de alteração que incluem dados de recursos e Notificações de alteração para recursos do Outlook no Microsoft Graph.

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 nas mensagens, seu aplicativo precisa da permissão 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.

Recurso com suporte	Delegada (conta corporativa ou de estudante)	Delegada (conta pessoal da Microsoft)	Aplicativo
baseTask (preterido)	Tasks.ReadWrite	Tasks.ReadWrite	Incompatível
callRecord (/communications/callRecords)	Incompatível	Incompatível	CallRecords.Read.All
canal (/teams/getAllChannels – todos os canais em uma organização)	Incompatível	Incompatível	Channel.ReadBasic.All, ChannelSettings.Read.All
canal (/teams/{id}/channels)	Channel.ReadBasic.All, ChannelSettings.Read.All	Incompatível	Channel.ReadBasic.All, ChannelSettings.Read.All
chat chat (/conversa – todos os chats em uma organização)	Incompatível	Incompatível	Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
chat (/chats/{id})	Chat.ReadBasic, Chat.Read, Chat.ReadWrite	Sem suporte	ChatSettings.Read.Chat , ChatSettings.ReadWrite.Chat, Chat.Manage.Chat*, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
chatMessage (/teams/{id}/channels/{id}/messages)	ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All	Sem suporte	ChannelMessage.Read.Group*, ChannelMessage.Read.All
chatMessage (/teams/getAllMessages -- todas as mensagens de canal na organização)	Sem suporte	Sem suporte	ChannelMessage.Read.All
chatMessage (/chats/{id}/messages)	Chat.Read, Chat.ReadWrite	Sem suporte	Chat.Read.All
chatMessage (/teams/getAllMessages -- todas as mensagens de chat na organização)	Sem suporte	Sem suporte	Chat.Read.All
chatMessage (/users/{id}/chats/getAllMessages -- mensagens de chat para todos os chats dos quais um usuário específico faz parte)	Chat.Read, Chat.ReadWrite	Sem suporte	Chat.Read.All, Chat.ReadWrite.All
contato	Contacts.Read	Contacts.Read	Contacts.Read
conversationMember (/chats/getAllMembers)	Incompatível	Sem suporte	ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
conversationMember (/chats/{id}/members)	ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite	Incompatível	ChatMember.Read.Chat , Chat.Manage.Chat, ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
conversationMember (/teams/getAllMembers)	Incompatível	Incompatível	TeamMember.Read.All, TeamMember.ReadWrite.All
conversationMember (/teams/{id}/members)	TeamMember.Read.All	Incompatível	TeamMember.Read.All
conversationMember (/teams/{id}/channels/getAllMembers)	Incompatível	Incompatível	ChannelMember.Read.All
driveItem (OneDrive pessoal de um usuário)	Sem suporte	Files.ReadWrite	Sem suporte
driveItem (OneDrive for Business)	Files.ReadWrite.All	Sem suporte	Files.ReadWrite.All
evento	Calendars.Read	Calendars.Read	Calendars.Read
grupo	Group.Read.All	Sem suporte	Group.Read.All
conversa em grupo	Group.Read.All	Sem suporte	Sem suporte
list	Sites.ReadWrite.All	Sem suporte	Sites.ReadWrite.All
message	Mail.ReadBasic, Mail.Read	Mail.ReadBasic, Mail.Read	Mail.Read
reunião online	Sem suporte	Incompatível	OnlineMeetings.Read.All, OnlineMeetings.ReadWrite.All
presence	Presence.Read.All	Incompatível	Incompatível
printer	Sem suporte	Sem suporte	Printer.Read.All, Printer.ReadWrite.All
printTaskDefinition	Sem suporte	Sem suporte	PrintTaskDefinition.ReadWrite.All
alerta de segurança	SecurityEvents.ReadWrite.All	Sem suporte	SecurityEvents.ReadWrite.All
equipe (/teams – todas as equipes em uma organização)	Sem suporte	Incompatível	Team.ReadBasic.All, TeamSettings.Read.All
equipe (/teams/{id})	Team.ReadBasic.All, TeamSettings.Read.All	Incompatível	Team.ReadBasic.All, TeamSettings.Read.All
todoTask	Tasks.ReadWrite	Tasks.ReadWrite	Incompatível
user	User.Read.All	User.Read.All	User.Read.All

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 darão suporte a permissões de acesso de gravação quando apenas permissões de acesso de leitura forem necessárias.

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

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. Antes de criar uma assinatura chatMessage com permissões de aplicativo, talvez seja necessário solicitar acesso. Para obter detalhes, confira APIs protegidas no Microsoft Teams.

Você deve usar o cabeçalho da solicitação Prefer: include-unknown-enum-members para obter os seguintes valores nos recursos chatMessage messageType enumeração evoluível: systemEventMessage para /teams/{id}/channels/{id}/messages e /chats/{id}/messages.

Observação

/teams/getAllMessages, /chats/getAllMessages, /me/chats/getAllMessages e /users/{id}/chats/getAllMessages tem requisitos de licenciamento e pagamento. /teams/getAllMessages e /chats/getAllMessages suportam ambos parâmetros de consulta model=A e model=B, /me/chats/getAllMessages e /users/{id}/chats/getAllMessages dão suporte apenas model=B. Se nenhum modelo for especificado, o modo de avaliação será usado.

conversationMember

As assinaturas conversationMember 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.

Observação

/teams/getAllMembers e /chats/getAllMembers tem requisitos de licenciamento e pagamento. /teams/getAllMembers e /chats/getAllMembers suportam os parâmetros de consulta model=A e model=B. Se nenhum modelo for especificado, o modo de avaliação será usado.

equipe, canal e chat

assinaturas de equipe, 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.

Exemplo de solicitação

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

POST https://graph.microsoft.com/beta/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

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 inscrever as instâncias unidade 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 do Outlook e, opcionalmente, especificar no conteúdo da solicitação POST se deseja incluir dados de recursos criptografados 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, você não pode usar os Calendários de permissões delegadas. Leia 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 pastas compartilhadas 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 seus equivalentes de somente leitura), pois eles não suportam inscrições que alteram as notificações em itens de pastas compartilhadas ou delegadas.

onlineMeetings, presença

As assinaturas em onlineMeetings e 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 configurar notificações de alteração para incluir dados de recursos. Para obter detalhes sobre assinaturas de reunião online, consulte Obter notificações de alteração para reuniões online.

Solicitação HTTP

POST /subscriptions

Cabeçalhos de solicitação

Nome	Tipo	Descrição
Autorização	string	{token} de portador. Obrigatório.

Corpo da solicitação

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

Resposta

Se tiver êxito, este método retornará um código 201 Created de 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.

HTTP

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"
}

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var subscription = 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"
};

await graphClient.Subscriptions
    .Request()
    .AddAsync(subscription);

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não dão suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

JavaScript

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

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não dão suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/beta/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/subscriptions"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

MSGraphSubscription *subscription = [[MSGraphSubscription alloc] init];
[subscription setChangeType:@"created"];
[subscription setNotificationUrl:@"https://webhook.azurewebsites.net/api/send/myNotifyClient"];
[subscription setResource:@"me/mailFolders('Inbox')/messages"];
[subscription setExpirationDateTime: "2016-11-20T18:23:45.9356913Z"];
[subscription setClientState:@"secretClientValue"];
[subscription setLatestSupportedTlsVersion:@"v1_2"];

NSError *error;
NSData *subscriptionData = [subscription getSerializedDataWithError:&error];
[urlRequest setHTTPBody:subscriptionData];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não dão suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Subscription subscription = new Subscription();
subscription.changeType = "created";
subscription.notificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient";
subscription.resource = "me/mailFolders('Inbox')/messages";
subscription.expirationDateTime = OffsetDateTimeSerializer.deserialize("2016-11-20T18:23:45.9356913Z");
subscription.clientState = "secretClientValue";
subscription.latestSupportedTlsVersion = "v1_2";

graphClient.subscriptions()
    .buildRequest()
    .post(subscription);

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não dão suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestBody := msgraphsdk.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)
result, err := graphClient.Subscriptions().Post(requestBody)

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não dão suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

PowerShell

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

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não dão suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

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

Exemplos de recursos

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

Tipo de recurso	Exemplos
baseTask (preterido)	/me/tasks/lists/{Id}/tasks
Registros de chamadas	communications/callRecords
Canais	/teams/getAllChannels, /teams/{id}/channels
Chat	/chats, /chats/{id}
Mensagem de chat	chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages
Contatos	me/contacts
ConversationMember	/chats/{id}/members, /chats/getAllMembers, /teams/{id}/members, /teams/getAllMembers, /teams/{id}/channels/getAllMembers
Conversas	groups('{id}')/conversations
Unidades	me/drive/root
Eventos	me/events
Grupos	groups
Lista	sites/{site-id}/lists/{list-id}
Email	me/mailfolders('inbox')/messages, me/messages
OnlineMeetings	/communications/onlineMeetings/?$filter=JoinWebUrl eq '{JoinWebUrl}'
Presença	/communications/presences/{id} (usuário único), /communications/presences?$filter=id in ('{id}','{id}',…) (vários usuários)
impressora	print/printers/{id}/jobs
printTaskDefinition	print/taskDefinitions/{id}/tasks
Teams	/teams, /teams/{id}
Usuários	users
todoTask	/me/todo/lists/{todoTaskListId}/tasks
Alerta de segurança	security/alerts?$filter=status eq 'NewAlert'

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/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 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.