Assine para alterar notificações de APIs de impressão na nuvem usando o Microsoft Graph

  • Artigo

A Impressão Universal ajuda os clientes a mover a infraestrutura de impressão para a nuvem, e faz parte de um ecossistema robusto de soluções de parceiros que oferecem funcionalidade de impressão avançada. Essas soluções podem se tornar ainda mais poderosas quando você usa as APIs de impressão na nuvem do Microsoft Graph para integração com a Impressão Universal.

Muitas soluções parceiras precisam processar trabalhos de impressão em tempo real à medida que são enviados dos dispositivos dos usuários para as impressoras, o que significa que eles precisam ser notificados quando os trabalhos de impressão estiverem disponíveis para processamento. A Impressão Universal fornece ganchos para que as soluções de fornecedores de impressão sejam notificadas conforme as tarefas se movem pela nuvem, e APIs que permitem o gerenciamento de impressoras e trabalhos de impressão.

Este artigo descreve como assinar notificações para vários eventos de trabalho de impressão.

Obtenha notificações de alterações

Antes de aproveitar as notificações de alteração por meio do Microsoft Graph, você deve registrar seu aplicativo no Azure e provisionar seu aplicativo nos clientes Microsoft Entra locatário. Certifique-se de que o aplicativo tenha os escopos de permissão necessários habilitados, conforme descrito mais adiante neste artigo.

Notificações e assinaturas

A Impressão Universal atualmente oferece suporte a notificações para dois cenários relacionados a trabalhos de impressão:

  • PrintTask é acionado (JobStarted): um aplicativo pode se inscrever para receber notificações quando o printTask(gancho) é acionado. Para obter detalhes sobre como acionar uma tarefa, consulte Habilitar impressão segura. Atualmente, um printTask pode ser acionado apenas para um evento JobStarted. Um evento JobStarted é gerado quando um trabalho de impressão é criado com sucesso, seu conteúdo é carregado e o processamento de trabalho é iniciado.

  • Jobfetchable: após o início do trabalho, aplicativos de impressão de terceiros ou a Impressão Universal podem fazer algum processamento (como converter o conteúdo XPS em PDF para uma impressora PDF). Depois que o processamento for concluído e a conteúdo estiver pronto para ser baixado por uma impressora, um evento JobFetchable é gerado para o trabalho de impressão correspondente.

Observação

Para ouvir as notificações de alteração do evento Jobfetchable, não é necessário um recurso printTaskDefinition.

O aplicativo deve lidar com notificações duplicadas.

Crie um aplicativo para ouvir as notificações

Para obter informações sobre como escutar notificações do Microsoft Graph, consulte Configurar notificações para alterações nos dados do usuário – Exemplos de código.

Escopos de permissão

Para assinar notificações para trabalhos de impressão, os aplicativos devem ter os seguintes escopos de permissão aprovados no locatário Microsoft Entra do cliente:

Os aplicativos devem gerar e usar o token de segurança Microsoft Entra no cabeçalho de solicitação do Microsoft API do Graph. O token de segurança contém as declarações de acordo com os escopos aprovados para o locatário Microsoft Entra do cliente pelo administrador.

Criar assinatura: evento printTask acionado (JobStarted)

Alguns aplicativos monitoram as filas de impressão em busca de trabalhos recebidos e para serem notificados assim que houver um trabalho válido na fila. Após serem notificados, eles podem coletar os metadados relevantes do trabalho ou até mesmo realizar modificações no trabalho de impressão – incluindo abortar o trabalho ou redirecionar o trabalho da fila de impressão atual para outra fila após modificar os atributos do trabalho corretamente.

Antes de criar uma notificação para um evento printTask-acionado, certifique-se de que o aplicativo criou o seguinte:

  • Um printTaskDefinition para o locatário Microsoft Entra do cliente. Uma única definição de tarefa pode ser associada a uma ou mais impressoras no mesmo locatário Microsoft Entra.

  • Um printTaskTrigger de cada uma das filas de impressão para as quais o parceiro quer receber uma notificação quando um novo trabalho de impressão for iniciado. O printTaskTrigger precisa ser vinculado ao printTaskDefinition.

Observação

Uma impressora pode ser associada a apenas um printTaskTrigger e um printTaskTrigger pode ser associado a apenas um printTaskDefinition. No entanto, um printTaskDefinition pode ter um ou mais printTaskTriggers associados a ele.

Com o printTaskDefinition que existe para o locatário Microsoft Entra do cliente, o aplicativo pode criar uma assinatura para um evento printTask disparado (JobStarted) usando o printTaskDefinition. Ao criar a assinatura:

  • O campo resource precisa ser definido como print/taskDefinitions/{printTaskDefinition ID}/tasks.
  • O campo changeType precisa ser definido como created.
  • O campo expirationDateTime precisa ser menor que o tempo máximo de expiração.

Para obter mais detalhes, confira Propriedades do tipo de recurso da assinatura..

Solicitação

O exemplo a seguir mostra uma solicitação.

POST https://graph.microsoft.com/v1.0/subscriptions 
Content-Type: application/json
{ 
    "changeType":"created", 
    "resource":"print/taskDefinitions/{printTaskDefinition ID}/tasks", 
    "clientState":"secret", 
    "notificationUrl":"{URL for receiving the event – e.g. https://webhookappexample.azurewebsites.net/api/notifications}", 
    "expirationDateTime":"2020-01-30T22:42:09Z" 
}

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 201 Created
Content-Type: application/json
{ 
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity", 
    "id": "{Subscription ID}", 
    "resource": "print/taskDefinitions/{printTaskDefinition ID}/tasks", 
    "applicationId": "{application ID}", 
    "changeType": "created", 
    "clientState": "secret", 
    "notificationUrl": "{URL for receiving the event – e.g. https://webhookappexample.azurewebsites.net/api/notifications}", 
    "notificationQueryOptions": null, 
    "lifecycleNotificationUrl": null, 
    "expirationDateTime": "2020-12-30T22:42:09Z", 
    "creatorId": "{Creator ID}", 
    "includeResourceData": null, 
    "latestSupportedTlsVersion": "v1_2", 
    "encryptionCertificate": null, 
    "encryptionCertificateId": null 
}

Criar assinatura: evento JobFetchable

Alguns aplicativos de nuvem precisam baixar os trabalhos de impressão da Impressão Universal quando estiverem prontos. Como esses aplicativos em execução na nuvem não estão protegidos pelo firewall do cliente, eles podem usar as notificações de alteração do Microsoft Graph para serem notificados quando um trabalho de impressão estiver pronto para ser baixado.

Observação

Trabalhos de impressão não podem ser modificados quando entram no estado JobFetchable. Uma notificação JobFetchable precisa ser criada para cada fila da impressora. Ao criar a assinatura:

  • O campo resource precisa ser definido como 'print/printers/{printer id}/jobs'.
  • O campo changeType precisa ser definido como updated.
  • O campo notificationQueryOptions precisa ser definido como $filter = isFetchable eq true.
  • O campo expirationDateTime precisa ser menor que o tempo máximo de expiração.

Para obter mais detalhes, confira Propriedades do tipo de recurso da assinatura..

Solicitação

O exemplo a seguir mostra uma solicitação.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json
{
    "changeType":"updated",
    "resource":"print/printers/{printer id}/jobs",
    "notificationQueryOptions": "$filter = isFetchable eq true", 
    "notificationUrl":"{URL for receiving the event – e.g. https://webhookappexample.azurewebsites.net/api/notifications}",
    "expirationDateTime":"2020-12-30T22:42:09Z",
    "clientState":"mysecret"
}

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 201 Created
Content-Type: application/json
{ 
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity", 
    "id": "{Subscription ID}", 
    "resource": "print/printers/{printer ID}/jobs", 
    "applicationId": "{Application ID}", 
    "changeType": "updated", 
    "clientState": "mysecret", 
    "notificationUrl": "{URL for receiving the event – e.g. https://webhookappexample.azurewebsites.net/api/notifications}", 
    "notificationQueryOptions": "$filter = isFetchable eq true", 
    "lifecycleNotificationUrl": null, 
    "expirationDateTime": "2020-12-30T22:42:09Z", 
    "creatorId": "{Creator ID}", 
    "includeResourceData": null, 
    "latestSupportedTlsVersion": "v1_2", 
    "encryptionCertificate": null, 
    "encryptionCertificateId": null
}

Renovar uma assinatura de notificação

O Microsoft Graph tem um limite de tempo de expiração. Para obter detalhes, confira tempo máximo de expiração. Para continuar recebendo notificações, é necessário que a assinatura seja renovada periodicamente, usando a API de atualização da assinatura.

Obter ou excluir assinaturas de notificação

Os aplicativos podem obter detalhes da assinatura ou excluir uma assinatura quando necessário. Para obter detalhes, confira Usar a API do Microsoft Graph para receber notificações de alteração.

Perguntas frequentes

Como o Microsoft Graph valida as URLs de notificação?

O Microsoft Graph valida o ponto de extremidade da notificação fornecido na propriedade notificationUrl da solicitação da assinatura antes de criá-la. Para obter detalhes, confira Validação do ponto de extremidade da notificação.

O que os aplicativos devem fazer após receber uma notificação de alteração?

Os aplicativos devem processar e reconhecer todas as notificações de alteração recebidas. Para obter detalhes, confira Processando a notificação de alteração.

Como posso validar a autenticidade das notificações?

A autenticidade das notificações pode ser validada usando o valor clientState conforme descrito em Processando a notificação de alteração ou validando tokens na notificação de alteração .

Como posso obter uma lista de assinaturas ativas?

Para obter detalhes sobre como recuperar uma lista de assinaturas de webhook, confira Listar assinaturas.

Conteúdo relacionado