Registrazione stampante stampa universale (UP)
1. Registrazione
1.1 Flusso
1.2 API
Le API seguenti sono disponibili con il servizio di registrazione UP globale per la registrazione delle stampanti.
URL di base del servizio di registrazione UP globale: https://register.print.microsoft.com
L'URL completo sarà la combinazione dell'URL di base globale e degli endpoint seguenti.
1.2.1 /register
L'endpoint /register viene usato per registrare una stampante. Sono disponibili 2 fasi per la registrazione.
Chiamata di registrazione iniziale per registrare la stampante
Stato di registrazione del polling per il completamento della richiesta di registrazione
1.2.1.1 Avvio della registrazione
La prima fase consiste nell'avviare una richiesta di registrazione con il servizio di registrazione globale. Questa operazione viene eseguita inviando una richiesta POST all'endpoint /register con il payload di registrazione in formato JSON.
1.2.1.1.1 Richiesta HTTP
POST /api/{version}/register
{version} è la versione dell'API/protocollo di registrazione UP usata dalla stampante.
Le versioni attualmente supportate sono:
- v1.0
1.2.1.1.2 Intestazioni di richiesta
Per v1.0:
| Nome | Descrizione |
|---|---|
| Autorizzazione | Connessione {token} obbligatoria. La stampante deve accedere all'amministratore di Microsoft Entra ID, seguendo il flusso del codice del dispositivo o un altro flusso di autorizzazione. |
1.2.1.1.3 Tipo di contenuto della richiesta
application/json
1.2.1.1.4 Payload della richiesta
Il payload della richiesta di registrazione sarà in formato JSON con i valori seguenti (con distinzione tra maiuscole e minuscole):
| Nome valore | Tipo di valore | Descrizione | Richiesto |
|---|---|---|---|
| name | string | Nome descrittivo della stampante. | Sì |
| manufacturer | string | Produttore della stampante. | Sì |
| modello | string | Modello della stampante. | Sì |
| device_id | string | UUID dispositivo fisico della stampante. | Sì |
| device_type | string | Tipo di dispositivo. Valori supportati (senza virgolette): "stampante" | Sì |
| certificate_request | Oggetto DeviceCertRequest | Richiesta di firma del certificato X.509 per il certificato creato e usato dalla stampante per identificarsi. Fare riferimento all'Appendice A.1 per un esempio di codifica su come creare una richiesta di firma del certificato con la libreria BouncyCastle .NET. | Sì |
L'oggetto DeviceCertRequest ha i valori seguenti (con distinzione tra maiuscole e minuscole):
| Nome valore | Tipo di valore | Descrizione | Richiesto |
|---|---|---|---|
| type | string | Proprietà che DEVE contenere "pkcs10". | Sì |
| data | string | Proprietà che contiene una richiesta di certificato PKCS#10 con codifica Base64 RFC4211. La richiesta di certificato DEVE usare un algoritmo di chiave pubblica RSA con una chiave a 2048 bit, un algoritmo di firma SHA256WithRSAEncryption e un algoritmo hash SHA256. | Sì |
| transport_key | string | Parte pubblica con codifica Base64 di una chiave asimmetrica generata dal client. | Sì |
1.2.1.1.5 Risposta riuscita
In caso di esito positivo (202 Accettato), il payload della risposta di registrazione sarà in formato JSON con i valori seguenti (con distinzione tra maiuscole e minuscole):
| Nome valore | Tipo di valore | Descrizione | Richiesto |
|---|---|---|---|
| registration_id | string | ID univoco che rappresenta questa richiesta di registrazione. Questa operazione verrà usata durante il polling dello stato di registrazione. | Sì |
| interval | integer | Intervallo di polling (in secondi) per verificare il completamento della richiesta di registrazione. | Sì |
1.2.1.1.6 Risposta errore
In caso di errore, verranno restituiti i codici di stato HTTP seguenti insieme a un payload di risposta di errore. Il payload della risposta di errore conterrà un oggetto JSON di errore seguendo il formato nella sezione 2.
Codici di stato HTTP
| Codice di stato HTTP | Descrizione |
|---|---|
| 400 (Richiesta non valida) | La richiesta non è valida o non è valida. Per informazioni dettagliate, vedere payload della risposta agli errori. Correggere e inviare nuovamente la richiesta. |
| 500 (errore interno del server) | Si è verificato un errore interno nel servizio. Per informazioni dettagliate, vedere payload della risposta agli errori. Riprovare la richiesta (se possibile, retry_timeout verrà impostata). |
Codici errore
| Codici di errore | Descrizione | Codice di stato HTTP |
|---|---|---|
| invalid_request | Il payload della richiesta di registrazione non è valido o non è valido. Questo problema si verifica in genere durante le fasi di sviluppo. Per altri dettagli, vedere error_description. | 400 |
| device_code_error | Il servizio non è riuscito a generare una coppia device/user code. | 500 |
| storage_error | Il servizio ha riscontrato un errore con l'archiviazione back-end. | 500 |
| service_error | Si è verificato un errore nel servizio. Per altri dettagli, vedere error_description. | 500 |
1.2.1.1.7 Esempi
1.2.1.1.7.5 Richiesta 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 Risposta 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 Ottenere lo stato di registrazione
Dopo che la richiesta di registrazione è stata accettata correttamente, la stampante eseguirà il polling dell'endpoint /register per lo stato della richiesta di registrazione. La stampante deve eseguire il polling in base al valore di intervallo ricevuto nella risposta di registrazione e deve fornire il registration_id ricevuto.
1.2.1.2.1 Richiesta HTTP
GET /api/{version}/register?{Query Parameters}
{version} è la versione dell'API/protocollo di registrazione UP usata dalla stampante.
Le versioni attualmente supportate sono:
- v1.0
{Query Parameters} vengono specificati nella sezione successiva.
1.2.1.2.2 Intestazioni di richiesta
Per v1.0:
| Nome | Descrizione |
|---|---|
| Autorizzazione | Connessione {token} obbligatoria. La stampante deve accedere all'amministratore di Microsoft Entra ID o seguire il flusso del codice del dispositivo. È possibile usare lo stesso token acquisito per la prima richiesta di registrazione. |
1.2.1.2.3 Parametri di query di richiesta
| Nome parametro | Descrizione | Richiesto |
|---|---|---|
| registration_id | ID di registrazione ricevuto dalla risposta della richiesta di registrazione. | Sì |
1.2.1.2.4 Risposte riuscite
I codici di stato HTTP seguenti verranno restituiti per gli scenari di "esito positivo" seguenti:
| Codice di stato HTTP | Fase di registrazione |
|---|---|
| 200 (OK) | Registrazione completata |
| 202 (Accettato) | Registrazione in corso - Effettuare un'altra richiesta dopo il superamento dell'intervallo |
Payload di risposta
Registrazione in corso (202 accettato):
Il payload della risposta di registrazione sarà in formato JSON con i valori seguenti (con distinzione tra maiuscole e minuscole):
| Nome valore | Tipo di valore | Descrizione | Richiesto |
|---|---|---|---|
| interval | integer | Intervallo di polling (in secondi) per verificare il completamento della richiesta di registrazione. Si noti che l'intervallo di polling non sarà necessario ogni volta. | Sì |
Registrazione completata (200 OK):
Il payload della risposta di registrazione sarà in formato JSON con i valori seguenti (con distinzione tra maiuscole e minuscole):
| Nome valore | Tipo di valore | Descrizione | Richiesto |
|---|---|---|---|
| cloud_device_id | string | UUID della stampante nel cloud rappresentato dalla stampante. | Sì |
| certificato | string | Certificato X.509 con codifica Base64. | Sì |
| print_svc_url | string | URL del servizio Stampa universale (UP) che gestisce le operazioni della stampante. | Sì |
| notification_url | string | URL che deve essere utilizzato dalla stampante per ascoltare le notifiche (nuovo processo di stampa, annulla processo di stampa e così via). | Sì |
| mcp_svc_resource_id | string | ID risorsa del servizio UP. Obbligatorio quando si richiede il token OAuth per la comunicazione con UP e UP Notification Services. | Sì |
| device_token_url | string | URL dell'autorità di token sicura (STA) che la stampante deve usare per ottenere i token per UP e UP Notification Services. | Sì |
1.2.1.2.5 Risposta errore
In caso di errore, verranno restituiti i codici di stato HTTP seguenti insieme a un payload di risposta di errore. Il payload della risposta di errore conterrà un oggetto JSON di errore seguendo il formato nella sezione 2.
Codici di stato HTTP
| Codice di stato HTTP | Descrizione |
|---|---|
| 400 (Richiesta non valida) | La richiesta non è valida o non è valida. Per informazioni dettagliate, vedere payload della risposta agli errori. La registrazione deve essere avviata nuovamente. |
| 500 (errore interno del server) | Si è verificato un errore interno nel servizio. Per informazioni dettagliate, vedere payload della risposta agli errori. La registrazione deve essere avviata nuovamente. |
Codici errore
| Codici di errore | Descrizione | Codice di stato HTTP |
|---|---|---|
| invalid_registration_id | L'ID di registrazione specificato non è valido. Ciò può verificarsi se l'ID di registrazione è stato archiviato in modo non corretto o se la registrazione della stampante non è stata completata entro il timeout di registrazione. La registrazione deve essere avviata nuovamente. | 400 |
| device_already_exists | Il dispositivo registrato è già registrato. L'amministratore deve controllare il portale UP per verificare se il dispositivo registrato è presente. In caso affermativo, potrebbe trattarsi di una voce non aggiornata che l'amministratore ha dimenticato di eliminare/annullare la registrazione. La registrazione deve essere avviata nuovamente. | 400 |
| user_token_error | Il servizio non è riuscito a ottenere il token utente per eseguire la registrazione. La registrazione deve essere avviata nuovamente. | 500 |
| storage_error | Il servizio ha riscontrato un errore con l'archiviazione back-end. La registrazione deve essere avviata nuovamente. | 500 |
| service_error | Si è verificato un errore nel servizio. Per altri dettagli, vedere error_description. La registrazione deve essere avviata nuovamente. | 500 |
1.2.1.2.6 Esempi
1.2.1.2.6.3 Richiesta 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 Risposta in corso v1.0
HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache
{
"interval": 15
}
1.2.1.2.6.7 Risposta completata 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 Autenticazione
Prima di registrare la stampante, è necessario autenticare l'amministratore in Microsoft Entra ID, seguendo il flusso del codice del dispositivo o un altro flusso di autorizzazione. Il token di accesso amministratore della stampante ottenuto deve essere inviato nell'intestazione di autorizzazione della richiesta per registrare una stampante. La documentazione del codice del dispositivo e di altri flussi di autenticazione supportati da Microsoft Entra ID è disponibile in Flussi di autenticazione supportati.
1.2.1.3.1 Parametri del flusso di codice del dispositivo
La documentazione del supporto di Microsoft Entra ID del flusso di codice del dispositivo è disponibile in Flusso del codice del dispositivo OAuth 2.0. L'elenco client_id seguente è temporaneo. In futuro verranno fornite informazioni aggiuntive.
| Nome parametro | Descrizione | Richiesto |
|---|---|---|
| tenant | Usare "Organizations" per il parametro tenant. | Sì |
| client_id | Usare registered client ID per il client_id. Altre informazioni in Registrazione del client OEM. |
Sì |
| ambito | Usare https://print.print.microsoft.com/.default per l'ambito |
Sì |
1.2.1.3.2 Richieste di flusso del codice del dispositivo di esempio
1.2.1.3.2.1 Avviare il flusso del codice del dispositivo
Richiesta:
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
Risposta:
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 Recupero del token utente
Richiesta:
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
Risposta: authorization_pending, l'utente non ha ancora eseguito l'accesso.
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
}
Risposta: success, l'utente ha eseguito l'accesso, viene restituito il token. Questo token può essere usato nell'intestazione di autorizzazione richiesta (descritta nella sezione 1.2.1.1.2) quando si invia una richiesta per registrare una stampante con Stampa universale.
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. Struttura della risposta di errore
Per le API precedenti, in caso di errore, la struttura di errore seguente verrà restituita nel payload in formato JSON con i valori seguenti (con distinzione tra maiuscole e minuscole). Queste risposte di errore sono principalmente a scopo di sviluppo e spetta allo sviluppatore cosa mostrare all'utente, se qualcosa.
| Nome valore | Tipo di valore | Descrizione | Richiesto |
|---|---|---|---|
| Errore | string | Stringa di codice di errore utilizzata per classificare il tipo di errore che si è verificato. | Sì |
| error_description | string | Messaggio di errore specifico che consente di identificare la causa radice dell'errore. | No |
| error_code | integer | Codice di errore aggiuntivo che consente di diagnosticare il problema. | No |
| http_status_code | integer | Codice di stato HTTP restituito con questa risposta di errore. | No |
| retry_timeout | integer | Numero di secondi di attesa della stampante prima di ripetere la richiesta. | No |
Ogni API precedente elenca le possibili stringhe di codice di errore.
2.1 Risposta di esempio
{
"error": "invalid_request",
"error_description": "Missing required field device_type"
}
Connettività con il servizio stampa universale dopo la registrazione della stampante
Universal Print supporta la funzionalità richiesta definita in PWG 5100.18 (IPP Infra). Le stampanti pronte per la stampa universale devono usare questo protocollo per comunicare con Stampa universale dopo aver completato il processo di registrazione della stampante. Per garantire che il chiamante sia una stampante con accesso, la stampante userà il token di accesso del dispositivo, come descritto in Recupero token di accesso alla stampante, come valore di connessione per l'intestazione HTTP Authorization .