tipo de recurso de assinatura
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 para alterações nos dados de recursos.
Métodos
Método | Tipo de retorno | Descrição |
---|---|---|
Listar de assinaturas | assinatura | Lista assinaturas ativas. |
Criar assinatura | assinatura | Assina um aplicativo de escuta para receber notificações sobre alterações nos dados do Microsoft Graph. |
Obter assinatura | subscription | Lê as propriedades e as relações do objeto subscription. |
Atualizar assinatura | subscription | Atualizações um tempo de validade da assinatura para renovação e/ou atualiza a notificaçãoUrl para entrega. |
Excluir assinatura | Nenhuma | Exclui um objeto assinatura. |
Reautorizar | Nenhum | Reautorize uma assinatura quando receber um desafio reautorizaçãoRequired . |
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 o usuário ou grupo for criado, atualizado ou excluído. 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 conterá a ID do usuário conectado do qual o aplicativo chamou em nome. Se o aplicativo usou permissões de aplicativo, este campo conterá 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. Para obter o tempo máximo de duração 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 um conjunto linha do tempo permite que eles usem temporariamente sua versão preterida 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; opcional caso contrário. A URL do ponto de extremidade que recebe notificações do ciclo de vida, incluindo subscriptionRemoved , reauthorizationRequired e missed notificações. Esta URL deve fazer uso do protocolo HTTPS. Para obter mais informações, confira Reduzir assinaturas ausentes e alterar notificações. |
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, o Webhooks entrega 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. Com suporte apenas para o Serviço Universal de Impressão. Para obter mais informações, consulte Assinar notificações de alteração 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 para 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 validade; caso contrário, eles precisam criar uma nova assinatura. Os aplicativos também podem cancelar a assinatura a qualquer momento para deixarem de receber notificações de alteraçã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 |
---|---|
Alerta de segurança | 43.200 minutos (menos de 30 dias) |
Teams callRecord | 4.230 minutos (menos de 3 dias) |
Chamada do TeamsRecording | 4.320 minutos (3 dias) |
Teams callTranscript | 4.320 minutos (3 dias) |
Canal do Teams | 4.320 minutos (3 dias) |
Chat do Teams | 4.320 minutos (3 dias) |
Teams chatMessage | 4.320 minutos (3 dias) |
conversationMember do Teams | 4.320 minutos (3 dias) |
onlineMeeting do Teams | 4.320 minutos (3 dias) |
Equipe do Teams | 4.320 minutos (3 dias) |
Conversa em grupo | 4.230 minutos (menos de 3 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 | 4.230 minutos (menos de 3 dias) |
usuário, grupo, outros recursos de diretório | 41.760 minutos (menos de 29 dias) |
onlineMeeting | 4.230 minutos (menos de 3 dias) |
presence | 60 minutos (1 hora) |
Imprimir printer | 4.230 minutos (menos de 3 dias) |
Imprimir printTaskDefinition | 4.230 minutos (menos de 3 dias) |
todoTask | 4.230 minutos (menos de 3 dias) Os webhooks para esse recurso só estão disponíveis no ponto de extremidade global e não nas nuvens nacionais. |
baseTask (preterido) | 4.230 minutos (menos de 3 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 |
---|---|---|
alerta1 | Menos de 3 minutos | 5 minutos |
calendar | Menos de 1 minuto | Três minutos |
callRecord | Menos de 15 minutos | 60 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 | 5 minutos |
evento | Desconhecido | Desconhecido |
grupo | Desconhecido | Desconhecido |
lista | Menos de 1 minuto | 5 minutos |
mensagem | Menos de 1 minuto | Três minutos |
onlineMeeting | Menos de 10 segundos | 1 minuto |
presence | Menos de 10 segundos | 1 minuto |
impressora | Menos de 1 minuto | 5 minutos |
printTaskDefinition | Menos de 1 minuto | 5 minutos |
equipe | Menos de 10 segundos | 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 após a criação do alerta. Ele não inclui o tempo necessário para uma regra criar um alerta a partir dos dados.
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"
}
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