Configurar notificações para alterações nos dados de recursos
As notificações de alteração permitem que as aplicações recebam alertas quando um recurso do Microsoft Graph está interessado em alterações; ou seja, criado, atualizado ou eliminado. O Microsoft Graph envia notificações para o ponto final de cliente especificado e o serviço de cliente processa as notificações de acordo com os requisitos comerciais. Por exemplo, o serviço pode obter mais dados, atualizar a respetiva cache e vistas, etc.
Porquê receber notificações de alteração?
As notificações de alteração seguem um modelo orientado para eventos em que os clientes recebem alertas quando ocorrem alterações em vez de consultarem o Microsoft Graph. Consoante a lógica de negócio, as notificações de alteração são adequadas quando:
- Está a subscrever um recurso que muda frequentemente.
- Tem de reagir às alterações quase em tempo real.
- Quer evitar consultar frequentemente o Microsoft Graph, o que pode fazer com que atinja os limites de limitação.
A imagem seguinte mostra como as notificações de alteração funcionam e se comparam com o controlo de alterações.
O vídeo seguinte fornece uma descrição geral das notificações de alteração no Microsoft Graph.
Tipos de notificações de alteração
O Microsoft Graph suporta três tipos de notificações de alteração:
- Notificações básicas: altere as notificações que não contêm dados de recursos que não o ID do recurso que foi alterado. Quando uma aplicação recebe uma notificação básica, o serviço pode utilizar o ID para consultar o objeto alterado.
- Notificações avançadas: altere as notificações que incluem os dados de recursos do objeto que foi alterado. Para obter mais informações sobre notificações avançadas, veja Notificações avançadas.
- Notificações de ciclo de vida: notificações que alertam o cliente quando estão em risco de falta de notificações de alteração devido ao ciclo de vida da subscrição. Para obter mais informações sobre as notificações de ciclo de vida, veja Notificações de ciclo de vida.
Receber notificações de alteração
O Microsoft Graph pode entregar notificações de alteração aos clientes através dos seguintes canais.
- Webhooks. Para obter mais informações, veja Receber notificações de alteração através de webhooks.
- Hubs de Eventos do Azure. Para obter mais informações, veja Receber notificações de alteração através de Hubs de Eventos do Azure.
- Grade de Eventos do Azure (pré-visualização). Para obter mais informações, veja Receber notificações de alteração através de Grade de Eventos do Azure.
Gerenciar assinaturas
Os clientes podem criar, renovar e excluir assinaturas. Enquanto a subscrição está ativa e quando ocorrem alterações no recurso subscrito, o Microsoft Graph envia notificações de alteração para o ponto final de notificação especificado.
Pode gerir a subscrição com o tipo de recurso de subscrição e os respetivos métodos relacionados. O Microsoft Graph envia notificações de alteração numa estrutura definida no tipo de recurso changeNotificationCollection.
Recursos com suporte
Uma aplicação pode subscrever alterações nos recursos do Microsoft Graph listados na tabela.
Observação
As subscrições de recursos marcados com um asterisco (*) só estão disponíveis no /beta ponto final.
| Recurso | Caminhos de recursos suportados | Limitações |
|---|---|---|
| Impressão na nuvem printer | Alterações quando uma tarefa de impressão está pronta para ser transferida (jobFetchable event): /print/printers/{id}/jobs |
- |
| Impressão na nuvem printTaskDefinition | Alterações quando existe uma tarefa válida na fila (evento jobStarted): /print/printtaskdefinition/{id}/tasks |
- |
| driveItem no OneDrive (pessoal) | Alterações ao conteúdo na hierarquia de qualquer pasta: /users/{id}/drive/root |
- |
| driveItem no OneDrive para trabalho ou escola | Alterações ao conteúdo na hierarquia da pasta raiz: /drives/{id}/root , /users/{id}/drive/root |
- |
| group | Alterações a todos os grupos: /groups Alterações a um grupo específico: /groups/{id} Alterações aos proprietários de um grupo específico: /groups/{id}/owners Alterações aos membros de um grupo específico: /groups/{id}/members |
Cotas máximas de assinaturas: Não suportado para inquilinos Azure AD B2C. NOTA: A criação e eliminação recuperável de grupos também acionam o updatedchangeType. |
| lista em um site do SharePoint | Alterações ao conteúdo na lista: /sites/{site-id}/lists/{list-id} |
- |
| Grupo Microsoft 365 conversação | Alterações às conversações de um grupo: groups/{id}/conversations |
- |
| Mensagem do Outlook | Alterações a todas as mensagens na caixa de correio de um utilizador: /users/{id}/messages , /me/messages Alterações às mensagens na Caixa de Entrada de um utilizador: /users/{id}/mailFolders('inbox')/messages , /me/mailFolders('inbox')/messages |
É permitido um máximo de 1000 subscrições ativas por caixa de correio para todas as aplicações. |
| Evento do Outlook | Alterações a todos os eventos na caixa de correio de um utilizador: /users/{id}/events , /me/events |
É permitido um máximo de 1000 subscrições ativas por caixa de correio para todas as aplicações. |
| Contato pessoal do Outlook | Alterações a todos os contactos pessoais na caixa de correio de um utilizador: /users/{id}/contacts , /me/contacts |
É permitido um máximo de 1000 subscrições ativas por caixa de correio para todas as aplicações. |
| Alerta de segurança | Alterações a um alerta específico: /security/alerts/{id} Alterações aos alertas filtrados: /security/alerts/?$filter={parameters} |
Para obter mais informações, veja API de Segurança alertas. |
| Aprovações do Teams | Alterações a todas as aprovações num inquilino: /solutions/approval/approvalItems |
Cotas máximas de assinaturas: |
| Teams callRecord | Mudanças para todos os registros de chamadas: /communications/callRecords Alterações aos registos de chamada filtrados: /communications/callRecords?$filter={parameters} |
Para obter mais informações, veja Alterar notificações de Registos de Chamadas. Cotas máximas de assinaturas: NOTA: A criação de registos de chamadas também aciona o updatedchangeType. |
| Chamada do TeamsRegisto | Todas as gravações numa 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 numa reunião organizada por um utilizador específico: users/{id}/onlineMeetings/getAllRecordings Uma gravação de chamada que fica disponível numa reunião onde está instalada uma determinada aplicação do Teams: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings * |
Cotas máximas de assinaturas: |
| Chamada do TeamsTranscript | Todas as transcrições numa 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 numa reunião organizada por um utilizador específico: users/{id}/onlineMeetings/getAllTranscripts Uma transcrição de chamadas que fica disponível numa reunião onde está instalada uma determinada aplicação do Teams: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts * |
Cotas máximas de assinaturas: |
| Chat do Teams | Alterações a qualquer conversa no inquilino: /chats Alterações a um chat específico: /chats/{id} Alterações a um chat específico com o parâmetro de consulta notifyOnUserSpecificProperties : /chats/{id}?notifyOnUserSpecificProperties={Boolean} Alterações a todas as conversas numa organização onde está instalada uma determinada aplicação do Teams: /appCatalogs/teamsApps/{id}/installedToChats Alterações a todas as conversas das quais um determinado utilizador faz parte: /users/{id}/chats Alterações a todas as conversas de que um determinado utilizador faz parte com o parâmetro de consulta notifyOnUserSpecificProperties : /users/{id}/chats?notifyOnUserSpecificProperties={Boolean} |
Cotas máximas de assinaturas: |
| Teams chatMessage | Alterações às mensagens de chat em todos os canais em todas as equipas: /teams/getAllMessages Alterações às mensagens de chat num canal específico: /teams/{id}/channels/{id}/messages Alterações às mensagens de chat em todas as conversas: /chats/getAllMessages Alterações às mensagens de chat num chat específico: /chats/{id}/messages As alterações às mensagens de chat em todas as conversas dos utilizadores específicos fazem parte: /users/{id}/chats/getAllMessages Alterações às mensagens de chat de todas as conversas numa organização onde está instalada uma determinada aplicação do Teams: /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages |
Cotas máximas de assinaturas: |
| Canal do Teams | Alterações aos canais em todas as equipas: /teams/getAllChannels Alterações ao canal numa equipa específica: /teams/{id}/channels |
Cotas máximas de assinaturas: |
| conversationMember do Teams | Alterações à associação numa equipa específica: /teams/{id}/members Alterações à associação em todos os canais numa equipa específica: teams/{id}/channels/getAllMembers Alterações à associação num chat específico: /chats/{id}/members Alterações à associação a todas as conversas numa organização onde está instalada uma determinada aplicação do Teams: /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers Alterações à associação em todas as conversas: /chats/getAllMembers |
Cotas máximas de assinaturas: |
| Teams onlineMeeting* | Alterações a uma reunião online: /communications/onlineMeetings(joinWebUrl='{encodedJoinWebUrl}')/meetingCallEvents |
Não suporta a utilização $select para devolver apenas as propriedades selecionadas. A notificação avançada consiste em todas as propriedades da instância alterada. Uma subscrição permitida por aplicação por reunião online. Para obter mais informações, consulte Obter notificações de alteração para atualizações de eventos de chamada de reunião do Microsoft Teams. |
| Teams presença | Alterações à presença de um único utilizador: /communications/presences/{id} Alterações à presença de vários utilizadores: /communications/presences?$filter=id in ({id},{id}...) |
A subscrição para a presença de vários utilizadores está limitada a 650 utilizadores distintos. Não suporta a utilização $select para devolver apenas as propriedades selecionadas. A notificação avançada consiste em todas as propriedades da instância alterada. Uma subscrição permitida por aplicação por utilizador delegado. Para obter mais informações, consulte Obter notificações de alteração para atualizações de presença no Microsoft Teams. |
| Equipe do Teams | Alterações a qualquer equipa no inquilino: /teams Alterações a uma equipa específica: /teams/{id} |
Cotas máximas de assinaturas: |
| Oferta de Turnos do TeamsShiftRequest | Alterações a qualquer pedido de turno de oferta numa equipa: /teams/{id}/schedule/offerShiftRequests |
Cotas máximas de assinaturas: |
| Turnos do Teams openShiftChangeRequest | Alterações a qualquer pedido de turno aberto numa equipa: /teams/{id}/schedule/openShiftChangeRequests |
Cotas máximas de assinaturas: |
| Turnos do Teams | Alterações a qualquer mudança numa equipa: /teams/{id}/schedule/shifts |
Cotas máximas de assinaturas: |
| Teams Shifts swapShiftsChangeRequest | Alterações a qualquer pedido de turno de troca numa equipa: /teams/{id}/schedule/swapShiftsChangeRequests |
Cotas máximas de assinaturas: |
| Teams Shifts timeOffRequest | Alterações a qualquer pedido de folga numa equipa: /teams/{id}/schedule/timeOffRequests |
Cotas máximas de assinaturas: |
| todoTask | Alterações a todas as tarefas numa lista de tarefas específica: /me/todo/lists/{todoTaskListId}/tasks |
- |
| user | Alterações a todos os utilizadores: /users Alterações a um utilizador específico: /users/{id} |
Cotas máximas de assinaturas: Não é suportado para contas Microsoft pessoais, como outlook.com. Não suportado para inquilinos Azure AD B2C. NOTA: A criação e eliminação recuperável de utilizadores também acionam o updatedchangeType. |
Observação
Muitos recursos têm limites ou quotas sobre quantas subscrições podem ser feitas relativamente a esse recurso. Ao exceder esse limite, as tentativas de criar uma subscrição resultarão numa 403 Forbidden resposta de erro. A propriedade da mensagem da resposta do erro explicará o limite que foi excedido.
Alguns destes recursos suportam notificações avançadas (notificações com dados de recursos). Para obter mais informações sobre os recursos que suportam notificações avançadas, veja Configurar notificações de alteração que incluem dados de recursos.
Tempo de vida da assinatura
As assinaturas têm tempo de vida limitado. As aplicações têm de renovar as subscrições antes da expiração; Caso contrário, têm de criar uma nova subscrição. Os aplicativos também podem cancelar a assinatura a qualquer momento para deixarem de receber notificações de alteração.
A tabela seguinte mostra os tempos máximos de expiração das subscrições por recurso no Microsoft Graph.
| Resource | Tempo de expiração máximo |
|---|---|
| Alerta de segurança | 43 200 minutos (menos de 30 dias) |
| Aprovações do Teams | 43 200 minutos (menos de 30 dias) |
| Teams callRecord | 4.230 minutos (menos de três dias) |
| Chamada do TeamsRegisto | 4.320 minutos (três dias) |
| Chamada do TeamsTranscript | 4.320 minutos (três dias) |
| Canal do Teams | 4.320 minutos (três dias) |
| Chat do Teams | 4.320 minutos (três dias) |
| Teams chatMessage | 4.320 minutos (três dias) |
| conversationMember do Teams | 4.320 minutos (três dias) |
| onlineMeeting do Teams | 4.320 minutos (três dias) |
| Equipe do Teams | 4.320 minutos (três dias) |
| Teams teamsAppInstallation | 4.320 minutos (3 dias) |
| Oferta de Turnos do TeamsShiftRequest | 360 minutos (6 horas) |
| Turnos do Teams openShiftChangeRequest | 360 minutos (6 horas) |
| Turnos do Teams | 360 minutos (6 horas) |
| Teams Shifts swapShiftsChangeRequest | 360 minutos (6 horas) |
| Teams Shifts timeOffRequest | 360 minutos (6 horas) |
| Conversa em grupo | 4.230 minutos (menos de três 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 | 10 080 minutos (menos de sete dias) |
| usuário, grupo, outros recursos de diretório | 41.760 minutos (menos de 29 dias) |
| onlineMeeting | 4.230 minutos (menos de três dias) |
| presence | 60 minutos (1 hora) |
| Imprimir printer | 4.230 minutos (menos de três dias) |
| Imprimir printTaskDefinition | 4.230 minutos (menos de três dias) |
| todoTask | 4.230 minutos (menos de três dias) Os webhooks para este recurso só estão disponíveis no ponto final global e não nas clouds nacionais. |
| baseTask (preterido) | 4.230 minutos (menos de três 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 |
| aprovações | Menos de 10 segundos | 40 segundos |
| 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 |
| offerShiftRequest | Menos de 1 minuto | 60 minutos |
| onlineMeeting | Menos de 10 segundos | 1 minuto |
| openShiftChangeRequest | Menos de 1 minuto | 60 minutos |
| presence | Menos de 10 segundos | 1 minuto |
| impressora | Menos de 1 minuto | 5 minutos |
| printTaskDefinition | Menos de 1 minuto | 5 minutos |
| shift | Menos de 1 minuto | 60 minutos |
| swapShiftsChangeRequest | Menos de 1 minuto | 60 minutos |
| equipe | Menos de 10 segundos | 60 minutos |
| teamsAppInstallation | Menos de 10 segundos | 60 minutos |
| timeOffRequest | Menos de 1 minuto | 60 minutos |
| todoTask | Menos de 2 minutos | 15 minutos |
| usuário | Desconhecido | Desconhecido |
1 A latência fornecida para o recurso de alerta só é aplicável após a criação do alerta. Não inclui o tempo que uma regra demora a 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