Compartilhar via


Atualizar assinatura

Namespace: microsoft.graph

Renove uma assinatura ampliando seu tempo de validade.

A tabela na secção Permissões lista os recursos que suportam a subscrição de notificações de alteração.

As subscrições expiram após um período de tempo que varia de acordo com o tipo de recurso. Para evitar notificações de alteração em falta, uma aplicação deve renovar as subscrições antes da data de expiração. Veja a subscrição para obter o comprimento máximo de uma subscrição para cada tipo de recurso.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global US Government L4 US Government L5 (DOD) China operada pela 21Vianet

Permissões

Dependendo do recurso e do tipo de permissão (delegado ou aplicativo) solicitado, a permissão especificada na tabela a seguir é a menos privilegiada necessária para fazer chamadas a esta API. Para saber mais, incluindo tomar cuidado antes de escolher as permissões mais privilegiadas, pesquise as seguintes permissões em Permissões.

Recurso com suporte Delegada (conta corporativa ou de estudante) Delegada (conta pessoal da Microsoft) Aplicativo
callRecord Incompatível Incompatível CallRecords.Read.All
callRecording
communications/onlineMeetings/getAllRecordings
Todas as gravações numa organização.
Sem suporte. Sem suporte. OnlineMeetingRecording.Read.All
callRecording
communications/onlineMeetings/{onlineMeetingId}/recordings
Todas as gravações para uma reunião específica.
OnlineMeetingRecording.Read.All Sem suporte. OnlineMeetingRecording.Read.All
callRecording
users/{userId}/onlineMeetings/getAllRecordings
Uma gravação de chamada que fica disponível numa reunião organizada por um utilizador específico.
OnlineMeetingRecording.Read.All Sem suporte. OnlineMeetingRecording.Read.All
callTranscript
communications/onlineMeetings/getAllTranscripts
Todas as transcrições numa organização.
Sem suporte. Sem suporte. OnlineMeetingTranscript.Read.All
callTranscript
communications/onlineMeetings/{onlineMeetingId}/transcripts
Todas as transcrições de uma reunião específica.
OnlineMeetingTranscript.Read.All Sem suporte. OnlineMeetingTranscript.Read.All
callTranscript
users/{userId}/onlineMeetings/getAllTranscripts
Uma transcrição de chamadas que fica disponível numa reunião organizada por um utilizador específico.
OnlineMeetingTranscript.Read.All Sem suporte. OnlineMeetingTranscript.Read.All
canal (/teams/getAllChannels – todos os canais em uma organização) Incompatível Sem suporte Channel.ReadBasic.All, ChannelSettings.Read.All
canal (/teams/{id}/channels) Channel.ReadBasic.All, ChannelSettings.Read.All Sem suporte Channel.ReadBasic.All, ChannelSettings.Read.All
chat chat (/conversa – todos os chats em uma organização) Incompatível Incompatível Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
chat (/chats/{id}) Chat.ReadBasic, Chat.Read, Chat.ReadWrite Sem suporte ChatSettings.Read.Chat*, ChatSettings.ReadWrite.Chat*, Chat.Manage.Chat*, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
chat
/appCatalogs/teamsApps/{id}/installedToChats
Todas as conversas numa organização onde está instalada uma determinada aplicação do Teams.
Sem suporte Sem suporte Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
chatMessage (/teams/{id}/channels/{id}/messages) ChannelMessage.Read.All Sem suporte ChannelMessage.Read.Group*, ChannelMessage.Read.All
chatMessage (/teams/getAllMessages -- todas as mensagens de canal na organização) Sem suporte Sem suporte ChannelMessage.Read.All
chatMessage (/chats/{id}/messages) Sem suporte Sem suporte Chat.Read.All
chatMessage (/teams/getAllMessages -- todas as mensagens de chat na organização) Sem suporte Sem suporte Chat.Read.All
chatMessage (/users/{id}/chats/getAllMessages -- mensagens de chat para todos os chats dos quais um usuário específico faz parte) Chat.Read, Chat.ReadWrite Sem suporte Chat.Read.All, Chat.ReadWrite.All
chatMessage
/appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
Mensagens de chat para todas as conversas numa organização onde está instalada uma determinada aplicação do Teams.
Sem suporte Sem suporte Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
contato Contacts.Read Contacts.Read Contacts.Read
conversationMember (/chats/getAllMembers) Incompatível Sem suporte ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
conversationMember (/chats/{id}/members) ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite Incompatível ChatMember.Read.Chat*, Chat.Manage.Chat*, ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
conversationMember
/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
Chat members for all chats in an organization where a particular Teams app is installed.
Sem suporte. Sem suporte. ChatMember.Read.WhereInstalled, ChatMember.ReadWrite.WhereInstalled, Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
conversationMember (/teams/{id}/members) TeamMember.Read.All Incompatível TeamMember.Read.All
conversationMember (/teams/{id}/channels/getAllMembers) Incompatível Incompatível ChannelMember.Read.All
driveItem (OneDrive pessoal de um usuário) Sem suporte Files.ReadWrite Sem suporte
driveItem (OneDrive for Business) Files.ReadWrite.All Sem suporte Files.ReadWrite.All
evento Calendars.Read Calendars.Read Calendars.Read
grupo Group.Read.All Sem suporte Group.Read.All
conversa em grupo Group.Read.All Sem suporte Sem suporte
list Sites.ReadWrite.All Sem suporte Sites.ReadWrite.All
message Mail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.Read Mail.Read
offerShiftRequest
(/teams/{id}/schedule/offerShiftRequests)
Alterações a qualquer pedido de turno de oferta numa equipa.
Schedule.Read.All, Schedule.ReadWrite.All Sem suporte. Schedule.Read.All, Schedule.ReadWrite.All
openShiftChangeRequest
(/teams/{id}/schedule/openShiftChangeRequests)
Alterações a qualquer pedido de turno aberto numa equipa.
Schedule.Read.All, Schedule.ReadWrite.All Sem suporte. Schedule.Read.All, Schedule.ReadWrite.All
presence Presence.Read.All Sem suporte. Sem suporte.
printer Sem suporte Sem suporte Printer.Read.All, Printer.ReadWrite.All
printTaskDefinition Sem suporte Sem suporte PrintTaskDefinition.ReadWrite.All
alerta de segurança SecurityEvents.ReadWrite.All Sem suporte SecurityEvents.ReadWrite.All
shift
(/teams/{id}/schedule/shifts)
Alterações a qualquer mudança numa equipa.
Schedule.Read.All, Schedule.ReadWrite.All Sem suporte. Schedule.Read.All, Schedule.ReadWrite.All
swapShiftsChangeRequest
(/teams/{id}/schedule/swapShiftsChangeRequests)
Alterações a qualquer pedido de turno de troca numa equipa.
Schedule.Read.All, Schedule.ReadWrite.All Sem suporte. Schedule.Read.All, Schedule.ReadWrite.All
equipe (/teams – todas as equipes em uma organização) Sem suporte Incompatível Team.ReadBasic.All, TeamSettings.Read.All
equipe (/teams/{id}) Team.ReadBasic.All, TeamSettings.Read.All Incompatível Team.ReadBasic.All, TeamSettings.Read.All
timeOffRequest
(/teams/{id}/schedule/timeOffRequests)
Alterações a qualquer pedido de folga numa equipa.
Schedule.Read.All, Schedule.ReadWrite.All Sem suporte. Schedule.Read.All, Schedule.ReadWrite.All
todoTask Tasks.ReadWrite Tasks.ReadWrite Incompatível
user User.Read.All User.Read.All User.Read.All
virtualEventWebinar VirtualEvent.Read Sem suporte. VirtualEvent.Read.All

Observação: Permissões marcadas com * usam consentimento específico de recurso.

chatMessage

chatMessage assinaturas podem ser especificadas para incluir dados de recurso. Se especificado para incluir dados de recurso (includeResourceData definido como true), encryption é necessária. A criação de assinatura falhará se um encryptionCertificate não for especificado para tais assinaturas.

Tem de utilizar o cabeçalho do Prefer: include-unknown-enum-members pedido para obter os seguintes valores no chatMessagemessageTypeenum evoluível: systemEventMessage para /teams/{id}/channels/{id}/messages e /chats/{id}/messages recurso.

Observação

/teams/getAllMessages, /chats/getAllMessages, /me/chats/getAllMessages, /users/{id}/chats/getAllMessagese /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages são APIs com tráfego limitado; podem aplicar-se modelos de pagamento e requisitos de licenciamento . /teams/getAllMessages e /chats/getAllMessages suportam modelos model=A de pagamento e model=B , /me/chats/getAllMessages, /users/{id}/chats/getAllMessagese /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages suportam apenas model=B. Se não especificar um modelo de pagamento na consulta, será utilizado o modo de avaliação predefinido.

Observação

Para adicionar ou alterar um modelo de pagamento para um recurso subscrito de uma notificação de alteração, tem de criar uma nova subscrição de notificação de alteração com o novo modelo de pagamento; atualizar uma notificação de alteração existente não funciona.

conversationMember

conversationMember subscriptions can be specified to include resource data. Se especificado para incluir dados de recurso (includeResourceData definido como true), encryption é necessária. A criação de assinatura falhará se um encryptionCertificate não for especificado.

Observação

/teams/getAllMembers, /chats/getAllMemberse /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers são APIs com tráfego limitado; podem aplicar-se modelos de pagamento e requisitos de licenciamento . /teams/getAllMembers e /chats/getAllMembers suportam modelos model=A de pagamento e model=B . /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers suporta apenas model=B. Se não especificar um modelo de pagamento na consulta, será utilizado o modo de avaliação predefinido.

Observação

Para adicionar ou alterar um modelo de pagamento para um recurso subscrito de uma notificação de alteração, tem de criar uma nova subscrição de notificação de alteração com o novo modelo de pagamento; atualizar uma notificação de alteração existente não funciona.

equipa, canal e chat

as subscrições de equipa, canal e chat podem ser especificadas para incluir dados de recursos. Se especificado para incluir dados de recurso (includeResourceData definido como true), encryption é necessária. A criação de assinatura falhará se um encryptionCertificate não for especificado.

Pode utilizar o parâmetro de cadeia de consulta notifyOnUserSpecificProperties quando subscrever alterações num chat específico ou ao nível do utilizador. Quando define o parâmetro de cadeia de consulta notifyOnUserSpecificProperties como durante a true criação da subscrição, são enviados dois tipos de payloads para o subscritor. Um tipo contém propriedades específicas do utilizador e o outro é enviado sem eles. Para obter mais informações, consulte Obter notificações de alteração para conversas com o Microsoft Graph.

Observação

/appCatalogs/teamsApps/{id}/installedToChats tem requisitos de licenciamento e pagamento, especificamente suportando apenas model=B. Se nenhum modelo for especificado, o modo de avaliação será usado.

Observação

Para adicionar ou alterar um modelo de pagamento para um recurso subscrito de uma notificação de alteração, tem de criar uma nova subscrição de notificação de alteração com o novo modelo de pagamento; atualizar uma notificação de alteração existente não funciona.

Exemplo de solicitação

Especifique o parâmetro de consulta model na propriedade recurso no corpo da solicitação.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
   "changeType": "created",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "chats/getAllMessages?model=A",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue",
   "latestSupportedTlsVersion": "v1_2"
}

driveItem

As limitações adicionais se aplicam aos itens do OneDrive. As limitações se aplicam para criação e gerenciamento de assinaturas (receber, atualizar e excluir assinaturas).

No OneDrive pessoal, você pode se inscrever em qualquer pasta raiz ou qualquer subpasta da unidade. No OneDrive for Business, você pode assinar somente a pasta raiz. As notificações de alteração são enviadas para os tipos de alterações solicitados na pasta assinada ou em qualquer arquivo, pasta ou outras instâncias driveItem em sua hierarquia. Não pode subscrever instâncias drive ou driveItem que não sejam pastas, como ficheiros individuais.

contato, evento e mensagem

Você pode assinar alterações nos recursos de contato,evento ou mensagem doOutlook.

Criar e gerenciar (obter, atualizar e excluir) uma assinatura requer um escopo de leitura para o recurso. Por exemplo, para receber notificações de alteração nas mensagens, seu aplicativo precisa da permissão Mail.Read. As notificações de alteração do Outlook dão suporte a escopos de permissão de aplicativo e delegados. Observe as seguintes limitações:

  • A permissão delegada dá suporte a inscrição de itens em pastas apenas na caixa de correio do usuário conectado. Por exemplo, não pode utilizar a permissão delegada Calendários.Ler para subscrever eventos na caixa de correio de outro utilizador.

  • Se inscrever para alterar as notificações de contatos, eventos no Outlook ou mensagens em pastascompartilhadas ou delegadas:

    • Usar a permissão de aplicativos correspondentes para inscrever as alterações dos itens em uma pasta ou uma caixa de correio de qualquer usuários no locatário.
    • Não utilize as permissões de partilha do Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared e os seus homólogos de leitura/escrita), uma vez que não suportam a subscrição para alterar notificações de itens em pastas partilhadas ou delegadas.

presença

as subscrições de presença requerem encriptação para notificações que incluam dados de recursos. A criação da subscrição falha se encryptionCertificate e encryptionCertificateId não forem especificados quando as notificações precisam de incluir dados de recursos. Para obter detalhes sobre as subscrições de presença, consulte Obter notificações de alteração para atualizações de presença no Microsoft Teams.

virtualEventWebinar

As subscrições em eventos virtuais suportam apenas notificações básicas e estão limitadas a algumas entidades de um evento virtual. Para obter mais informações sobre os tipos de subscrição suportados, veja Obter notificações de alteração para atualizações de eventos virtuais do Microsoft Teams.

Solicitação HTTP

PATCH /subscriptions/{id}

Cabeçalhos de solicitação

Nome Tipo Descrição
Autorização string {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.

Corpo da solicitação

No corpo do pedido, forneça apenas os valores das propriedades a atualizar. As propriedades existentes que não estão incluídas no corpo do pedido mantêm os valores anteriores ou são recalculadas com base em alterações a outros valores de propriedade.

A tabela a seguir especifica as propriedades que podem ser atualizadas.

O corpo do pedido tem de incluir, pelo menos, uma das propriedades listadas.

Nome Tipo Descrição
expirationDateTime DateTimeOffset Especifica a data e hora em UTC quando a subscrição expira. O período máximo de tempo da subscrição suportada varia consoante o recurso.
notificationUrl Cadeia de caracteres Esta URL deve fazer uso do protocolo HTTPS. Qualquer parâmetro de cadeia de consulta incluído na propriedade notificationUrl é incluído no pedido HTTP POST quando o Microsoft Graph envia as notificações de alteração.

Resposta

Se bem-sucedido, este método retorna um código de resposta 200 OK e um objeto subscription no corpo da resposta.

Para detalhes sobre como os erros são retornados, confira Respostas de erro.

Exemplo

Solicitação

O exemplo a seguir mostra uma solicitação.

PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}
Content-type: application/json

{
   "expirationDateTime":"2016-11-22T18:23:45.9356913Z"
}

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 200 OK
Content-type: application/json

{
  "id":"7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource":"me/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType":"created,updated",
  "clientState":"subscription-identifier",
  "notificationUrl":"https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "lifecycleNotificationUrl":"https://webhook.azurewebsites.net/api/send/lifecycleNotifications",
  "expirationDateTime":"2016-11-22T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2",
  "encryptionCertificate": "",
  "encryptionCertificateId": "",
  "includeResourceData": false,
  "notificationContentType": "application/json"
}