Compartilhar via

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

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 poder tirar partido das notificações de alteração através do Microsoft Graph, tem de registar a sua aplicação no Azure e aprovisionar a sua aplicação nos clientes Microsoft Entra inquilino. 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 utilizador – Exemplos de Código.

Escopos de permissão

Para subscrever notificações para tarefas de impressão, as aplicações têm de ter os seguintes âmbitos de permissão aprovados no inquilino Microsoft Entra do cliente:

As aplicações têm de gerar e utilizar o token de segurança Microsoft Entra no cabeçalho do pedido do Microsoft API do Graph. O token de segurança contém as afirmações de acordo com os âmbitos aprovados para o inquilino Microsoft Entra do cliente pelo respetivo 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:

  • Uma printTaskDefinition para o inquilino Microsoft Entra do cliente. Uma definição de tarefa única pode ser associada a uma ou mais impressoras no mesmo inquilino 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 a printTaskDefinition que existe para o inquilino Microsoft Entra do cliente, a aplicação pode criar uma subscrição para um evento printTask acionado (JobStarted) com 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

  • Last updated on