Compartilhar via


Usar a API do Microsoft Graph para acessar as notificações de alteração

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Cuidado

Os aplicativos existentes que usam esse recurso com baseTask ou baseTaskList devem ser atualizados, pois o conjunto de API a ser feito com base nesses recursos é preterido a partir de 31 de maio de 2022. Esse conjunto de API deixará de retornar dados em 31 de agosto de 2022. Use o conjunto de API criado em todoTask.

A API REST do Microsoft Graph pode fornecer notificações de alteração aos clientes por meio de vários pontos de extremidade, incluindo webhooks, Hubs de Eventos e Grade de Eventos. Para saber como assinar e receber notificações para seu aplicativo, confira Configurar notificações para alterações nos dados do usuário.

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 para trabalho ou escola 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): 1.000 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 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 em que um aplicativo específico 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: 10.000 assinaturas totais.
  • 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 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): 1.000 assinaturas totais 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.

    Observação: qualquer trajetória de recurso que comece com o /users/{id} também pode aceitar /me referenciar o usuário conectado.

    Permissões

    Em geral, as operações de assinatura exigem permissão de leitura para o recurso. Por exemplo, para obter notificações de mensagens, seu aplicativo precisa da Mail.Read permissão. O artigo criar assinatura lista as permissões necessárias para cada tipo de recurso. A tabela a seguir lista os tipos de permissões que seu aplicativo pode solicitar para usar webhooks para tipos de recursos específicos.

    Tipo de permissão Tipos de recurso com suporte
    Delegado - conta corporativa ou de estudante alerta, callRecording, callTranscript, channel, chat, contact, conversation, conversationMember, driveItem, list, event, group, message, user, presence, chatMessage (preview), team, todoTask, baseTask (preterido)
    Delegado - conta pessoal da Microsoft baseTask (preterido), contato, driveItem, lista, evento, mensagem, todoTask
    Application alerta, callRecording, callTranscript, channel, chat, contact, driveItem, list, event, group, message, user, callRecord, chatMessage, conversationMember, onlineMeeting, printer, printTaskDefinition, team