tipo de recurso de assinatura
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 API a ser feito com base nesses recursos é 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 API 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 para alterações nos dados de recursos.
Métodos
| Método | Tipo de retorno | Descrição |
|---|---|---|
| Listar de assinaturas | assinatura | Listar assinaturas ativas. |
| Criar assinatura | subscription | Assine um aplicativo ouvinte para receber notificações de alteração quando os dados do Microsoft Graph forem alterados. |
| Obter assinatura | subscription | Leia propriedades e relações do objeto de assinatura. |
| Atualizar assinatura | subscription | Renove uma assinatura atualizando seu tempo de validade. |
| Excluir assinatura | Nenhuma | Exclua um objeto de 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 tamanho máximo é de 255 caracteres. O cliente pode marcar que 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 a 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. Necessá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. 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, reauthorizationRequirede missed notificações. Esta URL deve fazer uso do protocolo HTTPS. Para obter mais informações, confira Reduzir assinaturas ausentes e alterar notificações. |
| 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 destino. Os clientes recebem notificações quando o recurso atinge o estado que corresponde à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, 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/beta/). 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",
"notificationContentType": "String",
"notificationQueryOptions": "String",
"notificationUrl": "String",
"notificationUrlAppId": "String",
"resource": "String"
}
Comentários
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, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de