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 nas assinaturas, consulte Configurar notificações para alterações nos dados de recursos: recursos com suporte.

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

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

Serviço global Governo dos EUA L4 GOVERNO DOS EUA L5 (DOD) China operada pela 21Vianet

Permissões

Criar uma assinatura exige o escopo de leitura do recurso. Por exemplo, para receber notificações de alterações por mensagens, seu aplicativo precisa da permissãoMail.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) Application
callRecord (/communications/callRecords) Incompatível Incompatível CallRecords.Read.All
callRecording
communications/onlineMeetings/getAllRecordings
Todas as gravações em uma organização.
Sem suporte. Sem suporte. OnlineMeetingRecording.Read.All
callRecording
communications/onlineMeetings/{onlineMeetingId}/recordings
Todas as gravações para uma reunião específica.
OnlineMeetingRecording.Read.All Sem suporte. OnlineMeetingRecording.Read.All
callRecording
users/{userId}/onlineMeetings/getAllRecordings
Uma gravação de chamada que fica disponível em uma reunião organizada por um usuário específico.
OnlineMeetingRecording.Read.All Sem suporte. OnlineMeetingRecording.Read.All
callTranscript
communications/onlineMeetings/getAllTranscripts
Todas as transcrições em uma organização.
Sem suporte. Sem suporte. OnlineMeetingTranscript.Read.All
callTranscript
communications/onlineMeetings/{onlineMeetingId}/transcripts
Todas as transcrições de uma reunião específica.
OnlineMeetingTranscript.Read.All Sem suporte. OnlineMeetingTranscript.Read.All
callTranscript
users/{userId}/onlineMeetings/getAllTranscripts
Uma transcrição de chamada que fica disponível em uma reunião organizada por um usuário específico.
OnlineMeetingTranscript.Read.All Sem suporte. OnlineMeetingTranscript.Read.All
canal (/teams/getAllChannels – todos os canais em uma organização) Incompatível Sem suporte Channel.ReadBasic.All, ChannelSettings.Read.All
canal (/teams/{id}/channels) Channel.ReadBasic.All, ChannelSettings.Read.All Sem suporte 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
chat
/appCatalogs/teamsApps/{id}/installedToChats
Todos os chats em uma organização em que um aplicativo específico do Teams está instalado.
Sem suporte Sem suporte Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
chatMessage (/teams/{id}/channels/{id}/messages) ChannelMessage.Read.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
chatMessage
/appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
Mensagens de chat para todos os chats em uma organização em que um aplicativo específico do Teams está instalado.
Sem suporte Sem suporte Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
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
/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
Membros do chat para todos os chats em uma organização em que um aplicativo específico do Teams está instalado.
Sem suporte. Sem suporte. ChatMember.Read.WhereInstalled, ChatMember.ReadWrite.WhereInstalled, Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
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
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
virtualEventWebinar VirtualEvent.Read Sem suporte. VirtualEvent.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 dão suporte a permissões de acesso de gravação quando são necessárias apenas permissões de acesso de leitura.

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.

Você deve usar o cabeçalho de Prefer: include-unknown-enum-members solicitação para obter os seguintes valores em chatMessagemessageTypeenume evoluível: systemEventMessage para /teams/{id}/channels/{id}/messages e /chats/{id}/messages recurso.

Observação

/teams/getAllMessages, /chats/getAllMessages, /me/chats/getAllMessages, , /users/{id}/chats/getAllMessagese /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages são APIs limitadas; modelos de pagamento e requisitos de licenciamento podem ser aplicados . /teams/getAllMessages e /chats/getAllMessages dar suporte a model=A modelos de model=B pagamento, /me/chats/getAllMessages, , /users/{id}/chats/getAllMessagese /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages dar suporte apenas model=Ba . Se você não especificar um modelo de pagamento em sua consulta, o modo de avaliação padrão será usado.

Observação

Para adicionar ou alterar um modelo de pagamento para um recurso inscrito de uma notificação de alteração, você deve criar uma nova assinatura de notificação de alteração com o novo modelo de pagamento; A atualização de uma notificação de alteração existente não funciona.

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, /chats/getAllMemberse /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers são APIs limitadas; modelos de pagamento e requisitos de licenciamento podem ser aplicados . /teams/getAllMemberse /chats/getAllMembers dar suporte a model=A modelos de pagamento e .model=B /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers dá suporte apenas model=Ba . Se você não especificar um modelo de pagamento em sua consulta, o modo de avaliação padrão será usado.

Observação

Para adicionar ou alterar um modelo de pagamento para um recurso inscrito de uma notificação de alteração, você deve criar uma nova assinatura de notificação de alteração com o novo modelo de pagamento; A atualização de uma notificação de alteração existente não funciona.

team, channel e chat

assinaturas de equipe, canal e chat 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

/appCatalogs/teamsApps/{id}/installedToChats tem requisitos de licenciamento e pagamento, especificamente com suporte apenas model=B. Se nenhum modelo for especificado, o modo de avaliação será usado.

Observação

Para adicionar ou alterar um modelo de pagamento para um recurso inscrito de uma notificação de alteração, você deve criar uma nova assinatura de notificação de alteração com o novo modelo de pagamento; A atualização de uma notificação de alteração existente não funciona.

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

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 assinar instâncias drive ou driveItem que não são 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 seus equivalentes de leitura/gravação), pois elas não dão suporte à assinatura para alterar notificações 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

As assinaturas em eventos virtuais dão suporte apenas a notificações básicas e são limitadas a algumas entidades de um evento virtual. Para obter mais informações sobre os tipos de assinatura com suporte, confira 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

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

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 duplicado

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

Exemplos de recursos

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

Tipo de recurso Exemplos
Registros de chamadas communications/callRecords
callRecording communications/onlineMeetings/getAllRecordings, communications/onlineMeetings/{onlineMeetingId}/recordings, users/{userId}/onlineMeetings/getAllRecordings
callTranscript communications/onlineMeetings/getAllTranscripts, communications/onlineMeetings/{onlineMeetingId}/transcripts, users/{userId}/onlineMeetings/getAllTranscripts
Mensagem de chat chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages
Contatos me/contacts
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
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
Alerta de segurança security/alerts?$filter=status eq 'New'
todoTask /me/todo/lists/{todoTaskListId}/tasks
Usuários users

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.