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
As aplicações existentes que utilizam esta funcionalidade com baseTask ou baseTaskList devem ser atualizadas, uma vez que o conjunto de API a fazer incorporado nestes recursos é preterido a partir de 31 de maio de 2022. Esse conjunto de API deixará de retornar dados em 31 de agosto de 2022. Utilize o conjunto de API criado no todoTask.
Representa uma subscrição que permite que uma aplicação cliente receba notificações de alteração sobre alterações a dados no Microsoft Graph.
Para obter mais informações sobre subscrições e notificações de alteração, incluindo recursos que suportam notificações de alteração, veja Configurar notificações para alterações nos dados de recursos.
Métodos
| Método | Tipo de retorno | Descrição |
|---|---|---|
| List | subscription | Listar subscrições ativas. |
| Create | subscription | Subscreva uma aplicação de serviço de escuta para receber notificações de alteração quando os dados do Microsoft Graph forem alterados. Quando uma susbcription é criada e valdiada com êxito, o Microsoft Graph envia à aplicação, pelo menos, um objeto changeNotificationCollection sempre que existir uma alteração no recurso subscrito. |
| Get | subscription | Ler propriedades e relações do objeto de subscrição. |
| Atualizar | subscription | Renove uma subscrição ao atualizar o tempo de expiração. |
| Delete | Nenhum | Eliminar um objeto de subscrição. |
| Reautorizar | Nenhum | Reautorizar uma subscrição quando receber um desafio reautorização Obrigatório . |
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 subscrito 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. Utilize updated para receber notificações quando o utilizador ou grupo é criado, atualizado ou eliminado de forma recuperável. Utilize deleted para receber notificações quando o utilizador ou grupo é eliminado 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 ao comparar o valor da propriedade clientState enviada com a subscrição 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 a aplicação utilizou permissões delegadas para criar a subscrição, este campo contém o ID do utilizador com sessão iniciada que a aplicação chamou em nome de. Se a aplicação utilizou permissões de aplicação, este campo contém o ID do principal de serviço correspondente à aplicação. 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 período máximo de tempo de subscrição suportado, veja Duração da subscrição. |
| 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 subscritores cujo ponto final de notificação suporta uma versão inferior à versão atualmente recomendada (TLS 1.2), especificar esta propriedade por um conjunto linha do tempo permite-lhes utilizar temporariamente a 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 subscritores cujo ponto final de notificação já suporta o TLS 1.2, a definição desta 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. O URL do ponto final que recebe notificações de ciclo de vida, incluindo subscriptionRemoved, reauthorizationRequirede missed notificações. Esta URL deve fazer uso do protocolo HTTPS. Para obter mais informações, veja Reduzir subscrições em falta 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 para o recurso de destino. Os clientes recebem notificações quando o recurso atinge o estado correspondente às opções de consulta fornecidas aqui. Com esta nova propriedade no payload de criação da subscrição juntamente com todas as propriedades existentes, os Webhooks entregam notificações sempre que um recurso atinge o estado pretendido 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. Suportado apenas para o Serviço de Impressão Universal. Para obter mais informações, consulte Subscrever a alteração de notificações de APIs de impressão na nuvem com o Microsoft Graph. |
| notificationUrl | Cadeia de caracteres | Obrigatório. O URL do ponto final que recebe as notificações de alteração. Esta URL deve fazer uso do protocolo HTTPS. Qualquer parâmetro de cadeia de consulta incluído na propriedade notificationUrl é incluído no pedido 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 ao cliente validar a autenticidade da notificação recebida. |
| recurso | Cadeia de caracteres | Obrigatório. Especifica o recurso que é monitorizado para alterações. Não inclua o 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. As aplicações têm de renovar as subscrições antes da expiração; caso contrário, têm de criar uma nova subscrição. Os aplicativos também podem cancelar a assinatura a qualquer momento para deixarem de receber notificações de alteração.
A tabela seguinte mostra os tempos máximos de expiração das subscrições por recurso no Microsoft Graph.
| Resource | Tempo de expiração máximo |
|---|---|
| Alerta de segurança | 43 200 minutos (menos de 30 dias) |
| Aprovações do Teams | 43 200 minutos (menos de 30 dias) |
| Teams callRecord | 4.230 minutos (menos de três dias) |
| Chamada do TeamsRegisto | 4.320 minutos (três dias) |
| Chamada do TeamsTranscript | 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) |
| Oferta de Turnos do TeamsShiftRequest | 360 minutos (6 horas) |
| Turnos do Teams openShiftChangeRequest | 360 minutos (6 horas) |
| Turnos do Teams | 360 minutos (6 horas) |
| Teams Shifts swapShiftsChangeRequest | 360 minutos (6 horas) |
| Teams Shifts timeOffRequest | 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) |
| 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 este recurso só estão disponíveis no ponto final global e não nas clouds nacionais. |
| 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 |
|---|---|---|
| alerta1 | Menos de 3 minutos | 5 minutos |
| aprovações | Menos de 10 segundos | 40 segundos |
| 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 |
| 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 após a criação do alerta. Não inclui o tempo que uma regra demora a criar um alerta a partir dos dados.
Relações
Nenhum
Representação JSON
A representação JSON seguinte 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"
}