Registro de impressora Universal Print (UP)
1. Inscrição
1.1 Vazão
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 do Serviço de Registro Global UP:https://register.print.microsoft.com
A URL completa será a combinação da URL base global e do(s) ponto(s) de extremidade abaixo.
1.2.1 /registo
O ponto de extremidade /register é usado para registrar uma impressora. São 2 etapas para inscrição.
Chamada de registro inicial para registrar a impressora
Votação do status do registro 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 v1.0:
| Nome | Descrição |
|---|---|
| Autorização | Portador {token} Obrigatório. A impressora deve entrar no administrador para o Microsoft Entra ID, seguindo o fluxo Código do dispositivo ou outro fluxo de autorização. |
1.2.1.1.3 Tipo de conteúdo de solicitação
application/json
1.2.1.1.4 Carga útil de solicitação
A carga útil 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. | Yes |
| fabricante | string | O fabricante da impressora. | Yes |
| modelo | string | O modelo da impressora. | Yes |
| device_id | string | O dispositivo físico UUID da impressora. | Yes |
| device_type | string | O tipo do dispositivo. Valores suportados (sem aspas): "impressora" | Yes |
| 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 BouncyCastle .NET. | Yes |
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". | Yes |
| 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. | Yes |
| transport_key | string | A parte pública codificada em base64 de uma chave assimétrica gerada pelo cliente. | Yes |
1.2.1.1.5 Resposta bem-sucedida
Em caso de sucesso (202 Aceitos), a carga útil 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 sondar o status do registro. | Yes |
| intervalo | Número inteiro | Tempo de intervalo de sondagem (em segundos) para verificar a conclusão da solicitação de registro. | Yes |
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) | O pedido é inválido ou malformado. Consulte a carga útil de resposta a erros para obter detalhes. Corrija e reenvie a solicitação. |
| 500 (Erro interno do servidor) | Ocorreu um erro interno no serviço. Consulte a carga útil de resposta a erros para obter detalhes. Repita a solicitação (se possível, retry_timeout será definida). |
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 código de dispositivo/usuário. | 500 |
| storage_error | O serviço apresentou um erro com o armazenamento 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 de registro
Depois que a solicitação de registro for aceita com êxito, a impressora pesquisará o /register ponto de extremidade para o status da solicitação de registro. A impressora deve sondar 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 v1.0:
| Nome | Descrição |
|---|---|
| Autorização | Portador {token} Obrigatório. A impressora deve entrar no administrador para o Microsoft Entra ID ou seguir o fluxo de 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 | O ID de registro recebido da resposta da solicitação de registro. | Yes |
1.2.1.2.4 Respostas bem-sucedidas
Os seguintes códigos de status HTTP serão retornados para os seguintes cenários de "êxito":
| Código de Status HTTP | Fase de Inscrições |
|---|---|
| 200 (OK) | Registro completo |
| 202 (Aceito) | Registro em andamento - Faça outra solicitação após o tempo de intervalo ter passado |
Cargas úteis de resposta
Inscrições em andamento (202 aceitas):
A carga útil 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 |
|---|---|---|---|
| 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 de intervalo de sondagem não precisará ser o mesmo todas as vezes. | Yes |
Inscrição Concluída (200 OK):
A carga útil 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 |
|---|---|---|---|
| cloud_device_id | string | O UUID da impressora na nuvem que esta impressora representa. | Yes |
| certificado | string | Certificado X.509 assinado codificado em Base64. | Yes |
| print_svc_url | string | A URL para o serviço UP, que manipula as operações da impressora. | Yes |
| notification_url | string | O URL que deve ser usado pela impressora para ouvir notificações (novo trabalho de impressão, cancelar trabalho de impressão, etc...). | Yes |
| mcp_svc_resource_id | string | A ID do recurso do serviço UP. Necessário ao solicitar o token OAuth para comunicação com os Serviços de Notificação UP e UP. | Yes |
| device_token_url | string | A URL da Autoridade de Token Seguro (STA) que a impressora deve usar para obter tokens para os Serviços de Notificação UP e UP. | Yes |
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) | O pedido é inválido ou malformado. Consulte a carga útil de resposta a erros para obter detalhes. O registro deve ser reiniciado. |
| 500 (Erro interno do servidor) | Ocorreu um erro interno no serviço. Consulte a carga útil de resposta a erros 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 | O ID de registro fornecido é inválido. Isso pode ocorrer se a ID de registro foi armazenada incorretamente ou se o registro da impressora não foi 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 não conseguiu obter o token de usuário para executar o registro. O registro deve ser reiniciado. | 500 |
| storage_error | O serviço apresentou um erro com o armazenamento 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 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 suportados pelo Microsoft Entra ID podem ser encontrados em Fluxos de autenticação suportados.
1.2.1.3.1 Parâmetros de fluxo de código do dispositivo
A documentação do suporte do Microsoft Entra ID do fluxo de código do dispositivo pode ser encontrada em Fluxo de código do dispositivo OAuth 2.0. A client_id lista abaixo é temporária. Forneceremos informações adicionais em um futuro próximo.
| Nome do Parâmetro | Descrição | Obrigatório |
|---|---|---|
| locatário | Use "Organizations" para o parâmetro de locatário. | Yes |
| client_id | Use registered client ID para o client_id. Informações adicionais em Registrando cliente OEM. |
Yes |
| scope | Uso https://print.print.microsoft.com/.default para o escopo |
Yes |
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 com o Universal Print.
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 for o caso.
| Nome do valor | Tipo de Valor | Descrição | Necessário |
|---|---|---|---|
| error | string | Uma cadeia de caracteres de código de erro que é usada para classificar o tipo de erro que ocorreu. | Yes |
| 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 tentar novamente a solicitação. | Não |
Cada API acima listará sua(s) possível(s) sequência(s) 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 Universal Print após o registro da impressora
O Universal Print 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 Universal Print 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 à Impressora, como o valor do Portador para o cabeçalho HTTP Authorization .