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

  • Artigo

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.

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:
  • Por aplicativo (para todos os locatários combinados): 50.000 assinaturas totais.
  • Por locatário (para todos os aplicativos combinados): 1000 assinaturas totais em todos os aplicativos.
  • Por combinação de aplicativo e locatário: 100 assinaturas totais.

    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 updatedchangeType.
    		•
    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:
  • Por organização: 100 assinaturas totais.

    NOTA: A criação de registros de chamada também dispara o updatedchangeType.
    		•
    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:
  • Por aplicativo e combinação de reunião online: 1
  • Por aplicativo e combinação de usuário: 1
  • Por usuário (para assinaturas que acompanham gravações em todos os onlineMeetings organizados pelo usuário): 10 assinaturas.
  • Por organização: 10.000 assinaturas totais.
    		•
    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:
  • Por aplicativo e combinação de reunião online: 1
  • Por aplicativo e combinação de usuário: 1
  • Por usuário (para assinaturas que acompanham transcrições em todos os onlineMeetings organizados pelo usuário): 10 assinaturas.
  • Por organização: 10.000 assinaturas totais.
    		•
    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:
  • Por combinação de aplicativo e chat: 1 assinatura.
  • Por organização: 10.000 assinaturas totais.
    		•
    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:
  • 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 do qual o usuário faz parte): 10 assinaturas.
  • Por organização: 10.000 assinaturas totais.
    		•
    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:
  • Por combinação de aplicativo e equipe: 1 assinatura.
  • Por organização: 10.000 assinaturas totais.
    		•
    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:
  • Por combinação de aplicativo e equipe: 1 assinatura.
  • Por organização: 10.000 assinaturas totais.
    		•
    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:
  • Por combinação de aplicativo e equipe: 1 assinatura.
  • Por organização: 10.000 assinaturas totais.
    		•
    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:
  • Por aplicativo (para todos os locatários combinados): 50.000 assinaturas totais.
  • Por locatário (para todos os aplicativos combinados): 1000 total de assinaturas em todos os aplicativos
  • Por combinação de aplicativo e locatário: 100 assinaturas totais.

    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 updatedchangeType.
    		•

    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.

    Conteúdo relacionado