Configurar notificações para alterações nos dados de recursos

  • Artigo

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.

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.

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:
  • Por aplicação (para todos os inquilinos combinados): 50 000 subscrições totais.
  • Por inquilino (para todas as aplicações combinadas): 1000 subscrições totais em todas as aplicações.
  • Combinação por aplicação e inquilino: 100 subscrições totais.

    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:
  • Por locatário (para todos os aplicativos combinados): 1000 total de assinaturas em todos os aplicativos
  • Combinação por aplicação e inquilino: 1 subscrição.
    		•
    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:
  • Por organização: 100 subscrições totais.

    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:
  • Combinação por aplicação e reunião online: 1
  • Combinação por aplicação e utilizador: 1
  • Por utilizador (para subscrições que monitorizam as gravações em todos os OnlineMeetings organizados pelo utilizador): 10 subscrições.
  • Por organização: 10 000 subscrições totais.
    		•
    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:
  • Combinação por aplicação e reunião online: 1
  • Combinação por aplicação e utilizador: 1
  • Por utilizador (para subscrições que monitorizam transcrições em todos os OnlineMeetings organizados pelo utilizador): 10 subscrições.
  • Por organização: 10 000 subscrições totais.
    		•
    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:
  • Combinação por aplicação e chat: 1 subscrição.
  • Por organização: 10 000 subscrições totais.
  • Por utilizador (para subscrições que monitorizam todas as conversas de que um determinado utilizador faz parte): 10 subscrições.
    		•
    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:
  • Por aplicação e canal ou combinação de chat: 1 subscrição.
  • Por utilizador (para subscrições que monitorizam mensagens de chat em todas as conversas de que o utilizador faz parte): 10 subscrições.
  • Por organização: 10 000 subscrições totais.
    		•
    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:
  • Combinação por aplicação e equipa: 1 subscrição.
  • Por organização: 10 000 subscrições totais.
    		•
    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:
  • Combinação por aplicação e equipa: 1 subscrição.
  • Por organização: 10 000 subscrições totais.
    		•
    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:
  • Combinação por aplicação e equipa: 1 subscrição.
  • Por organização: 10 000 subscrições totais.
    		•
    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:
  • Combinação por aplicação e caminho de recurso: 1 subscrição por inquilino.
  • Por caminho de recurso e combinação de utilizador: 10 subscrições de utilizador delegadas por inquilino.
    		•
    Turnos do Teams openShiftChangeRequest Alterações a qualquer pedido de turno aberto numa equipa: /teams/{id}/schedule/openShiftChangeRequests Cotas máximas de assinaturas:
  • Combinação por aplicação e caminho de recurso: 1 subscrição por inquilino.
  • Combinação de caminho por utilizador e de recurso: 10 subscrições.
  • Por organização: 10 000 subscrições totais.
    		•
    Turnos do Teams Alterações a qualquer mudança numa equipa: /teams/{id}/schedule/shifts Cotas máximas de assinaturas:
  • Combinação por aplicação e caminho de recurso: 1 subscrição por inquilino.
  • Combinação de caminho por utilizador e de recurso: 10 subscrições.
  • Por organização: 10 000 subscrições totais.
    		•
    Teams Shifts swapShiftsChangeRequest Alterações a qualquer pedido de turno de troca numa equipa: /teams/{id}/schedule/swapShiftsChangeRequests Cotas máximas de assinaturas:
  • Combinação por aplicação e caminho de recurso: 1 subscrição por inquilino.
  • Combinação de caminho por utilizador e de recurso: 10 subscrições.
  • Por organização: 10 000 subscrições totais.
    		•
    Teams Shifts timeOffRequest Alterações a qualquer pedido de folga numa equipa: /teams/{id}/schedule/timeOffRequests Cotas máximas de assinaturas:
  • Combinação por aplicação e caminho de recurso: 1 subscrição por inquilino.
  • Combinação de caminho por utilizador e de recurso: 10 subscrições.
  • Por organização: 10 000 subscrições totais.
    		•
    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:
  • Por aplicação (para todos os inquilinos combinados): 50 000 subscrições totais.
  • Por inquilino (para todas as aplicações combinadas): 1000 subscrições totais em todas as aplicações
  • Combinação por aplicação e inquilino: 100 subscrições totais.

    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.

    Conteúdo relacionado