Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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 APIs de tarefas pendentes criado nesses recursos foi 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 APIs criado em todoTask.
Representa uma assinatura que permite que um aplicativo cliente receba notificações de alteração sobre alterações nos dados no Microsoft Graph.
Para obter mais informações sobre assinaturas e notificações de alteração, incluindo recursos que dão suporte a notificações de alteração, consulte Configurar notificações de alterações nos dados do recurso.
Métodos
| Método | Tipo de retorno | Descrição |
|---|---|---|
| List | subscription | Listar assinaturas ativas. |
| Create | subscription | Assine um aplicativo ouvinte para receber notificações de alteração quando os dados do Microsoft Graph forem alterados. Quando uma assinatura é criada e validada com êxito, o Microsoft Graph envia ao aplicativo pelo menos um objeto changeNotificationCollection sempre que há uma alteração no recurso assinado. |
| Get | subscription | Propriedades de leitura e relações do objeto de assinatura. |
| Atualizar | subscription | Renove uma assinatura atualizando seu tempo de expiração. |
| Delete | Nenhum | Exclua um objeto de assinatura. |
| Reautorizar | Nenhum | Reautorize uma assinatura quando receber um desafio reauthorizationRequired . |
| Obter VAPID | Cadeia de caracteres | Obtenha a chave pública VAPID (Identificação Voluntária do Servidor de Aplicativos) a ser usada para criar a assinatura após RFC8292. |
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
| ApplicationId | Cadeia de caracteres | Opcional. Identificador do aplicativo usado para criar a assinatura. Somente leitura. |
| changeType | Cadeia de caracteres | Obrigatório. Indica o tipo de alteração no recurso inscrito que gera uma notificação de alteração. Os valores com suporte são: created, updated, deleted. Vários valores podem ser combinados usando uma lista separada por vírgula. Observação:
|
| clientState | String | Opcional. Especifica o valor da propriedade clientState enviada pelo serviço em cada notificação de alteração. O tamanho máximo é de 255 caracteres. O cliente pode marcar se a notificação de alteração veio do serviço comparando o valor da propriedade clientState enviada com a assinatura com o valor da propriedade clientState recebida com cada notificação de alteração. |
| creatorId | String | Opcional. Identificador de usuário ou entidade de serviço que criou a assinatura. Se o aplicativo usou permissões delegadas para criar a assinatura, esse campo contém a ID do usuário conectado em nome do qual o aplicativo chamou. Se o aplicativo usou permissões de aplicativo, esse campo contém a ID da entidade de serviço correspondente ao aplicativo. Somente leitura. |
| encryptionCertificate | Cadeia de caracteres | Opcional. Uma representação codificada em Base64 de um certificado com uma chave pública usada para criptografar os dados de recursos nas notificações de alteração. Opcional, mas necessário quando includeResourceData é true. |
| encryptionCertificateId | String | Opcional. Um identificador personalizado fornecido pelo aplicativo para ajudar a identificar o certificado necessário para descriptografar os dados do recurso. Obrigatório quando includeResourceData é true. |
| expirationDateTime | DateTimeOffset | Obrigatório. Especifica a data e a hora em que a assinatura do webhook expira. O horário está em UTC e pode ser uma quantidade de tempo desde a criação da assinatura que varia para o recurso assinado. Qualquer valor abaixo de 45 minutos após a hora da solicitação é definido automaticamente como 45 minutos após a hora da solicitação. Para obter a duração máxima da assinatura com suporte, consulte Tempo de vida da assinatura. |
| id | String | Opcional. Identificador exclusivo da assinatura. Somente leitura. |
| includeResourceData | Booleano | Opcional. Quando definido como true, alterar as notificações inclui dados de recurso (como o conteúdo de uma mensagem de bate-papo). |
| latestSupportedTlsVersion | Cadeia de caracteres | Opcional. Especifica a versão mais recente do protocolo TLS que o ponto de extremidade, especificado por notificationUrl, é compatível. Os valores possíveis são: v1_0, v1_1, v1_2, v1_3.
Para assinantes cujo ponto de extremidade de notificação dá suporte a uma versão inferior à versão atualmente recomendada (TLS 1.2), especificar essa propriedade por uma linha do tempo definida permite que eles usem temporariamente a versão obsoleta do TLS antes de concluir a atualização para o TLS 1.2. Para esses assinantes, não definir essa propriedade pela linha do tempo resultaria em uma falha nas operações da assinatura. Para assinantes cujo ponto de extremidade de notificação já dá suporte ao TLS 1.2, definir essa propriedade é opcional. Nesses casos, o Microsoft Graph padroniza a propriedade como v1_2. |
| lifecycleNotificationUrl | String | Necessário para recursos do Teams se o valor for superior a expirationDateTime 1 hora a partir de agora; caso contrário, é opcional. A URL do ponto de extremidade que recebe notificações do ciclo de vida, incluindo subscriptionRemoved, reauthorizationRequirede missed notificações. Esta URL deve fazer uso do protocolo HTTPS. Para obter mais informações, consulte Reduzir assinaturas ausentes e notificações de alteração. |
| notificationContentType | Cadeia de caracteres | Opcional. O tipo de conteúdo desejado para notificações de alteração do Microsoft Graph para tipos de recursos com suporte. O tipo de conteúdo padrão é application/json. |
| notificationQueryOptions | String | Opcional. Opções de consulta OData para especificar o valor do recurso de direcionamento. Os clientes recebem notificações quando o recurso atinge o estado correspondente às opções de consulta fornecidas aqui. Com essa nova propriedade no conteúdo de criação de assinatura junto com todas as propriedades existentes, os Webhooks entregam notificações sempre que um recurso atinge o estado desejado mencionado na propriedade notificationQueryOptions . Por exemplo, quando o trabalho de impressão é concluído ou quando um valor de propriedade de recurso de trabalho de impressão isFetchable torna-se true etc. Suporte apenas para o Serviço de Impressão Universal. Para obter mais informações, consulte Assinar para alterar as notificações de APIs de impressão na nuvem usando o Microsoft Graph. |
| notificationUrl | Cadeia de caracteres | Obrigatório. A URL do ponto de extremidade que recebe as notificações de alteração. 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. |
| notificationUrlAppId | String | Opcional. A ID do aplicativo que o serviço de assinatura pode usar para gerar o token de validação. O valor permite que o cliente valide a autenticidade da notificação recebida. |
| recurso | Cadeia de caracteres | Obrigatório. Especifica o recurso monitorado quanto a alterações. Não inclua a URL base (https://graph.microsoft.com/beta/). Consulte os possíveis valores do caminho do recurso de cada recurso suportado. |
| vapidPublicKey | String | Opcional. A chave pública VAPID do servidor de aplicativos, codificada em base64url (ponto descompactado P-256, pré-codificação de 65 bytes). Obtido chamando a função getVapidPublicKey na coleção de assinaturas. O navegador passa esse valor para PushManager.subscribe({ applicationServerKey }) vincular a assinatura push a essa identidade do servidor. Obrigatório quando notificationUrl tem como destino uma origem de serviço Web Push conhecida (por exemplo, *.push.apple.com, fcm.googleapis.com, ); updates.push.services.mozilla.comrejeitado com 400 Bad Request se fornecido em uma assinatura de webhook padrão. Para obter mais informações, consulte RFC 8292. |
| webPushEncryptionP256dhPublicKey | String | Opcional. A chave pública ECDH do assinante, codificada em base64url (ponto descompactado P-256, pré-codificação de 65 bytes). Obtido no navegador via PushSubscription.getKey('p256dh'). Usado como a chave pública par durante o acordo de chave ECDH para derivar a chave de criptografia de conteúdo por mensagem para criptografia de conteúdo RFC 8291. Necessário quando notificationUrl tem como destino uma origem de serviço Web Push conhecida; rejeitado com 400 Bad Request se fornecido em uma assinatura de webhook padrão. Para obter mais informações, consulte RFC 8291 Seção 3. |
| webPushEncryptionSecret | String | Opcional. O segredo de autenticação do assinante, codificado em base64url (pré-codificação de 16 bytes). Obtido no navegador via PushSubscription.getKey('auth'). Usado como o sal HMAC-SHA-256 para a etapa de combinação HKDF que deriva o material de chave para a criptografia de carga útil RFC 8291. Somente gravação: esse valor nunca é retornado em respostas GET (retornado como null). Trate como um segredo. Necessário quando notificationUrl tem como destino uma origem de serviço Web Push conhecida; rejeitado com 400 Bad Request se fornecido em uma assinatura de webhook padrão. Para obter mais informações, consulte RFC 8291 Seção 3. |
Tempo de vida da assinatura
As assinaturas têm tempo de vida limitado. Os aplicativos precisam renovar suas assinaturas antes do tempo de expiração; caso contrário, eles precisarão criar uma nova assinatura. Os aplicativos também podem cancelar a assinatura a qualquer momento para deixarem de receber notificações de alteração.
Além disso, qualquer solicitação com expirationDateTime definida como menos de 45 minutos após a hora da solicitação é definida automaticamente como 45 minutos após a hora da solicitaçã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 |
|---|---|
| Copilot aiInteraction | 4.320 minutos (três dias) |
| Alerta de segurança | 43.200 minutos (menos de 30 dias) |
| Aprovações de equipes | 43.200 minutos (menos de 30 dias) |
| Teams callRecord | 4.230 minutos (menos de três dias) |
| CallRecording do Teams | 4.320 minutos (três dias) |
| Transcrição de chamada do Teams | 4.320 minutos (três dias) |
| Canal do Teams | 4.320 minutos (três dias) |
| Chat do Teams | 4.320 minutos (três dias) |
| Teams chatMessage | 4.320 minutos (três dias) |
| conversationMember do Teams | 4.320 minutos (três dias) |
| onlineMeeting do Teams | 4.320 minutos (três dias) |
| Equipe do Teams | 4.320 minutos (três dias) |
| Teams : teamsAppInstallation | 4.320 minutos (3 dias) |
| Turnos do Teams offerShiftRequest | 360 minutos (6 horas) |
| Turnos do Teams openShiftChangeRequest | 360 minutos (6 horas) |
| Turnos do Teams turno | 360 minutos (6 horas) |
| Troca de turnos do Teams ShiftsChangeRequest | 360 minutos (6 horas) |
| TimeOffRequest dos turnos do Teams | 360 minutos (6 horas) |
| Conversa em grupo | 4.230 minutos (menos de três 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 | 10.080 minutos (menos de sete dias) Para assinaturas com dados de recurso (assinaturas de notificação avançada), o tempo de vida da assinatura é de 1440 minutos (menos de um dia). |
| usuário, grupo, outros recursos de diretório | 41.760 minutos (menos de 29 dias) |
| onlineMeeting | 4.230 minutos (menos de três dias) |
| presence | 60 minutos (1 hora) |
| Imprimir printer | 4.230 minutos (menos de três dias) |
| Imprimir printTaskDefinition | 4.230 minutos (menos de três dias) |
| todoTask | 4.230 minutos (menos de três dias) Os webhooks para esse recurso só estão disponíveis no ponto de extremidade global e não nas nuvens nacionais. |
| Alerta de Monitoramento de Integridade do Microsoft Entra | 42.300 minutos (menos de 30 dias) |
| baseTask (preterido) | 4.230 minutos (menos de três 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 |
|---|---|---|
| aiInteraction | Menos de 10 segundos | 60 minutos |
| Alerta1 | Menos de 3 minutos | 5 minutos |
| Aprovações | Menos de 10 segundos | 40 segundos |
| calendar | Menos de 1 minuto | Três minutos |
| callRecord2 | Menos de 30 minutos | 150 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 | 6 horas |
| evento | Desconhecido | Desconhecido |
| grupo | Desconhecido | Desconhecido |
| alerta de monitoramento de integridade | Desconhecido | Desconhecido |
| lista | Menos de 1 minuto | 6 horas |
| message | Menos de 1 minuto | Três minutos |
| offerShiftRequest | Menos de 1 minuto | 60 minutos |
| onlineMeeting | Menos de 10 segundos | 1 minuto |
| openShiftChangeRequest | Menos de 1 minuto | 60 minutos |
| presence | Menos de 10 segundos | 1 minuto |
| impressora | Menos de 1 minuto | 5 minutos |
| printTaskDefinition | Menos de 1 minuto | 5 minutos |
| shift | Menos de 1 minuto | 60 minutos |
| swapShiftsChangeRequest | Menos de 1 minuto | 60 minutos |
| equipe | Menos de 10 segundos | 60 minutos |
| teamsAppInstallation | Menos de 10 segundos | 60 minutos |
| timeOffRequest | Menos de 1 minuto | 60 minutos |
| todoTask | Menos de 2 minutos | 15 minutos |
| usuário | Desconhecido | Desconhecido |
1 A latência fornecida para o recurso de alerta só é aplicável depois que o alerta é criado. Não inclui o tempo necessário para uma regra criar um alerta a partir dos dados. 2 A latência fornecida para o recurso callRecord só é aplicável à primeira versão de um registro de chamada. As versões subsequentes de um registro de chamada podem ser atualizadas além das latências declaradas.
Relações
Nenhum
Representação JSON
A representação JSON a seguir mostra o tipo de recurso.
{
"@odata.type": "#microsoft.graph.subscription",
"applicationId": "String",
"changeType": "String",
"clientState": "String",
"creatorId": "String",
"encryptionCertificate": "String",
"encryptionCertificateId": "String",
"expirationDateTime": "String (timestamp)",
"id": "String (identifier)",
"includeResourceData": "Boolean",
"latestSupportedTlsVersion": "String",
"lifecycleNotificationUrl": "String",
"notificationContentType": "String",
"notificationQueryOptions": "String",
"notificationUrl": "String",
"notificationUrlAppId": "String",
"resource": "String",
"vapidPublicKey": "String",
"webPushEncryptionP256dhPublicKey": "String",
"webPushEncryptionSecret": "String"
}