Partilhar via

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

  • Artigo

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

As aplicações existentes que utilizam esta funcionalidade com baseTask ou baseTaskList devem ser atualizadas, uma vez que o conjunto de API a fazer incorporado nestes recursos é preterido a partir de 31 de maio de 2022. Esse conjunto de API deixará de retornar dados em 31 de agosto de 2022. Utilize o conjunto de API criado no todoTask.

A API REST do Microsoft Graph pode entregar notificações de alteração aos clientes através de vários pontos finais, incluindo webhooks, Hubs de Eventos e Event Grid. Para saber como subscrever e receber notificações para a sua aplicação, consulte Configurar notificações para alterações nos dados do utilizador.

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.

    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 subscrição requerem permissão de leitura para o recurso. Por exemplo, para receber notificações de mensagens, a sua aplicação precisa da Mail.Read permissão. O artigo criar subscrição lista as permissões necessárias para cada tipo de recurso. A tabela seguinte lista os tipos de permissões que a sua aplicação pode pedir para utilizar webhooks para tipos de recursos específicos.

    Tipo de permissão Tipos de recurso com suporte
    Delegado - conta corporativa ou de estudante alerta, chamadaRecording, callTranscript, canal, chat, chatMessage (pré-visualização), contacto, conversação, conversationMember, driveItem, evento, grupo, lista, mensagem, offerShiftRequest, openShiftChangeRequest, presença, turno, swapShiftsChangeRequest, equipa, timeOffRequest, todoTask, utilizador, baseTask (preterido)
    Delegado - conta pessoal da Microsoft contact, driveItem, event, list, message, todoTask, baseTask (preterido)
    Application alerta, callRecord, aprovações, callRecording, callTranscript, channel, chat, chatMessage, contact, conversationMember, driveItem, event, group, list, message, offerShiftRequest, onlineMeeting, openShiftChangeRequest, printer, printTaskDefinition, shift, swapShiftsChangeRequest, equipa, timeOffRequest, utilizador

    Conteúdo relacionado