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 Versão.
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
A criação de uma assinatura requer permissão de leitura para o recurso. Por exemplo, para obter 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.
Observação
- 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.
- Alguns recursos dão suporte a notificações de alteração em vários cenários, cada um deles pode exigir permissões diferentes. Nesses casos, use o caminho do recurso para diferenciar os cenários.
| Recurso com suporte | Delegada (conta corporativa ou de estudante) | Delegada (conta pessoal da Microsoft) | Aplicativo |
|---|---|---|---|
| callRecord | Sem suporte. | Sem suporte. | CallRecords.Read.All |
callRecording communications/onlineMeetings/getAllRecordings Qualquer gravação fica disponível no locatário. |
Sem suporte. | Sem suporte. | OnlineMeetingRecording.Read.All |
callRecording communications/onlineMeetings/{onlineMeetingId}/recordings Qualquer gravação fica disponível 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 |
callRecording appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings Uma gravação de chamada que se torna disponível em uma reunião em que um aplicativo específico do Teams está instalado. |
Sem suporte. | Sem suporte. | OnlineMeetingRecording.Read.All, OnlineMeetingRecording.Read.Chat |
callTranscript communications/onlineMeetings/getAllTranscripts Qualquer transcrição fica disponível no locatário. |
Sem suporte. | Sem suporte. | OnlineMeetingTranscript.Read.All |
callTranscript communications/onlineMeetings/{onlineMeetingId}/transcripts Qualquer transcrição fica disponível para 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 |
callTranscript appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts Uma transcrição de chamada que fica disponível em uma reunião em que um aplicativo específico do Teams está instalado. |
Sem suporte. | Sem suporte. | OnlineMeetingTranscript.Read.All, OnlineMeetingTranscript.Read.Chat |
canal /teams/getAllChannels Todos os canais em uma organização. |
Sem suporte. | Sem suporte. | Channel.ReadBasic.All, ChannelSettings.Read.All |
canal /teams/{id}/channels Todos os canais em uma equipe específica em uma organização. |
Channel.ReadBasic.All, ChannelSettings.Read.All | Sem suporte. | Channel.ReadBasic.All, ChannelSettings.Read.All |
chat /chats Todos os chats em uma organização. |
Sem suporte. | Sem suporte. | Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
chat /chats/{id} Um chat específico. |
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 Todas as mensagens e respostas em um canal específico. |
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 Todas as mensagens em um chat. |
Chat.Read, Chat.ReadWrite | Sem suporte. | Chat.Read.All |
chatMessage /chats/getAllMessages Todas as mensagens de chat em uma organização. |
Sem suporte. | Sem suporte. | Chat.Read.All |
chatMessage /users/{id}/chats/getAllMessages Mensagens de chat para todos os chats dos quais um determinado usuário 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 Membros de todos os chats em uma organização. |
Sem suporte. | Sem suporte. | ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
conversationMember /chats/{id}/members Membros de um chat específico. |
ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite | Sem suporte. | 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/getAllMembers Membros em todas as equipes de uma organização. |
Sem suporte. | Sem suporte. | TeamMember.Read.All, TeamMember.ReadWrite.All |
conversationMember /teams/{id}/members Membros em uma equipe específica. |
TeamMember.Read.All | Sem suporte. | TeamMember.Read.All |
conversationMember /teams/{id}/channels/getAllMembers Membros em todos os canais privados de uma equipe específica. |
Sem suporte. | Sem suporte. | ChannelMember.Read.All |
conversationMember /teams/getAllChannels/getAllMembers |
Sem suporte. | Sem suporte. | 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 |
| onlineMeeting | Sem suporte. | Sem suporte. | OnlineMeetings.Read.All, OnlineMeetings.ReadWrite.All |
| presence | Presence.Read.All | Sem suporte. | Sem suporte. |
| impressora | 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 |
team /teams Todas as equipes em uma organização. |
Sem suporte. | Sem suporte. | Team.ReadBasic.All, TeamSettings.Read.All |
team /teams/{id} Uma equipe específica. |
Team.ReadBasic.All, TeamSettings.Read.All | Sem suporte. | Team.ReadBasic.All, TeamSettings.Read.All |
| todoTask | Tasks.ReadWrite | Tasks.ReadWrite | Sem suporte. |
| user | User.Read.All | User.Read.All | User.Read.All |
| virtualEventWebinar | VirtualEvent.Read | Sem suporte. | VirtualEvent.Read.All |
| baseTask (preterido) | Tasks.ReadWrite | Tasks.ReadWrite | Sem suporte. |
Observação
As seguintes permissões usam o consentimento específico do recurso:
- OnlineMeetingRecording.Read.Chat
- OnlineMeetingTranscript.Read.Chat
- ChatSettings.Read.Chat
- ChatSettings.ReadWrite.Chat
- Chat.Manage.Chat
- ChannelMessage.Read.Group
- ChatMember.Read.Chat
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
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 for Business, você pode assinar somente a pasta raiz. As notificações de alteração são enviadas para as alterações solicitadas na pasta subscrita 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. Esse cabeçalho se aplica ao SharePoint e OneDrive for Business, mas não às contas do OneDrive de consumidor.
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 deve 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 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.
onlineMeetings, presença
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 recurso. Para obter detalhes sobre assinaturas de reunião online, confira Obter notificações de alteração para reuniões online.
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 for bem-sucedido, esse método retornará um 201 Created código 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 o novo email recebido 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"
}
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
A seguir estão valores válidos para a propriedade do recurso.
| Tipo de recurso | Exemplos |
|---|---|
| callRecord | communications/callRecords |
| callRecording | communications/onlineMeetings/getAllRecordings, communications/onlineMeetings/{onlineMeetingId}/recordings, users/{userId}/onlineMeetings/getAllRecordings, appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings |
| callTranscript | communications/onlineMeetings/getAllTranscripts, communications/onlineMeetings/{onlineMeetingId}/transcripts, users/{userId}/onlineMeetings/getAllTranscripts, appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts |
| canal | /teams/getAllChannels, /teams/{id}/channels |
| chat | /chats, /chats/{id} |
| chatMessage | chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages |
| contato | me/contacts |
| conversationMember | /chats/{id}/members, /chats/getAllMembers, /teams/{id}/members, /teams/getAllMembers, /teams/{id}/channels/getAllMembers |
| driveItem | me/drive/root |
| event | me/events |
| group | groups |
| conversa em grupo | groups('{id}')/conversations |
| list | sites/{site-id}/lists/{list-id} |
| message | me/mailfolders('inbox')/messages, me/messages |
| onlineMeeting | /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 |
| equipe | /teams, /teams/{id} |
| user | users |
| todoTask | /me/todo/lists/{todoTaskListId}/tasks |
| alerta de segurança | security/alerts?$filter=status eq 'NewAlert' |
| baseTask (preterido) | /me/tasks/lists/{Id}/tasks |
Observação
Qualquer caminho com me o qual começar também pode ser usado em users/{id} vez de me direcionar um usuário específico em vez do 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.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de