Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Namespace: microsoft.graph
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 | assinatura | Lista assinaturas ativas. |
| Create | assinatura | Assina um aplicativo de escuta para receber notificações sobre alterações nos dados do Microsoft Graph. 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 | Lê as propriedades e as relações do objeto subscription. |
| Atualizar | subscription | Atualizações o tempo de expiração de uma assinatura para renovação e/ou atualiza o notificationUrl para entrega. |
| Delete | Nenhuma | Exclui um objeto assinatura. |
| Reautorizar | Nenhum | Reautorize uma assinatura quando receber um desafio reauthorizationRequired . |
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: updated changeType. updated e deleted changeType. Use updated para receber notificações quando um usuário ou grupo é criado, atualizado ou excluído temporariamente. Use deleted para receber notificações quando o usuário ou grupo for excluído permanentemente. |
| clientState | String | Opcional. Especifica o valor da propriedade clientState enviada pelo serviço em cada notificação de alteração. O comprimento máximo é de 128 caracteres. O cliente pode verificar se a notificação de alteração veio do serviço pela comparação do valor da propriedade clientState enviada com a assinatura com o valor da propriedade clientState recebida contendo 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. |
| 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. |
| notificationQueryOptions | String | Opcional. Opções de consulta OData para especificar o valor para o recurso de direcionamento. Os clientes recebem notificações quando o recurso atinge ao estado correspondente às opções de consulta aqui fornecidas. 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/v1.0/). Consulte os possíveis valores do caminho do recurso de cada recurso suportado. |
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",
"notificationQueryOptions": "String",
"notificationUrl": "String",
"notificationUrlAppId": "String",
"resource": "String"
}