Configurar notificações para alterações nos dados de recursos
As notificações de alteração permitem que os aplicativos recebam alertas quando um recurso do Microsoft Graph estiver interessado em alterações; ou seja, criado, atualizado ou excluído. O Microsoft Graph envia notificações para o ponto de extremidade do cliente especificado e o serviço cliente processa as notificações de acordo com os requisitos de negócios. Por exemplo, o serviço pode buscar mais dados, atualizar seu cache e exibições e assim por diante.
Por que receber notificações de alteração?
As notificações de alteração seguem um modelo controlado por eventos em que os clientes recebem alertas quando ocorrem alterações em vez de sondar o Microsoft Graph. Dependendo da lógica de negócios, as notificações de alteração são adequadas quando:
- Você está assinando um recurso que é alterado com frequência.
- Você precisa reagir às alterações quase em tempo real.
- Você deseja evitar sondar frequentemente o Microsoft Graph, o que pode fazer com que você atinja os limites de limitação.
Tipos de notificações de alteração
O Microsoft Graph dá suporte a três tipos de notificações de alteração:
- Notificações básicas: altere as notificações que não contêm dados de recurso que não sejam a ID do recurso alterado. Quando um aplicativo recebe uma notificação básica, o serviço pode usar a id para consultar o objeto alterado.
- Notificações avançadas: altere as notificações que incluem os dados de recurso do objeto que foi alterado. Para obter mais informações sobre notificações avançadas, confira notificações avançadas.
- Notificações do ciclo de vida: Notificações que alertam o cliente quando ele está em risco de falta de notificações de alteração devido ao ciclo de vida de sua assinatura. Para obter mais informações sobre notificações de ciclo de vida, consulte Notificações do ciclo de vida.
Recebendo notificações de alteração
O Microsoft Graph pode fornecer notificações de alteração aos clientes por meio dos canais a seguir.
- Webhooks. Para obter mais informações, confira Receber notificações de alteração por meio de webhooks.
- Hubs de Eventos do Azure. Para obter mais informações, consulte Receber notificações de alteração por meio de Hubs de Eventos do Azure.
- Grade de Eventos do Azure (versão prévia). Para obter mais informações, consulte Receber notificações de alteração por meio de Grade de Eventos do Azure.
Gerenciar assinaturas
Os clientes podem criar, renovar e excluir assinaturas. Enquanto a assinatura está ativa e quando ocorrem alterações no recurso inscrito, o Microsoft Graph envia notificações de alteração para o ponto de extremidade de notificação especificado.
Você gerencia a assinatura usando o tipo de recurso de assinatura e seus métodos relacionados. O Microsoft Graph envia notificações de alteração em uma estrutura definida no tipo de recurso changeNotificationCollection.
Recursos com suporte
Um aplicativo pode assinar alterações nos recursos do Microsoft Graph listados na tabela.
Observação
Assinaturas de recursos marcados com um asterisco (*
) só estão disponíveis no /beta
ponto de extremidade.
Recurso | Caminhos de recursos com suporte | Limitações |
---|---|---|
Impressão na nuvem printer | Alterações quando um trabalho de impressão está pronto para ser baixado (evento jobFetchable): /print/printers/{id}/jobs |
- |
Impressão na nuvem printTaskDefinition | Alterações quando há um trabalho válido na fila (evento jobStarted): /print/printtaskdefinition/{id}/tasks |
- |
driveItem no OneDrive (pessoal) | Alterações no conteúdo dentro da hierarquia de qualquer pasta: /users/{id}/drive/root |
- |
driveItem no OneDrive for Business | Alterações no conteúdo dentro da hierarquia da pasta raiz: /drives/{id}/root , /users/{id}/drive/root |
- |
group | Alterações em todos os grupos: /groups Alterações em um grupo específico: /groups/{id} Alterações nos proprietários de um grupo específico: /groups/{id}/owners Alterações nos membros de um grupo específico: /groups/{id}/members |
Cotas máximas de assinaturas: Não há suporte para Azure AD locatários B2C. NOTA: A criação e a exclusão temporária de grupos também disparam o updated changeType. |
lista em um site do SharePoint | Alterações no conteúdo na lista: /sites/{site-id}/lists/{list-id} |
- |
Grupo Microsoft 365 conversação | Alterações nas conversas de um grupo: groups/{id}/conversations |
- |
Mensagem do Outlook | Alterações em todas as mensagens na caixa de correio de um usuário: /users/{id}/messages , /me/messages Alterações nas mensagens na caixa de entrada de um usuário: /users/{id}/mailFolders('inbox')/messages , /me/mailFolders('inbox')/messages |
Um máximo de 1.000 assinaturas ativas por caixa de correio para todos os aplicativos é permitido. |
Evento do Outlook | Alterações em todos os eventos na caixa de correio de um usuário: /users/{id}/events , /me/events |
Um máximo de 1.000 assinaturas ativas por caixa de correio para todos os aplicativos é permitido. |
Contato pessoal do Outlook | Alterações em todos os contatos pessoais na caixa de correio de um usuário: /users/{id}/contacts , /me/contacts |
Um máximo de 1.000 assinaturas ativas por caixa de correio para todos os aplicativos é permitido. |
Alerta de segurança | Alterações em um alerta específico: /security/alerts/{id} Alterações em alertas filtrados: /security/alerts/?$filter={parameters} |
Para obter mais informações, consulte API de Segurança alertas. |
Teams callRecord | Mudanças para todos os registros de chamadas: /communications/callRecords |
Cotas máximas de assinaturas: NOTA: A criação de registros de chamada também dispara o updated changeType. |
Chamada do TeamsRecording | Todas as gravações em uma organização: communications/onlineMeetings/getAllRecordings Todas as gravações para uma reunião específica: communications/onlineMeetings/{onlineMeetingId}/recordings Uma gravação de chamada que fica disponível em uma reunião organizada por um usuário específico: users/{id}/onlineMeetings/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: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings * |
Cotas máximas de assinaturas: |
Teams callTranscript | Todas as transcrições em uma organização: communications/onlineMeetings/getAllTranscripts Todas as transcrições de uma reunião específica: communications/onlineMeetings/{onlineMeetingId}/transcripts Uma transcrição de chamada que fica disponível em uma reunião organizada por um usuário específico: users/{id}/onlineMeetings/getAllTranscripts Uma transcrição de chamada que se torna disponível em uma reunião em que um determinado aplicativo do Teams está instalado: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts * |
Cotas máximas de assinaturas: |
Chat do Teams | Alterações em qualquer chat no locatário: /chats Alterações em um chat específico: /chats/{id} Alterações em todos os chats em uma organização em que um aplicativo específico do Teams está instalado: /appCatalogs/teamsApps/{id}/installedToChats |
Cotas máximas de assinaturas: |
Teams chatMessage | Alterações nas mensagens de chat em todos os canais em todas as equipes: /teams/getAllMessages Alterações nas mensagens de chat em um canal específico: /teams/{id}/channels/{id}/messages Alterações nas mensagens de chat em todos os chats: /chats/getAllMessages Alterações nas mensagens de chat em um chat específico: /chats/{id}/messages Alterações nas mensagens de chat em todos os chats que um determinado usuário faz parte: /users/{id}/chats/getAllMessages Alterações nas mensagens de chat para todos os chats em uma organização em que um aplicativo específico do Teams está instalado: /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages |
Cotas máximas de assinaturas: |
Canal do Teams | Alterações nos canais em todas as equipes: /teams/getAllChannels Alterações no canal em uma equipe específica: /teams/{id}/channels |
Cotas máximas de assinaturas: |
conversationMember do Teams | Alterações na associação em uma equipe específica: /teams/{id}/members Alterações na associação em todos os canais em uma equipe específica: teams/{id}/channels/getAllMembers Alterações na associação em um chat específico: /chats/{id}/members Alterações na associação para todos os chats em uma organização em que um aplicativo específico do Teams está instalado: /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers Alterações na associação em todos os chats: /chats/getAllMembers |
Cotas máximas de assinaturas: |
Equipes onlineMeeting* | Alterações em uma reunião online: /communications/onlineMeetings/?$filter=JoinWebUrl eq {joinWebUrl} |
|
Teams presença | Alterações na presença de um único usuário: /communications/presences/{id} Alterações em várias presenças de usuário: /communications/presences?$filter=id in ({id},{id}...) |
|
Equipe do Teams | Alterações em qualquer equipe no locatário: /teams Alterações em uma equipe específica: /teams/{id} |
Cotas máximas de assinaturas: |
todoTask | Alterações em todas as tarefas em uma lista de tarefas específica: /me/todo/lists/{todoTaskListId}/tasks |
- |
user | Alterações em todos os usuários: /users Alterações em um usuário específico: /users/{id} |
Cotas máximas de assinaturas: Não há suporte para contas pessoais da Microsoft como outlook.com. Não há suporte para Azure AD locatários B2C. NOTA: A criação e a exclusão temporária dos usuários também disparam o updated changeType. |
Observação
Muitos recursos têm limites ou cotas sobre quantas assinaturas podem ser feitas em relação a esse recurso. Ao exceder esse limite, as tentativas de criar uma assinatura resultarão em uma 403 Forbidden
resposta de erro. A propriedade da mensagem da resposta de erro explicará o limite que foi excedido.
Alguns desses recursos dão suporte a notificações avançadas (notificações com dados de recursos). Para obter mais informações sobre recursos que dão suporte a notificações avançadas, consulte Configurar notificações de alteração que incluem dados de recurso.
Tempo de vida da assinatura
As assinaturas têm tempo de vida limitado. Os aplicativos precisam renovar suas assinaturas antes do tempo de validade; Caso contrário, eles precisam criar uma nova assinatura. Os aplicativos também podem cancelar a assinatura a qualquer momento para deixarem de receber notificações de alteração.
A tabela a seguir mostra os tempos máximos de expiração para assinaturas por recurso no Microsoft Graph.
Resource | Tempo de expiração máximo |
---|---|
Alerta de segurança | 43.200 minutos (menos de 30 dias) |
Teams callRecord | 4.230 minutos (menos de 3 dias) |
Chamada do TeamsRecording | 4.320 minutos (3 dias) |
Teams callTranscript | 4.320 minutos (3 dias) |
Canal do Teams | 4.320 minutos (3 dias) |
Chat do Teams | 4.320 minutos (3 dias) |
Teams chatMessage | 4.320 minutos (3 dias) |
conversationMember do Teams | 4.320 minutos (3 dias) |
onlineMeeting do Teams | 4.320 minutos (3 dias) |
Equipe do Teams | 4.320 minutos (3 dias) |
Conversa em grupo | 4.230 minutos (menos de 3 dias) |
OneDrive driveItem | 42.300 minutos (menos de 30 dias) |
Lista do Microsoft Office SharePoint Online | 42.300 minutos (menos de 30 dias) |
Outlook mensagem, evento, contato | 4.230 minutos (menos de 3 dias) |
usuário, grupo, outros recursos de diretório | 41.760 minutos (menos de 29 dias) |
onlineMeeting | 4.230 minutos (menos de 3 dias) |
presence | 60 minutos (1 hora) |
Imprimir printer | 4.230 minutos (menos de 3 dias) |
Imprimir printTaskDefinition | 4.230 minutos (menos de 3 dias) |
todoTask | 4.230 minutos (menos de 3 dias) Os webhooks para esse recurso só estão disponíveis no ponto de extremidade global e não nas nuvens nacionais. |
baseTask (preterido) | 4.230 minutos (menos de 3 dias) |
Observação:Os aplicativos existentes e os novos aplicativos não devem ultrapassar o valor suportado. No futuro, as solicitações para criar ou renovar uma assinatura além do valor máximo falharão.
Latência
A tabela a seguir lista a latência esperada entre um evento acontecendo no serviço e a entrega da notificação de alteração.
Recurso | Latência média | Latência máxima |
---|---|---|
alerta1 | Menos de 3 minutos | 5 minutos |
calendar | Menos de 1 minuto | Três minutos |
callRecord | Menos de 15 minutos | 60 minutos |
callRecording | Menos de 10 segundos | 60 minutos |
callTranscript | Menos de 10 segundos | 60 minutos |
canal | Menos de 10 segundos | 60 minutos |
chat | Menos de 10 segundos | 60 minutos |
chatMessage | Menos de 10 segundos | 1 minuto |
contato | Menos de 1 minuto | Três minutos |
conversa | Desconhecido | Desconhecido |
conversationMember | Menos de 10 segundos | 60 minutos |
driveItem | Menos de 1 minuto | 5 minutos |
evento | Desconhecido | Desconhecido |
grupo | Desconhecido | Desconhecido |
lista | Menos de 1 minuto | 5 minutos |
mensagem | Menos de 1 minuto | Três minutos |
onlineMeeting | Menos de 10 segundos | 1 minuto |
presence | Menos de 10 segundos | 1 minuto |
impressora | Menos de 1 minuto | 5 minutos |
printTaskDefinition | Menos de 1 minuto | 5 minutos |
equipe | Menos de 10 segundos | 60 minutos |
todoTask | Menos de 2 minutos | 15 minutos |
usuário | Menos de 2 minutos | 15 minutos |
1 A latência fornecida para o recurso de alerta só é aplicável após a criação do alerta. Ele não inclui o tempo necessário para uma regra criar um alerta a partir dos dados.
Exemplos de código
Os exemplos de código a seguir estão disponíveis no GitHub.
- Módulo de Treinamento do Microsoft Graph - Usar notificações de alteração e controlar alterações com o Microsoft Graph
- Exemplo de webhooks do Microsoft Graph para Node.js
- Exemplo de Webhooks do Microsoft Graph para o ASP.NET Core
- Exemplo de Webhooks do Microsoft Graph para Java Spring
Conteúdo relacionado
Comentários
https://aka.ms/ContentUserFeedback.
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, consulteEnviar e exibir comentários de