Atualizar assinatura
Namespace: microsoft.graph
Renove uma assinatura ampliando seu tempo de validade.
A tabela na seção Permissões lista os recursos que dão suporte à assinatura de notificações de alteração.
As assinaturas expiram após um período de tempo que varia de acordo com o tipo de recurso. Para evitar notificações de alteração ausentes, um aplicativo deve renovar suas assinaturas bem antes da data de validade. Consulte assinatura para obter o comprimento máximo de uma assinatura para cada tipo de recurso.
Essa API está disponível nas seguintes implantações nacionais de nuvem.
Serviço global | Governo dos EUA L4 | GOVERNO DOS EUA 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 em uma 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 em uma reunião organizada por um usuário específico. |
OnlineMeetingRecording.Read.All | Sem suporte. | OnlineMeetingRecording.Read.All |
callTranscript communications/onlineMeetings/getAllTranscripts Todas as transcrições em uma 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 chamada que fica disponível em uma reunião organizada por um usuário 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 Todos os chats em uma organização em que um aplicativo específico do Teams está instalado. |
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 todos os chats em uma organização em que um aplicativo específico do Teams está instalado. |
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 Membros do chat para todos os chats em uma organização em que um aplicativo específico do Teams está instalado. |
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 |
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 |
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 |
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.
Você deve usar o cabeçalho de Prefer: include-unknown-enum-members
solicitação para obter os seguintes valores em chatMessagemessageTypeenume 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/getAllMessages
e /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
são APIs limitadas; modelos de pagamento e requisitos de licenciamento podem ser aplicados .
/teams/getAllMessages
e /chats/getAllMessages
dar suporte a model=A
modelos de model=B
pagamento, /me/chats/getAllMessages
, , /users/{id}/chats/getAllMessages
e /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
dar suporte apenas model=B
a .
Se você não especificar um modelo de pagamento em sua consulta, o modo de avaliação padrão será usado.
Observação
Para adicionar ou alterar um modelo de pagamento para um recurso inscrito de uma notificação de alteração, você deve criar uma nova assinatura de notificação de alteração com o novo modelo de pagamento; A atualização de uma notificação de alteração existente não funciona.
conversationMember
as assinaturas conversationMember 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.
Observação
/teams/getAllMembers
, /chats/getAllMembers
e /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
são APIs limitadas; modelos de pagamento e requisitos de licenciamento podem ser aplicados .
/teams/getAllMembers
e /chats/getAllMembers
dar suporte a model=A
modelos de pagamento e .model=B
/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
dá suporte apenas model=B
a .
Se você não especificar um modelo de pagamento em sua consulta, o modo de avaliação padrão será usado.
Observação
Para adicionar ou alterar um modelo de pagamento para um recurso inscrito de uma notificação de alteração, você deve criar uma nova assinatura de notificação de alteração com o novo modelo de pagamento; A atualização de uma notificação de alteração existente não funciona.
team, channel e chat
assinaturas de equipe, canal e chat 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.
Observação
/appCatalogs/teamsApps/{id}/installedToChats
tem requisitos de licenciamento e pagamento, especificamente com suporte 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 inscrito de uma notificação de alteração, você deve criar uma nova assinatura de notificação de alteração com o novo modelo de pagamento; A atualização de 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. Você não pode assinar instâncias drive ou driveItem que não são pastas, como arquivos 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, você não pode usar a permissão delegada Calendars.Read para assinar eventos na caixa de correio de outro usuário.
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 use as permissões de compartilhamento do Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared e seus equivalentes de leitura/gravação), pois elas não dão suporte à assinatura para alterar notificações em itens em pastas compartilhadas ou delegadas.
presença
as assinaturas de presença exigem criptografia para notificações que incluem dados de recurso. A criação da assinatura falhará se a criptografiaCertificate e encryptionCertificateId não forem especificadas quando as notificações precisarem incluir dados de recurso. Para obter detalhes sobre assinaturas de presença, confira Obter notificações de alteração para atualizações de presença no Microsoft Teams.
virtualEventWebinar
As assinaturas em eventos virtuais dão suporte apenas a notificações básicas e são limitadas a algumas entidades de um evento virtual. Para obter mais informações sobre os tipos de assinatura com suporte, confira 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. |
Corpo da solicitação
No corpo da solicitação, forneça apenas os valores das propriedades que devem ser atualizadas. As propriedades existentes que não estão incluídas no corpo da solicitação mantêm seus valores anteriores ou são recalculadas com base em alterações em outros valores de propriedade.
A tabela a seguir especifica as propriedades que podem ser atualizadas.
O corpo da solicitação deve incluir pelo menos uma das propriedades listadas.
Nome | Tipo | Descrição |
---|---|---|
expirationDateTime | DateTimeOffset | Especifica a data e a hora em UTC quando a assinatura expira. Para o tempo máximo de assinatura com suporte varia dependendo do recurso. |
notificationUrl | Cadeia de caracteres | Esta URL deve fazer uso do protocolo HTTPS. Qualquer parâmetro de cadeia de caracteres de consulta incluído na propriedade notificationUrl é incluído na solicitação 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"
}
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de