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 no qual eles estão interessados muda; isto é, criados, atualizados ou excluídos. O Microsoft Graph envia notificações para o ponto de extremidade do cliente especificado, e o serviço do cliente processa as notificações de acordo com os requisitos comerciais. Por exemplo, o serviço pode buscar mais dados, atualizar seu cache e exibições e assim por diante.

Importante

Não há suporte para o recurso de notificações de alteração na ID externa do Microsoft Entra em locatários externos e locatários do Azure AD B2C.

Por que receber notificações de alteração?

As notificações de alteração seguem um modelo orientado a eventos em que os clientes recebem alertas quando ocorrem alterações, em vez de pesquisarem 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 muda com frequência.
  • Você precisa reagir às alterações quase em tempo real.
  • Você deve evitar pesquisar com frequência o Microsoft Graph, o que pode fazer com que você atinja os limites de limitação.

A imagem a seguir mostra como as notificações de alteração funcionam e se compara com o controle de alterações.

Ilustração de notificações de alteração e serviços de consulta delta

O vídeo a seguir fornece uma visão geral das notificações de alteração no Microsoft Graph.

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: Notificações de alteração que não contêm dados de recursos diferentes da ID do recurso que foi 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: notificações de alteração que incluem os dados de recurso do objeto que foi alterado. Para obter mais informações sobre notificações avançadas, consulte Notificações avançadas.
  • Notificações de ciclo de vida: notificações que alertam o cliente quando ele corre o risco de perder 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 de ciclo de vida.

Recebendo notificações de alteração

O Microsoft Graph pode fornecer notificações de alteração aos clientes por meio dos seguintes canais.

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 as alterações nos recursos do Microsoft Graph listados na tabela. As assinaturas de recursos marcados com um asterisco (*) só estão disponíveis no /beta ponto de extremidade.

Observação

Para recursos do Microsoft Teams, o limite por organização de 10.000 assinaturas no total é compartilhado cumulativamente entre todas as assinaturas de notificação de alteração do Teams no locatário. Inclui assinaturas criadas para diferentes recursos do Teams, como chats, mensagens de chat, transcrições de chamadas, gravações de chamadas, canais, equipes e membros da conversa, que contam para a mesma cota organizacional. Quando o número combinado de assinaturas ativas do Teams atinge esse limite, qualquer solicitação adicional de criação de assinatura para um recurso do Teams falha com um 403 Forbidden erro.

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 Alterado quando há um trabalho válido na fila (evento jobStarted): /print/printtaskdefinition/{id}/tasks -
Copilot aiInsights Insights de IA do Copilot de reuniões das quais um determinado usuário faz parte: /copilot/users/{userId}/onlineMeetings/getAllAiInsights

Insights de IA do Copilot para uma reunião específica: /copilot/users/{userId}/onlineMeetings/{onlineMeetingId}/aiInsights		 Cotas máximas de assinatura para insights de IA em todas as reuniões de um usuário:
  • Por aplicativo e combinação de usuário: 1
  • Por usuário (delegado): 10
  • Por organização: total de 10.000 assinaturas.


Cotas máximas de assinatura para insights de IA de uma reunião específica:
  • Por aplicativo e combinação de usuário + reunião: 1
  • Combinação por usuário e reunião (delegada): 1
  • Por organização: 10.000 assinaturas no total (compartilhadas)
Copilot aiInteraction Interações de IA do Copilot das quais um determinado usuário faz parte: copilot/users/{userId}/interactionHistory/getAllEnterpriseInteractions

Interações de IA do Copilot em uma organização: copilot/interactionHistory/getAllEnterpriseInteractions		 Cotas máximas de assinaturas:
  • Combinação por aplicativo e locatário (para assinaturas que acompanham interações de IA em um locatário): 1
  • Combinação por aplicativo e usuário (para assinaturas que acompanham as interações de IA das quais um determinado usuário faz parte): 1
  • Por usuário (para assinaturas que acompanham interações de IA das quais um determinado usuário faz parte): 10 assinaturas.
  • Por organização: total de 10.000 assinaturas.
driveItem no OneDrive (pessoal) Alterações no conteúdo dentro da hierarquia de qualquer pasta: /users/{id}/drive/root -
driveItem no OneDrive corporativo ou de estudante 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:
  • Por aplicativo (para todos os locatários combinados): 50.000 assinaturas no total.
  • Por locatário (para todos os aplicativos combinados): 1.000 assinaturas no total em todos os aplicativos.
  • Combinação por aplicativo e locatário: total de 100 assinaturas.


Não há suporte para locatários do Azure AD B2C.

OBSERVAÇÃO: A criação e a exclusão reversível de grupos também acionam o updatedchangeType.
Alerta de Monitoramento de Integridade do Microsoft Entra Alterações em todos os alertas de monitoramento de integridade: /reports/healthmonitoring/alerts

Alterações em um tipo específico de alerta: /reports/healthmonitoring/alert com a notificationQueryOptions propriedade no conteúdo da solicitação definida como $filter=alertType eq '{alertType}'		 -
lista em um site do SharePoint Alterações no conteúdo dentro da 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		 É permitido um máximo de 1.000 assinaturas ativas por caixa de correio para todos os aplicativos.
Evento do Outlook Alterações em todos os eventos na caixa de correio de um usuário: /users/{id}/events , /me/events É permitido um máximo de 1.000 assinaturas ativas por caixa de correio para todos os aplicativos.
Contato pessoal do Outlook Alterações em todos os contatos pessoais na caixa de correio de um usuário: /users/{id}/contacts , /me/contacts É permitido um máximo de 1.000 assinaturas ativas por caixa de correio para todos os aplicativos.
Alerta de segurança Alterações em um alerta específico: /security/alerts/{id}

Alterações nos alertas filtrados: /security/alerts/?$filter={parameters}		 Para obter mais informações, consulte Alertas da API de Segurança.
Aprovações de equipes Alterações em todas as aprovações em um locatário: /solutions/approval/approvalItems Cotas máximas de assinaturas:
  • Por locatário (para todos os aplicativos combinados): 1000 total de assinaturas em todos os aplicativos
  • Combinação por aplicativo e locatário: 1 assinatura.
Teams callRecord Mudanças para todos os registros de chamadas: /communications/callRecords

Alterações nos registros de chamadas filtrados: /communications/callRecords?$filter={parameters}		 Para obter mais informações, consulte Alterar notificações para Registros de Chamada.

Cotas máximas de assinaturas:
  • Por organização: total de 100 assinaturas.


OBSERVAÇÃO: A criação de registros de chamada também dispara o updatedchangeType.
CallRecording do Teams Todas as gravações em uma organização: communications/onlineMeetings/getAllRecordings

Todas as gravações de uma reunião específica: communications/onlineMeetings/{onlineMeetingId}/recordings

Uma gravação de chamada que se torna 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 determinado aplicativo do Teams está instalado: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings *		 Cotas máximas de assinaturas:
  • Combinação por aplicativo e reunião online: 1
  • Por aplicativo e combinação de usuário: 1
  • Por usuário (para gravações de acompanhamento de assinaturas em todas as reuniões online organizadas pelo usuário): 10 assinaturas.
  • Por organização: total de 10.000 assinaturas.
Transcrição de chamada do Teams 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 fica 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:
  • Combinação por aplicativo e reunião online: 1
  • Por aplicativo e combinação de usuário: 1
  • Por usuário (para transcrições de acompanhamento de assinaturas em todas as reuniões online organizadas pelo usuário): 10 assinaturas.
  • Por organização: total de 10.000 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 um chat específico com o parâmetro de consulta notifyOnUserSpecificProperties : /chats/{id}?notifyOnUserSpecificProperties={Boolean}

Alterações em todos os chats em uma organização onde um determinado aplicativo do Teams está instalado: /appCatalogs/teamsApps/{id}/installedToChats

Alterações em todos os chats dos quais um determinado usuário faz parte: /users/{id}/chats

Alterações em todos os chats dos quais um determinado usuário faz parte com o parâmetro de consulta notifyOnUserSpecificProperties : /users/{id}/chats?notifyOnUserSpecificProperties={Boolean}		 Cotas máximas de assinaturas:
  • Por combinação de aplicativo e chat: 1 assinatura.
  • Por organização: total de 10.000 assinaturas.
  • Por usuário (para assinaturas que acompanham todos os chats dos quais um determinado usuário faz parte): 10 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 dos quais 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 determinado aplicativo do Teams está instalado: /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages		 Cotas máximas de assinaturas:
  • Por aplicativo e combinação de canal ou chat: 1 assinatura.
  • Por usuário (para assinaturas que acompanham mensagens de chat em todos os chats dos quais o usuário faz parte): 10 assinaturas.
  • Por organização: total de 10.000 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:
  • Combinação por aplicativo e equipe: 1 assinatura.
  • Por organização: total de 10.000 assinaturas.
conversationMember do Teams Alterações na associação de uma equipe específica: /teams/{id}/members

Alterações na associação em todos os canais de 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 de todos os chats em uma organização em que um determinado aplicativo 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:
  • Combinação por aplicativo e equipe: 1 assinatura.
  • Por organização: total de 10.000 assinaturas.
Teams onlineMeeting* Alterações em uma reunião online: /communications/onlineMeetings(joinWebUrl='{encodedJoinWebUrl}')/meetingCallEvents Não dá suporte ao uso $select para retornar apenas propriedades selecionadas. A notificação avançada consiste em todas as propriedades da instância alterada. Uma assinatura permitida por aplicativo 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 na presença de um único usuário: /communications/presences/{id}

Alterações na presença de vários usuários: /communications/presences?$filter=id in ({id},{id}...)		 A assinatura para a presença de vários usuários é limitada a 650 usuários distintos. Não dá suporte ao uso $select para retornar apenas propriedades selecionadas. A notificação avançada consiste em todas as propriedades da instância alterada. Uma assinatura permitida por aplicativo por usuário 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 em qualquer equipe no locatário: /teams

Alterações em uma equipe específica: /teams/{id}		 Cotas máximas de assinaturas:
  • Combinação por aplicativo e equipe: 1 assinatura.
  • Por organização: total de 10.000 assinaturas.
Turnos do Teams offerShiftRequest Alterações em qualquer solicitação de turno de oferta em uma equipe: /teams/{id}/schedule/offerShiftRequests Cotas máximas de assinaturas:
  • Combinação por aplicativo e caminho de recurso: 1 assinatura por locatário.
  • Por caminho de recurso e combinação de usuário: 10 assinaturas de usuário delegadas por locatário.
Turnos do Teams openShiftChangeRequest Alterações em qualquer solicitação de turno aberto em uma equipe: /teams/{id}/schedule/openShiftChangeRequests Cotas máximas de assinaturas:
  • Combinação por aplicativo e caminho de recurso: 1 assinatura por locatário.
  • Combinação por usuário e caminho de recurso: 10 assinaturas.
  • Por organização: total de 10.000 assinaturas.
Turnos do Teams turno Alterações em qualquer turno em uma equipe: /teams/{id}/schedule/shifts Cotas máximas de assinaturas:
  • Combinação por aplicativo e caminho de recurso: 1 assinatura por locatário.
  • Combinação por usuário e caminho de recurso: 10 assinaturas.
  • Por organização: total de 10.000 assinaturas.
Troca de turnos do Teams ShiftsChangeRequest Alterações em qualquer solicitação de troca de turno em uma equipe: /teams/{id}/schedule/swapShiftsChangeRequests Cotas máximas de assinaturas:
  • Combinação por aplicativo e caminho de recurso: 1 assinatura por locatário.
  • Combinação por usuário e caminho de recurso: 10 assinaturas.
  • Por organização: total de 10.000 assinaturas.
TimeOffRequest dos turnos do Teams Alterações em qualquer solicitação de folga em uma equipe: /teams/{id}/schedule/timeOffRequests Cotas máximas de assinaturas:
  • Combinação por aplicativo e caminho de recurso: 1 assinatura por locatário.
  • Combinação por usuário e caminho de recurso: 10 assinaturas.
  • Por organização: total de 10.000 assinaturas.
todoTask Alterações em todas as tarefas em uma lista de tarefas específica: /me/todo/lists/{todoTaskListId}/tasks -
user Alterações para todos os usuários: /users

Alterações em um usuário específico: /users/{id}		 Cotas máximas de assinaturas:
  • Por aplicativo (para todos os locatários combinados): 50.000 assinaturas no total.
  • Por locatário (para todos os aplicativos combinados): 1.000 assinaturas no total em todos os aplicativos
  • Combinação por aplicativo e locatário: total de 100 assinaturas.


Não há suporte para contas pessoais da Microsoft como outlook.com.

Não há suporte para locatários do Azure AD B2C.

OBSERVAÇÃO: A criação e a exclusão reversível de usuários também acionam o updatedchangeType.

Observação

Muitos recursos têm limites ou cotas de quantas assinaturas podem ser feitas nesse recurso. Ao exceder esse limite, as tentativas de criar uma assinatura resultarão em uma resposta de 403 Forbidden erro. A propriedade message 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 detalhes, consulte Configurar notificações de alteração que incluem dados de recursos.

Tempo de vida da assinatura

As assinaturas têm tempo de vida limitado. Os aplicativos precisam renovar suas assinaturas antes do tempo de expiração; Caso contrário, eles precisarão 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
Copilot aiInteraction 4.320 minutos (três dias)
Alerta de segurança 43.200 minutos (menos de 30 dias)
Aprovações de equipes 43.200 minutos (menos de 30 dias)
Teams callRecord 4.230 minutos (menos de três dias)
CallRecording do Teams 4.320 minutos (três dias)
Transcrição de chamada do Teams 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)
Turnos do Teams offerShiftRequest 360 minutos (6 horas)
Turnos do Teams openShiftChangeRequest 360 minutos (6 horas)
Turnos do Teams turno 360 minutos (6 horas)
Troca de turnos do Teams ShiftsChangeRequest 360 minutos (6 horas)
TimeOffRequest dos turnos do Teams 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)

Para assinaturas com dados de recurso (assinaturas de notificação avançada), o tempo de vida da assinatura é de 1440 minutos (menos de um dia).
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 esse recurso só estão disponíveis no ponto de extremidade global e não nas nuvens nacionais.
Alerta de Monitoramento de Integridade do Microsoft Entra 42.300 minutos (menos de 30 dias)
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
aiInteraction Menos de 10 segundos 60 minutos
Alerta1 Menos de 3 minutos 5 minutos
Aprovações Menos de 10 segundos 40 segundos
calendar Menos de 1 minuto Três minutos
callRecord2 Menos de 30 minutos 150 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 6 horas
evento Desconhecido Desconhecido
grupo Desconhecido Desconhecido
alerta de monitoramento de integridade Desconhecido Desconhecido
lista Menos de 1 minuto 6 horas
message 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 depois que o alerta é criado. Não inclui o tempo necessário para uma regra criar um alerta a partir dos dados. 2 A latência fornecida para o recurso callRecord só é aplicável à primeira versão de um registro de chamada. As versões subsequentes de um registro de chamada podem ser atualizadas além das latências declaradas.

Exemplos de código

Os exemplos de código a seguir estão disponíveis no GitHub.

Conteúdo relacionado

  • Last updated on