Registrering av universalutskriftsskrivare (UP)
1. Registrering
1.1 Flöde
1.2 API:er
Följande API:er är tillgängliga med den globala UP-registreringstjänsten för registrering av skrivare.
Global UP Registration Service Base URL: https://register.print.microsoft.com
Den fullständiga URL:en är kombinationen av den globala bas-URL:en och slutpunkterna nedan.
1.2.1 /register
Slutpunkten /register används för att registrera en skrivare. Det finns två steg för registrering.
Första registreringsanropet för att registrera skrivaren
Avsökningsregistreringsstatus för slutförande av registreringsbegäran
1.2.1.1 Initiera registrering
Det första steget är att initiera en registreringsbegäran med den globala registreringstjänsten. Detta görs genom att skicka en POST-begäran till /register-slutpunkten med registreringsnyttolasten i JSON-format.
1.2.1.1.1 HTTP-begäran
POST /api/{version}/register
{version} är den version av UP-registrerings-API:et/protokollet som skrivaren använder.
Versioner som stöds för närvarande är:
- V1.0
1.2.1.1.2 Begärandehuvuden
För v1.0:
| Name | beskrivning |
|---|---|
| Auktorisering | Bearer {token} Krävs. Skrivaren måste logga in administratören på Microsoft Entra-ID genom att följa flödet Enhetskod eller ett annat auktoriseringsflöde. |
1.2.1.1.3 Begär innehållstyp
application/json
1.2.1.1.4 Begär nyttolast
Nyttolasten för registreringsbegäran kommer att vara i JSON-format med följande värden (skiftlägeskänslig):
| Värdenamn | Värdetyp | beskrivning | Obligatoriskt |
|---|---|---|---|
| name | sträng | Skrivarens eget namn. | Ja |
| manufacturer | sträng | Skrivarens tillverkare. | Ja |
| modell | sträng | Skrivarens modell. | Ja |
| device_id | sträng | Den fysiska enhetens UUID för skrivaren. | Ja |
| device_type | sträng | Enhetens typ. Värden som stöds (utan citattecken): "skrivare" | Ja |
| certificate_request | DeviceCertRequest-objekt | X.509-certifikatsigneringsbegäran (CSR) för certifikatet som skapats och använts av skrivaren för att identifiera sig själv. Se bilaga A.1 för ett kodexempel på hur du skapar en CSR med BouncyCastle .NET-biblioteket. | Ja |
DeviceCertRequest-objektet har följande värden (skiftlägeskänsligt):
| Värdenamn | Värdetyp | beskrivning | Obligatoriskt |
|---|---|---|---|
| type | sträng | En egenskap som MÅSTE innehålla "pkcs10". | Ja |
| data | sträng | En egenskap som innehåller en base64-kodad PKCS#10-certifikatbegäran RFC4211. Certifikatbegäran MÅSTE använda en offentlig RSA-nyckelalgoritm med en 2048-bitarsnyckel, en SHA256WithRSAEncryption-signaturalgoritm och en SHA256-hashalgoritm. | Ja |
| transport_key | sträng | Den base64-kodade offentliga delen av en asymmetrisk nyckel som genereras av klienten. | Ja |
1.2.1.1.5 Lyckat svar
Vid lyckad (202 Godkänd) kommer nyttolasten för registreringssvaret att vara i JSON-format med följande värden (skiftlägeskänslig):
| Värdenamn | Värdetyp | beskrivning | Obligatoriskt |
|---|---|---|---|
| registration_id | sträng | Det unika ID som representerar den här registreringsbegäran. Detta används vid avsökning för registreringsstatus. | Ja |
| interval | integer | Avsökningsintervalltid (i sekunder) för att kontrollera om registreringsbegäran har slutförts. | Ja |
1.2.1.1.6 Felsvar
Vid fel returneras följande HTTP-statuskoder tillsammans med en nyttolast för felsvar. Nyttolasten för felsvar innehåller ett JSON-felobjekt som följer formatet i avsnitt 2.
HTTP-statuskoder
| HTTP-statuskod | beskrivning |
|---|---|
| 400 (felaktig begäran) | Begäran är ogiltig eller felaktig. Mer information finns i nyttolasten för felsvar. Åtgärda och skicka begäran igen. |
| 500 (internt serverfel) | Ett internt fel har uppstått i tjänsten. Mer information finns i nyttolasten för felsvar. Försök igen (om möjligt kommer retry_timeout att anges). |
Felkoder
| Felkoder | beskrivning | HTTP-statuskod |
|---|---|---|
| invalid_request | Nyttolasten för registreringsbegäran var felaktig/ogiltig. Detta inträffar vanligtvis under utvecklingsstadier. Mer information finns i error_description. | 400 |
| device_code_error | Det gick inte att generera ett par för enhets-/användarkod. | 500 |
| storage_error | Det uppstod ett fel i tjänsten med Serverdelslagring. | 500 |
| service_error | Ett fel uppstod i tjänsten. Mer information finns i error_description. | 500 |
1.2.1.1.7 Exempel
1.2.1.1.7.5 Begäran 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 Svar 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 Få registreringsstatus
När registreringsbegäran har godkänts avsöker /register skrivaren slutpunkten efter status för registreringsbegäran. Skrivaren bör avsöka baserat på det intervallvärde som tas emot i registreringssvaret och måste ange det registration_id mottagna.
1.2.1.2.1 HTTP-begäran
GET /api/{version}/register?{Query Parameters}
{version} är den version av UP-registrerings-API:et/protokollet som skrivaren använder.
Versioner som stöds för närvarande är:
- V1.0
{Query Parameters} anges i nästa avsnitt.
1.2.1.2.2 Begärandehuvuden
För v1.0:
| Name | beskrivning |
|---|---|
| Auktorisering | Bearer {token} Krävs. Skrivaren måste logga in administratören på Microsoft Entra-ID eller följa flödet Enhetskod. Samma token som hämtas för den första registerbegäran kan användas. |
1.2.1.2.3 Frågeparametrar för begäran
| Parameternamn | beskrivning | Obligatoriskt |
|---|---|---|
| registration_id | Registrerings-ID:t som togs emot från svaret på registreringsbegäran. | Ja |
1.2.1.2.4 Lyckade svar
Följande HTTP-statuskoder returneras för följande "lyckade" scenarier:
| HTTP-statuskod | Registreringsfas |
|---|---|
| 200 (OK) | Registreringen har slutförts |
| 202 (godkänd) | Registrering pågår – Gör en annan begäran när intervalltiden har passerat |
Svarsnyttolaster
Pågående registrering (202 accepterad):
Nyttolasten för registreringssvaret är i JSON-format med följande värden (skiftlägeskänslig):
| Värdenamn | Värdetyp | beskrivning | Obligatoriskt |
|---|---|---|---|
| interval | integer | Avsökningsintervalltid (i sekunder) för att kontrollera om registreringsbegäran har slutförts. Observera att avsökningsintervalltiden inte är densamma varje gång. | Ja |
Registreringen är klar (200 OK):
Nyttolasten för registreringssvaret är i JSON-format med följande värden (skiftlägeskänslig):
| Värdenamn | Värdetyp | beskrivning | Obligatoriskt |
|---|---|---|---|
| cloud_device_id | sträng | UUID för skrivaren i molnet som den här skrivaren representerar. | Ja |
| certifikat | sträng | Base64-kodat signerat X.509-certifikat. | Ja |
| print_svc_url | sträng | URL:en till tjänsten Universell utskrift (UP) som hanterar skrivaråtgärder. | Ja |
| notification_url | sträng | Den URL som ska användas av skrivaren för att lyssna efter meddelanden (nytt utskriftsjobb, avbryt utskriftsjobb osv.). | Ja |
| mcp_svc_resource_id | sträng | Resurs-ID för UP-tjänsten. Krävs när du begär OAuth-token för kommunikation med UP- och UP Notification Services. | Ja |
| device_token_url | sträng | URL:en för den säkerhetstokenutfärdare (STA) som skrivaren ska använda för att hämta token för UP- och UP Notification Services. | Ja |
1.2.1.2.5 Felsvar
Vid fel returneras följande HTTP-statuskoder tillsammans med en nyttolast för felsvar. Nyttolasten för felsvar innehåller ett JSON-felobjekt som följer formatet i avsnitt 2.
HTTP-statuskoder
| HTTP-statuskod | beskrivning |
|---|---|
| 400 (felaktig begäran) | Begäran är ogiltig eller felaktig. Mer information finns i nyttolasten för felsvar. Registreringen bör startas på nytt. |
| 500 (internt serverfel) | Ett internt fel har uppstått i tjänsten. Mer information finns i nyttolasten för felsvar. Registreringen bör startas på nytt. |
Felkoder
| Felkoder | beskrivning | HTTP-statuskod |
|---|---|---|
| invalid_registration_id | Det angivna registrerings-ID:t är ogiltigt. Detta kan inträffa om registrerings-ID:t lagrades felaktigt eller om skrivarregistreringen inte har slutförts inom tidsgränsen för registreringen. Registreringen bör startas på nytt. | 400 |
| device_already_exists | Enheten som registreras är redan registrerad. Administratören bör kontrollera UP-portalen för att se om enheten som registreras finns. I så fall kan det vara en inaktuell post som administratören glömde att ta bort/avregistrera. Registreringen bör startas på nytt. | 400 |
| user_token_error | Tjänsten kunde inte hämta användartoken för att utföra registreringen. Registreringen bör startas på nytt. | 500 |
| storage_error | Det uppstod ett fel i tjänsten med Serverdelslagring. Registreringen bör startas på nytt. | 500 |
| service_error | Ett fel uppstod i tjänsten. Mer information finns i error_description. Registreringen bör startas på nytt. | 500 |
1.2.1.2.6 Exempel
1.2.1.2.6.3 Begäran 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 Pågående svar v1.0
HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache
{
"interval": 15
}
1.2.1.2.6.7 Slutfört svar 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 Autentisering
Innan du registrerar skrivaren måste administratören autentiseras till Microsoft Entra-ID genom att följa flödet Enhetskod eller ett annat auktoriseringsflöde. Åtkomsttoken för skrivaradministratören måste skickas i auktoriseringshuvudet för begäran om att registrera en skrivare. Dokumentation om enhetskod och andra autentiseringsflöden som stöds av Microsoft Entra-ID finns i autentiseringsflöden som stöds.
1.2.1.3.1 Parametrar för enhetskodflöde
Dokumentation om Microsoft Entra ID-stöd för enhetskodflödet finns i OAuth 2.0-enhetskodflödet. Listan client_id nedan är tillfällig. Vi kommer att tillhandahålla ytterligare information inom en snar framtid.
| Parameternamn | beskrivning | Obligatoriskt |
|---|---|---|
| klientorganisation | Använd "Organisationer" för klientparametern. | Ja |
| client_id | Använd registered client ID för client_id. Ytterligare information finns i Registrera OEM-klient. |
Ja |
| omfattning | Använd https://print.print.microsoft.com/.default för omfånget |
Ja |
1.2.1.3.2 Exempel på enhetskodflödesbegäranden
1.2.1.3.2.1 Initiera enhetskodflödet
Begäran:
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
Svar:
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 Hämta användartoken
Begäran:
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
Svar: authorization_pendinganvändaren har inte loggat in ännu.
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
}
Svar: success, användaren har loggat in, token returneras. Den här token kan användas i det nödvändiga auktoriseringshuvudet (beskrivs i avsnitt 1.2.1.1.2) när du skickar en begäran om att registrera en skrivare med universell utskrift.
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. Struktur för felhantering
För api:erna ovan returneras följande felstruktur vid fel i nyttolasten i JSON-format med följande värden (skiftlägeskänsliga). Dessa felsvar är främst i utvecklingssyfte och det är upp till utvecklaren vad som ska visas för användaren, om något.
| Värdenamn | Värdetyp | beskrivning | Obligatoriskt |
|---|---|---|---|
| fel | sträng | En felkodssträng som används för att klassificera den typ av fel som inträffade. | Ja |
| error_description | sträng | Ett specifikt felmeddelande som kan hjälpa till att identifiera rotorsaken till felet. | Nej |
| error_code | integer | Ytterligare felkod som kan hjälpa dig att diagnostisera problemet. | Nej |
| http_status_code | integer | HTTP-statuskoden som returnerades med det här felsvaret. | Nej |
| retry_timeout | integer | Antalet sekunder som skrivaren ska vänta innan begäran försöker igen. | Nej |
Varje API ovan visar en lista över möjliga felkodssträngar.
2.1 Exempelsvar
{
"error": "invalid_request",
"error_description": "Missing required field device_type"
}
Anslutning med Universal Print-tjänsten efter skrivarregistrering
Universal Print stöder de funktioner som krävs som definieras i PWG 5100.18 (IPP Infra). Universell utskriftsklara skrivare förväntas använda det här protokollet för att kommunicera med Universal Print när skrivarregistreringsprocessen har slutförts. För att säkerställa att anroparen är en skrivare med åtkomst använder skrivaren enhetens åtkomsttoken, enligt beskrivningen i Hämtning av skrivaråtkomsttoken, som ägarvärde för HTTP-huvudet Authorization .