Registro de impressora de impressão universal (UP)
1. Inscrição
1.1 Fluxo
1.2 APIs
As APIs a seguir estão disponíveis com o Serviço de Registro Global UP para registrar impressoras.
URL da Base de Serviço de Registro Global UP: https://register.print.microsoft.com
O URL completo será a combinação do URL base global e dos endpoints abaixo.
1.2.1 /registrar
O ponto de extremidade /register é usado para registrar uma impressora. Existem 2 etapas para inscrição.
Chamada de registro inicial para registrar a impressora
Status de registro de sondagem para conclusão da solicitação de registro
1.2.1.1 Iniciando o registro
A primeira etapa é iniciar uma solicitação de registro com o serviço de registro global. Isso é feito emitindo uma solicitação POST para o ponto de extremidade /register com a carga de registro no formato JSON.
1.2.1.1.1 Solicitação HTTP
POST /api/{version}/register
{version} é a versão da API/protocolo de registro UP que a impressora está usando.
As versões atualmente suportadas são:
- v1.0
1.2.1.1.2 Cabeçalhos de solicitação
Para a v1.0:
| Nome | Descrição |
|---|---|
| Autorização | Portador {token} Obrigatório. A impressora deve conectar o administrador à ID do Microsoft Entra, seguindo o fluxo Código do dispositivo ou outro fluxo de autorização. |
1.2.1.1.3 Tipo de conteúdo da solicitação
application/json
1.2.1.1.4 Carga útil da solicitação
A carga da solicitação de registro estará no formato JSON com os seguintes valores (diferencia maiúsculas de minúsculas):
| Nome do valor | Tipo de Valor | Descrição | Obrigatório |
|---|---|---|---|
| name | string | O nome amigável da impressora. | Sim |
| fabricante | string | O fabricante da impressora. | Sim |
| modelo | string | O modelo da impressora. | Sim |
| device_id | string | O UUID do dispositivo físico da impressora. | Sim |
| device_type | string | O tipo do dispositivo. Valores suportados (sem aspas): "impressora" | Sim |
| certificate_request | Objeto DeviceCertRequest | A Solicitação de Assinatura de Certificado (CSR) X.509 para o certificado criado e usado pela impressora para se identificar. Consulte o Apêndice A.1 para obter um exemplo de codificação sobre como criar um CSR com a biblioteca .NET BouncyCastle. | Sim |
O objeto DeviceCertRequest tem os seguintes valores (diferencia maiúsculas de minúsculas):
| Nome do valor | Tipo de Valor | Descrição | Obrigatório |
|---|---|---|---|
| tipo | string | Uma propriedade que DEVE conter "pkcs10". | Sim |
| data | string | Uma propriedade que contém uma solicitação de certificado PKCS#10 codificada em base64 RFC4211. A solicitação de certificado DEVE usar um algoritmo de chave pública RSA com uma chave de 2048 bits, um algoritmo de assinatura SHA256WithRSAEncryption e um algoritmo de hash SHA256. | Sim |
| transport_key | string | A parte pública codificada em base64 de uma chave assimétrica gerada pelo cliente. | Sim |
1.2.1.1.5 Resposta bem-sucedida
Em caso de sucesso (202 Aceito), o conteúdo da resposta de registro estará no formato JSON com os seguintes valores (diferencia maiúsculas de minúsculas):
| Nome do valor | Tipo de Valor | Descrição | Obrigatório |
|---|---|---|---|
| registration_id | string | A ID exclusiva que representa essa solicitação de registro. Isso será usado ao pesquisar o status do registro. | Sim |
| intervalo | Número inteiro | Tempo de intervalo de sondagem (em segundos) para verificar a conclusão da solicitação de registro. | Sim |
1.2.1.1.6 Resposta de erro
Em caso de erro, os seguintes códigos de status HTTP serão retornados junto com uma carga de resposta de erro. A carga de resposta de erro conterá um objeto JSON de erro seguindo o formato na seção 2.
Códigos de status HTTP
| Código de Status HTTP | Descrição |
|---|---|
| 400 (Solicitação inválida) | A solicitação é inválida ou malformada. Consulte payload de resposta de erro para obter detalhes. Corrija e reenvie a solicitação. |
| 500 (Erro interno do servidor) | Ocorreu um erro interno no serviço. Consulte payload de resposta de erro para obter detalhes. Repita a solicitação (se possível, retry_timeout será definido). |
Códigos de Erro
| Códigos de erro | Descrição | Código de Status HTTP |
|---|---|---|
| invalid_request | A carga útil da solicitação de registro estava malformada/inválida. Isso geralmente ocorre durante os estágios de desenvolvimento. Consulte error_description para obter mais detalhes. | 400 |
| device_code_error | O serviço não pôde gerar um par de Dispositivo/Código de Usuário. | 500 |
| storage_error | O serviço apresentou um erro com o armazenamento de back-end. | 500 |
| service_error | Ocorreu um erro no serviço. Consulte error_description para obter mais detalhes. | 500 |
1.2.1.1.7 Exemplos
1.2.1.1.7.5 Solicitação v1.0
POST https://register.print.microsoft.com/api/v1.0/register HTTP/1.1
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
Accept-Encoding: gzip, deflate
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkZ6U3pHTVZ1a0U2Nm9EQnpwR0JUY2NBMlVRYyIsImtpZCI6IkZ6U3pHTVZ1a0U2Nm9EQnpwR0JUY2NBMlVRYyJ9.eyJhdWQiOiJodHRwczovL3ByaW50LnByaW50LXBwZS5taWNyb3NvZnQuY29tIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy1wcGUubmV0LzIwZGY5NTlmLWE0OTItNGU3NC05N2E3LTE0YWJiM2ZlZjFkYi8iLCJpYXQiOjE1NjE2NzUxNjYsIm5iZiI6MTU2MTY3NTE2NiwiZXhwIjoxNTYxNjc5MDY2LCJhY3IiOiIxIiwiYWlvIjoiNDJOZ1lOQXNYbUtTSHZSM3Jvcjd2RVdMMWtmc0NMUi93R085cjYzMGl2T1RLWlVoV1ZzQSIsImFtciI6WyJwd2QiXSwiYXBwaWQiOiI0MTdhZTZlYi1hYWM4LTQyYzgtOTAwYy0wZTUwZGViYmE2ODgiLCJhcHBpZGFjciI6IjAiLCJmYW1pbHlfbmFtZSI6IlN0YWdlciIsImdpdmVuX25hbWUiOiJNYWRlbGluZSIsImdyb3VwcyI6WyI1YjljNGVkMS0yMWUyLTRkNzktYjE0Zi1mMzYyMTI5ODcyYjIiXSwiaXBhZGRyIjoiMTMxLjEwNy4xNTkuMjAiLCJuYW1lIjoiTWFkZWxpbmUgU3RhZ2VyIiwib2lkIjoiYzJmMjg2NDctMWQ4ZS00YTdhLWIzZjctZjU4YmQ3ODYxODk4IiwicHVpZCI6IjEwMDM0MDAwMDA2OEJFQzgiLCJzY3AiOiJzYW1wbGVzLnJlYWQgc2FtcGxlcy53cml0ZSIsInN1YiI6IlR6b2hRcmNzTHNjNUNHR09hWndxa1ZiajhaSkh4MnB1dzdpcWhWVXFWRGsiLCJ0ZW5hbnRfY3RyeSI6IlVTIiwidGlkIjoiMjBkZjk1OWYtYTQ5Mi00ZTc0LTk3YTctMTRhYmIzZmVmMWRiIiwidW5pcXVlX25hbWUiOiJtYXN0YWdlckBjbG91ZHByaW50cHBlLmNjc2N0cC5uZXQiLCJ1cG4iOiJtYXN0YWdlckBjbG91ZHByaW50cHBlLmNjc2N0cC5uZXQiLCJ1dGkiOiJlal84QlAtLW1rZWNNWjdncFJNR0FBIiwidmVyIjoiMS4wIiwid2lkcyI6WyI2MmU5MDM5NC02OWY1LTQyMzctOTE5MC0wMTIxNzcxNDVlMTAiXX0.e1RpyZDQzqlV11uyRXWRmaqf6wk2mg763muoIiMG2Qq8DW221Rg91cLP5px6KSfhpd7nv-Ln_KUFsZ4IlJqfmsrfCL_vgKHjYQuRDv2BY8-vrIqUC_5XVA_sj2Ib7iT7SjDYyMv6QDZM2rf7kVggvRuaZihUxxGZWby84EXD8KKAYfAQGo3r6AceuSDJOvToMy-Kp-MEqRuzExZdq2p1_qRIBtHe8Its4xuR8ZHEVqWnY0Y_qeVA8uxl3mQxZSvH8BVYn4Bdy_VZcNtrNKt3YpHFzG4kgy5V6wGLecRI7IBzYd4uK_FwpaYXHpkrSbO0ATEX3tjrgPnHbicA053Ilw
Content-Length: 1600
{
"name": "Test Printer",
"manufacturer": "Test Manufacturer",
"model": "Test Model",
"device_type": "printer",
"device_id": "a188d9e8-8daa-44c9-862b-d6202bcf1b68",
"certificate_request":
{
"type": "pkcs10",
"data": "MIICpDCCAYwCAQAwYTELMAkGA1UEBhMCVVMxEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1JlZG1vbmQxFzAVBgNVBAoMDk1pY3Jvc29mdCBDb3JwMRIwEAYDVQQDDAlNaWNyb3NvZnQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDJ1xUdFKBlFdS9dHqSrD7YS0ZJ6MgcYy5wI3P0wOWrDi28OCBLbt6HBg02KDh1MlmVrfIR2O6WWeJ59M63JuwEn2e2WoGnIb/M6NyANyBBmgZ3bjp39UJHbXtYYXm/VJrPcOLM09dST7KR1zAcD2J+rnK8ZVUtYuTl58D7R6zsrYshw5CwxfLYPXeXwiSoKhtEC8Xn1lz3mi5B2SdsFHdjaQb6E0tCG5zdrVzzhCEVPaoo4e9SCTB9jDNulTU1ZkHzGBk+UzlKv4APsclyGCTEgA01T6/ueBrVeKY9d4DYfz/pu4sm0Vf1E+2hggtwbBOP60sFtkfnKiwtVoDF1KC9AgMBAAEwDQYJKoZIhvcNAQELBQADggEBACdggPBJ5MoJJ3QjVYDypuJGWDVWBT0G4pXNZHNz5Q4OVDze7aCw3Sl78Qdzy++XsrSXjtyZyEb+A5R36YKTpzRBCHSOWyZkZKpxj0Uo8/+RzjzJ1uvtwfhelfQ6EVktFsz6a2hixcaa47bN/bjj9stJbbRsxjJwR1K5YI/i+9DaUE7r7VDXiknQ7/ZyEYquAqY/O/LEnFOGhkSvkLlFPTbnJ7fzURyNnQhmp8p3DMj5dXYgKfWPxViqvJChx8pJf9zM4TjzaTZIj08tSOp2LtWGeMNkFgYJH4URe3t4OPx5crkKj8i5aIW1Ulb8ezJLW1IU7W8hF71ooZWFTOsAnjQ=",
"transport_key":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAydcVHRSgZRXUvXR6kqw+2EtGSejIHGMucCNz9MDlqw4tvDggS27ehwYNNig4dTJZla3yEdjullniefTOtybsBJ9ntlqBpyG/zOjcgDcgQZoGd246d/VCR217WGF5v1Saz3DizNPXUk+ykdcwHA9ifq5yvGVVLWLk5efA+0es7K2LIcOQsMXy2D13l8IkqCobRAvF59Zc95ouQdknbBR3Y2kG+hNLQhuc3a1c84QhFT2qKOHvUgkwfYwzbpU1NWZB8xgZPlM5Sr+AD7HJchgkxIANNU+v7nga1XimPXeA2H8/6buLJtFX9RPtoYILcGwTj+tLBbZH5yosLVaAxdSgvQIDAQAB"
}
}
1.2.1.1.7.6 Resposta v1.0
HTTP/1.1 202 Accepted
Date: Thu, 27 Jun 2019 22:47:34 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
{
"registration_id": "fbbd6371-7e88-4881-8818-8d2ea2e8fe88",
"interval": 5
}
1.2.1.2 Obtendo o status do registro
Depois que a solicitação de registro for aceita com êxito, a impressora sondará o /register endpoint para o status da solicitação de registro. A impressora deve pesquisar com base no valor de intervalo recebido na resposta de registro e deve fornecer o registration_id recebido.
1.2.1.2.1 Solicitação HTTP
GET /api/{version}/register?{Query Parameters}
{version} é a versão da API/protocolo de registro UP que a impressora está usando.
As versões atualmente suportadas são:
- v1.0
{Query Parameters} são especificados na próxima seção.
1.2.1.2.2 Cabeçalhos de solicitação
Para a v1.0:
| Nome | Descrição |
|---|---|
| Autorização | Portador {token} Obrigatório. A impressora deve conectar o administrador à ID do Microsoft Entra ou seguir o fluxo Código do dispositivo. O mesmo token adquirido para a primeira solicitação de registro pode ser usado. |
1.2.1.2.3 Parâmetros de consulta de solicitação
| Nome do Parâmetro | Descrição | Obrigatório |
|---|---|---|
| registration_id | A ID de registro recebida da resposta da solicitação de registro. | Sim |
1.2.1.2.4 Respostas bem-sucedidas
Os seguintes códigos de status HTTP serão retornados para os seguintes cenários de "sucesso":
| Código de Status HTTP | Fase de Registro |
|---|---|
| 200 (OK) | Registro completo |
| 202 (Aceito) | Registro em andamento - Faça outra solicitação após o intervalo |
Cargas de resposta
Inscrições em andamento (202 aceitas):
A carga de resposta de registro estará no formato JSON com os seguintes valores (diferencia maiúsculas de minúsculas):
| Nome do valor | Tipo de Valor | Descrição | Obrigatório |
|---|---|---|---|
| intervalo | Número inteiro | Tempo de intervalo de sondagem (em segundos) para verificar a conclusão da solicitação de registro. Observe que o tempo do intervalo de sondagem não será necessariamente o mesmo todas as vezes. | Sim |
Registro completo (200 OK):
A carga de resposta de registro estará no formato JSON com os seguintes valores (diferencia maiúsculas de minúsculas):
| Nome do valor | Tipo de Valor | Descrição | Obrigatório |
|---|---|---|---|
| cloud_device_id | string | O UUID da impressora na nuvem que essa impressora representa. | Sim |
| certificate | string | Certificado X.509 assinado codificado em Base64. | Sim |
| print_svc_url | string | A URL para o serviço de Impressão Universal (UP) que lida com as operações da impressora. | Sim |
| notification_url | string | O URL que deve ser usado pela impressora para escutar notificações (novo trabalho de impressão, cancelar trabalho de impressão, etc...). | Sim |
| mcp_svc_resource_id | string | A ID do recurso do serviço UP. Necessário ao solicitar o token OAuth para comunicação com o UP e os Serviços de Notificação UP. | Sim |
| device_token_url | string | A URL da STA (Secure Token Authority) que a impressora deve usar para obter tokens para os Serviços de Notificação UP e UP. | Sim |
1.2.1.2.5 Resposta de erro
Em caso de erro, os seguintes códigos de status HTTP serão retornados junto com uma carga de resposta de erro. A carga de resposta de erro conterá um objeto JSON de erro seguindo o formato na seção 2.
Códigos de status HTTP
| Código de Status HTTP | Descrição |
|---|---|
| 400 (Solicitação inválida) | A solicitação é inválida ou malformada. Consulte payload de resposta de erro para obter detalhes. O registro deve ser reiniciado. |
| 500 (Erro interno do servidor) | Ocorreu um erro interno no serviço. Consulte payload de resposta de erro para obter detalhes. O registro deve ser reiniciado. |
Códigos de Erro
| Códigos de erro | Descrição | Código de Status HTTP |
|---|---|---|
| invalid_registration_id | A ID de registro fornecida é inválida. Isso pode ocorrer se a ID de registro tiver sido armazenada incorretamente ou se o registro da impressora não tiver sido concluído dentro do tempo limite de registro. O registro deve ser reiniciado. | 400 |
| device_already_exists | O dispositivo que está sendo registrado já está registrado. O administrador deve verificar o portal UP para ver se o dispositivo que está sendo registrado está presente. Se for, pode ser uma entrada obsoleta que o administrador esqueceu de excluir / cancelar o registro. O registro deve ser reiniciado. | 400 |
| user_token_error | O serviço falhou ao obter o token do usuário para executar o registro. O registro deve ser reiniciado. | 500 |
| storage_error | O serviço apresentou um erro com o armazenamento de back-end. O registro deve ser reiniciado. | 500 |
| service_error | Ocorreu um erro no serviço. Consulte error_description para obter mais detalhes. O registro deve ser reiniciado. | 500 |
1.2.1.2.6 Exemplos
1.2.1.2.6.3 Solicitação v1.0
GET https://register.print.microsoft.com/api/v1.0/register?registration_id=bb86db79-2918-
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkZ6U3pHTVZ1a0U2Nm9EQnpwR0JUY2NBMlVRYyIsImtpZCI6IkZ6U3pHTVZ1a0U2Nm9EQnpwR0JUY2NBMlVRYyJ9.eyJhdWQiOiJodHRwczovL3ByaW50LnByaW50LXBwZS5taWNyb3NvZnQuY29tIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy1wcGUubmV0LzIwZGY5NTlmLWE0OTItNGU3NC05N2E3LTE0YWJiM2ZlZjFkYi8iLCJpYXQiOjE1NjE2NzUxNjYsIm5iZiI6MTU2MTY3NTE2NiwiZXhwIjoxNTYxNjc5MDY2LCJhY3IiOiIxIiwiYWlvIjoiNDJOZ1lOQXNYbUtTSHZSM3Jvcjd2RVdMMWtmc0NMUi93R085cjYzMGl2T1RLWlVoV1ZzQSIsImFtciI6WyJwd2QiXSwiYXBwaWQiOiI0MTdhZTZlYi1hYWM4LTQyYzgtOTAwYy0wZTUwZGViYmE2ODgiLCJhcHBpZGFjciI6IjAiLCJmYW1pbHlfbmFtZSI6IlN0YWdlciIsImdpdmVuX25hbWUiOiJNYWRlbGluZSIsImdyb3VwcyI6WyI1YjljNGVkMS0yMWUyLTRkNzktYjE0Zi1mMzYyMTI5ODcyYjIiXSwiaXBhZGRyIjoiMTMxLjEwNy4xNTkuMjAiLCJuYW1lIjoiTWFkZWxpbmUgU3RhZ2VyIiwib2lkIjoiYzJmMjg2NDctMWQ4ZS00YTdhLWIzZjctZjU4YmQ3ODYxODk4IiwicHVpZCI6IjEwMDM0MDAwMDA2OEJFQzgiLCJzY3AiOiJzYW1wbGVzLnJlYWQgc2FtcGxlcy53cml0ZSIsInN1YiI6IlR6b2hRcmNzTHNjNUNHR09hWndxa1ZiajhaSkh4MnB1dzdpcWhWVXFWRGsiLCJ0ZW5hbnRfY3RyeSI6IlVTIiwidGlkIjoiMjBkZjk1OWYtYTQ5Mi00ZTc0LTk3YTctMTRhYmIzZmVmMWRiIiwidW5pcXVlX25hbWUiOiJtYXN0YWdlckBjbG91ZHByaW50cHBlLmNjc2N0cC5uZXQiLCJ1cG4iOiJtYXN0YWdlckBjbG91ZHByaW50cHBlLmNjc2N0cC5uZXQiLCJ1dGkiOiJlal84QlAtLW1rZWNNWjdncFJNR0FBIiwidmVyIjoiMS4wIiwid2lkcyI6WyI2MmU5MDM5NC02OWY1LTQyMzctOTE5MC0wMTIxNzcxNDVlMTAiXX0.e1RpyZDQzqlV11uyRXWRmaqf6wk2mg763muoIiMG2Qq8DW221Rg91cLP5px6KSfhpd7nv-Ln_KUFsZ4IlJqfmsrfCL_vgKHjYQuRDv2BY8-vrIqUC_5XVA_sj2Ib7iT7SjDYyMv6QDZM2rf7kVggvRuaZihUxxGZWby84EXD8KKAYfAQGo3r6AceuSDJOvToMy-Kp-MEqRuzExZdq2p1_qRIBtHe8Its4xuR8ZHEVqWnY0Y_qeVA8uxl3mQxZSvH8BVYn4Bdy_VZcNtrNKt3YpHFzG4kgy5V6wGLecRI7IBzYd4uK_FwpaYXHpkrSbO0ATEX3tjrgPnHbicA053Ilw
Host: register.print.microsoft.com
1.2.1.2.6.4 Resposta em andamento v1.0
HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache
{
"interval": 15
}
1.2.1.2.6.7 Resposta concluída v1.0
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 267
Content-Type: application/json; charset=utf-8
{
"cloud_device_id": "7c907b43-d8f0-4e42-a279-1e37eb4fd2bf",
"certificate": "MIID8jCCAtqgAwIBAgIQR2Y15zkurJhCGxcaQ0d7tjANBgkqhkiG9w0BAQsFADB4MXYwEQYKCZImiZPyLGQBGRYDbmV0MBUGCgmSJomT8ixkARkWB3dpbmRvd3MwHQYDVQQDExZNUy1Pcmdhbml6YXRpb24tQWNjZXNzMCsGA1UECxMkODJkYmFjYTQtM2U4MS00NmNhLTljNzMtMDk1MGMxZWFjYTk3MB4XDTE4MDExOTAwNTIxM1oXDTI4MDExOTAxMjIxM1owLzEtMCsGA1UEAxMkZjVlYjVmNWUtMDYyNC00YTNiLThmZjItNjQ5ZTAyM2ZiNzJkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApQc0Twp+vlT5Vc74zLoXbrufcIKnoW980OWFKHf7lRlRqjj9MWpea99j+3K8JQSoifXJvS5QzyjXrH9phsrfX84I258y6dM/aUadLYYKjO38wx9c1vQppZi1P3LcDaJiXPgNQ8omWCtDNoVwQlTUmB9Pq6h+V6S4P59Mq9cem6yEE7pu4DLqLSB68jexvLQnuGDfn6PsVUC3ML21zDmAr3QDikiZDe9Iy03IRrXvl6obj5QZtkGFbK9ueArFcWpymsEK
FfVhrKL7ca/rAEFHsHacJYHkJNMw3Qzs0yMYZRsH/fS+eBebvQWUEujQ+BX8xZQX48ukwtC8R37RsqrLjwIDAQABo4HAMIG9MAwGA1UdEwEB/wQCMAAwFgYDVR0lAQH/BAwwCgYIKwYBBQUHAwIwIgYLKoZIhvcUAQWCHAIEEwSBEF5f6/UkBjtKj/JkngI/ty0wIgYLKoZIhvcUAQWCHAMEEwSBEHXH6W+38IhBoi1uqlWcNhUwIgYLKoZIhvcUAQWCHAUEEwSBEAWT1qlxl5pLvXhzFTIfL2swFAYLKoZIhvcUAQWCHAgEBQSBAk5BMBMGCyqGSIb3FAEFghwHBAQEgQEwMA0GCSqGSIb3DQEBCwUAA4IBAQCXpFMa9DCgIIJTD3RlEyPN8WB/HgMkhLBqwtZugkmIn8D80ckuhrfa2jJfWkNxEfFXanjq9B4tAvkNt7vBXiYw+PKj8+CE5FgfUTNtIw3Q/06tnJBj20mz28ZNbdRUgXzxXiY7oZss54dbHH+7TFO9k9Pm1CuUOzLFX4LeC48wo/S6uN7JDeID6pQjcR00eYJ+gcD800AXBYXrqSreYhdtl1swcD71qgshELAo2qXu0kzuKj05GIB5SXFOoU+KhuB0LMuEZF5rsQPN4KcasGaAb/8MIORAxkYStNLQZQLYbDve/dUownbfruW/o3tnjJP0GA0gY/Ohv5ssgrCFsiBq",
"print_svc_url": "https://print.print.microsoft.com/",
"notification_url": "https://notification.print.microsoft.com/",
"mcp_svc_resource_id":"https://print.print.microsoft.com",
"device_token_url": "https://login.microsoftonline.com/common/oauth2/token"
}
1.2.1.3 Autenticação
Antes de registrar a impressora deve autenticar o administrador no Microsoft Entra ID, seguindo o fluxo de Código do Dispositivo ou outro fluxo de autorização. O token de acesso de administrador da impressora obtido deve ser enviado no cabeçalho de autorização da solicitação para registrar uma impressora. A documentação do código do dispositivo e outros fluxos de autenticação compatíveis com a ID do Microsoft Entra pode ser encontrada em Fluxos de autenticação com suporte.
1.2.1.3.1 Parâmetros de fluxo de código de dispositivo
A documentação do suporte da ID do Microsoft Entra do fluxo de código do dispositivo pode ser encontrada em Fluxo de código do dispositivo OAuth 2.0. O listado client_id abaixo é temporário. Forneceremos informações adicionais em um futuro próximo.
| Nome do Parâmetro | Descrição | Obrigatório |
|---|---|---|
| locatário | Use "Organizações" para o parâmetro tenant. | Sim |
| client_id | Use registered client ID para o client_id. Informações adicionais em Registrando Cliente OEM. |
Sim |
| scope | Usar https://print.print.microsoft.com/.default para o escopo |
Sim |
1.2.1.3.2 Exemplo de solicitações de fluxo de código de dispositivo
1.2.1.3.2.1 Iniciar o fluxo de código do dispositivo
Solicitação:
POST https://login.microsoftonline.com/organizations/oauth2/v2.0/devicecode HTTP/1.1
Accept-Charset: utf-8
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: login.microsoftonline.com
Content-Length: 103
Expect: 100-continue
Connection: Keep-Alive
client_id=<registered_client_id>&scope=https%3A%2F%2Fprint.print.microsoft.com%2F.default
Resposta:
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 473
{
"user_code": "FMTB7B3WR",
"device_code": "FAQABAAEAAAAP0wLlqdLVToOpA4kwzSnx3SB1wjNptiBt5jFM8ePgJKGOjX-WOEksHYT3zgqz9VVg4MqY8J6Tej_rpniyj4WjOsVe-RCJuGexX-IwPKDK-df38P0zpLv5ktxSCflT_F-8Cbef6BRDpk0Qm-lPOhC4bcbtdIaM8yqf-cS962rGC9VdVNFVFStePppCDRcumjAgAA",
"verification_uri": "https://microsoft.com/devicelogin",
"expires_in": 900,
"interval": 5,
"message": "To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code FMTB7B3WR to authenticate."
}
1.2.1.3.2.2 Recuperando o token do usuário
Solicitação:
POST https://login.microsoftonline.com/tenant/oauth2/v2.0/token HTTP/1.1
Accept-Charset: utf-8
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: login.microsoftonline.com
Content-Length: 289
Expect: 100-continue
grant_type=device_code&client_id=<registered_client_id>&device_code=FAQABAAEAAAAP0wLlqdLVToOpA4kwzSnx3SB1wjNptiBt5jFM8ePgJKGOjX-WOEksHYT3zgqz9VVg4MqY8J6Tej_rpniyj4WjOsVe-RCJuGexX-IwPKDK-df38P0zpLv5ktxSCflT_F-8Cbef6BRDpk0Qm-lPOhC4bcbtdIaM8yqf-cS962rGC9VdVNFVFStePppCDRcumjAgAA
Resposta: authorization_pending, o usuário ainda não fez login.
HTTP/1.1 400 Bad Request
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 469
{
"error": "authorization_pending",
"error_description": "AADSTS70016: Pending end-user authorization.\r\nTrace ID: 60997c8b-15ed-4d12-99b6-6da879fd1400\r\nCorrelation ID: 7300aba9-1698-4a4e-b6dd-66459a828108\r\nTimestamp: 2019-09-26 23:13:43Z",
"error_codes": [70016],
"timestamp": "2019-09-26 23:13:43Z",
"trace_id": "60997c8b-15ed-4d12-99b6-6da879fd1400",
"correlation_id": "7300aba9-1698-4a4e-b6dd-66459a828108",
"error_uri": https://login.microsoftonline.com/error?code=70016
}
Resposta: success, o usuário fez login, o token é retornado. Esse token pode ser usado no cabeçalho de autorização necessário (descrito na seção 1.2.1.1.2) ao enviar uma solicitação para registrar uma impressora na Impressão Universal.
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 1763
{
"token_type": "Bearer",
"scope": "https://print.print.microsoft.com/Print.Device https://print.print.microsoft.com/.default",
"expires_in": 3599,
"ext_expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImFQY3R3X29kdlJPb0VOZzNWb09sSWgydGlFcyIsImtpZCI6ImFQY3R3X29kdlJPb0VOZzNWb09sSWgydGlFcyJ9.eyJhdWQiOiJodHRwczovL3ByaW50LnByaW50Lm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mMGQ4ODMyMy04OGY2LTQ4MTMtOGI0ZC05NGVjNjdlNjA3YmQvIiwiaWF0IjoxNTY5NTM5Mzc3LCJuYmYiOjE1Njk1MzkzNzcsImV4cCI6MTU2OTU0MzI3NywiYWNyIjoiMSIsImFpbyI6IkFTUUEyLzhNQUFBQVA1U1NzTklCYXRVQ2UxSGZXaEdvNHhqbUM4b2RCckNpeDNaN0dyZWJUMEE9IiwiYW1yIjpbInB3ZCJdLCJhcHBpZCI6IjQxN2FlNmViLWFhYzgtNDJjOC05MDBjLTBlNTBkZWJiYTY4OCIsImFwcGlkYWNyIjoiMCIsImdyb3VwcyI6WyIzMjVhNDljOS1mNjQ0LTQxNjEtODdmZS1kZTQ5ZGEyNDhjZTkiXSwiaXBhZGRyIjoiMTY3LjIyMC4yLjE4IiwibmFtZSI6Ik1hZGVsaW5lIFN0YWdlciIsIm9pZCI6ImIzZTE1ODM0LTAxZmUtNDIwNi05MjkwLTk5OTNiMzM1MWM2MSIsInB1aWQiOiIxMDAzN0ZGRUFDRjVBNUE1Iiwic2NwIjoiUHJpbnQuRGV2aWNlIiwic3ViIjoiN2hhQzVjdEZlYjZPVHBsMHROUDJmRDJVY3pWTFRjbTZlNkQ1eEZkOEpvYyIsInRlbmFudF9jdHJ5IjoiVVMiLCJ0aWQiOiJmMGQ4ODMyMy04OGY2LTQ4MTMtOGI0ZC05NGVjNjdlNjA3YmQiLCJ1bmlxdWVfbmFtZSI6Im1hc3RhZ2VyQGNsb3VkcHJpbnRwcm9kdWN0aW9uLm9ubWljcm9zb2Z0LmNvbSIsInVwbiI6Im1hc3RhZ2VyQGNsb3VkcHJpbnRwcm9kdWN0aW9uLm9ubWljcm9zb2Z0LmNvbSIsInV0aSI6Inp2N2EtdGRrR0VHQkFSMl9zWU1UQUEiLCJ2ZXIiOiIxLjAiLCJ3aWRzIjpbIjYyZTkwMzk0LTY5ZjUtNDIzNy05MTkwLTAxMjE3NzE0NWUxMCJdfQ.Nfz82GPdQUx6py2xwhVhI4hvpbLTdaaDSVFnGx4Eb3CeJHcQvCmmKoB9Lze7YITcEcLdxUkGEQGEXSh6M3yDrNP_hsoIROdWhe6RDjbYVPmJUL319lL4eNtQTJq8bKcJVbeM5SamlY1mBIhxH_sjL4TX0NN2RnDIuF_L1NSRW0IaHoZxzf257y0n7BqPROl3VpQ97wA8P-hhVBbfwwB9i-sLbsoCVszuE9JnHpgJPm6h9FDL9Px57ddTMZDvJchxOL5gUTA76gdRqUUzLROCMlz0R7vTJotl2RQnrzZBoNNoM9iJHL2KqQKuuezHEro1453lSRASiBkZHHEOFglzSg"
}
2. Estrutura de resposta a erros
Para as APIs acima, em caso de erro, a seguinte estrutura de erro será retornada na carga no formato JSON com os seguintes valores (diferencia maiúsculas de minúsculas). Essas respostas de erro são principalmente para fins de desenvolvimento e cabe ao desenvolvedor o que mostrar ao usuário, se houver.
| Nome do valor | Tipo de Valor | Descrição | Necessário |
|---|---|---|---|
| erro | string | Uma cadeia de caracteres de código de erro usada para classificar o tipo de erro que ocorreu. | Sim |
| error_description | string | Uma mensagem de erro específica que pode ajudar a identificar a causa raiz do erro. | Não |
| error_code | Número inteiro | Código de erro adicional que pode ajudar a diagnosticar o problema. | Não |
| http_status_code | Número inteiro | O código de status HTTP que foi retornado com essa resposta de erro. | Não |
| retry_timeout | Número inteiro | O número de segundos que a impressora deve aguardar antes de repetir a solicitação. | Não |
Cada API acima listará suas possíveis strings de código de erro.
2.1 Exemplo de resposta
{
"error": "invalid_request",
"error_description": "Missing required field device_type"
}
Conectividade com o serviço de Impressão Universal após o registro da impressora
A Impressão Universal suporta a funcionalidade necessária definida no PWG 5100.18 (IPP Infra). Espera-se que as impressoras prontas para Impressão Universal usem esse protocolo para se comunicar com a Impressão Universal depois de concluir o processo de registro da impressora. Para garantir que o chamador seja uma impressora com acesso, a impressora usará o Token de Acesso do dispositivo, conforme descrito em Recuperação de Token de Acesso da Impressora, como o valor do Portador para o cabeçalho HTTP Authorization .