通用列印 （UP） 印表機註冊
1. 註冊
1.1 流程
1.2 API
全域 UP 註冊服務提供下列 API 來註冊印表機。
全域 UP 註冊服務基底 URL： https://register.print.microsoft.com
完整 URL 會是全域基底 URL 和以下端點的組合。
1.2.1 /register
/register 端點是用來註冊印表機。 註冊有 2 個階段。
註冊印表機的初始註冊呼叫
輪詢註冊狀態以完成註冊要求
1.2.1.1 起始註冊
第一個階段是使用全域註冊服務起始註冊要求。 這是透過以 JSON 格式向 /register 端點發出 POST 要求來完成。
1.2.1.1.1 HTTP 要求
POST /api/{version}/register
{version} 是印表機所使用的UP註冊 API/通訊協定版本。
目前支援的版本如下：
- v1.0
1.2.1.1.2 要求標頭
針對 v1.0：
| 名稱 | 描述 |
|---|---|
| 授權 | 持有人 {token} 必要。 印表機必須登入系統管理員，才能Microsoft Entra ID，然後遵循裝置程式代碼流程或其他授權流程。 |
1.2.1.1.3 要求內容類型
application/json
1.2.1.1.4 要求承載
註冊要求承載會採用 JSON 格式，具有下列值（區分大小寫）：
| 值名稱 | 值類型 | 描述 | 必要 |
|---|---|---|---|
| NAME | 字串 | 印表機的易記名稱。 | Yes |
| 製造商 | 字串 | 印表機製造商。 | Yes |
| 機型 | 字串 | 印表機的模型。 | Yes |
| device_id | 字串 | 印表機的實體裝置 UUID。 | Yes |
| device_type | 字串 | 裝置的類型。 支援的值（不含引號）：“印表機” | Yes |
| certificate_request | DeviceCertRequest 物件 | 印表機用來識別自己所建立及使用之憑證的 X.509 憑證簽署要求 （CSR）。 如需如何使用 BouncyCastle .NET 連結庫建立 CSR 的程式碼範例，請參閱附錄 A.1。 | Yes |
DeviceCertRequest 物件具有下列值（區分大小寫）：
| 值名稱 | 值類型 | 描述 | 必要 |
|---|---|---|---|
| type | 字串 | 必須包含 「pkcs10」 的屬性。 | Yes |
| 資料 | 字串 | 屬性，包含base64編碼的PKCS#10 憑證要求 RFC4211。 憑證要求必須使用 RSA 公鑰演演算法搭配 2048 位密鑰、SHA256WithRSAEncryption 簽章演算法和 SHA256 哈希演算法。 | Yes |
| transport_key | 字串 | 用戶端所產生非對稱密鑰的base64編碼公用部分。 | Yes |
1.2.1.1.5 成功回應
成功時（202 已接受），註冊響應承載會採用 JSON 格式，具有下列值（區分大小寫）：
| 值名稱 | 值類型 | 描述 | 必要 |
|---|---|---|---|
| registration_id | 字串 | 表示此註冊要求的唯一標識碼。 輪詢註冊狀態時，將會使用此方式。 | Yes |
| interval | 整數 | 輪詢間隔時間（以秒為單位），以檢查註冊要求是否完成。 | Yes |
1.2.1.1.6 錯誤回應
發生錯誤時，將會傳回下列 HTTP 狀態代碼以及錯誤響應承載。 錯誤響應承載會在第 2 節的格式之後包含錯誤 JSON 物件。
HTTP 狀態碼
| HTTP 狀態碼 | 描述 |
|---|---|
| 400 (錯誤的要求) | 要求無效或格式不正確。 如需詳細資訊，請參閱錯誤響應承載。 修正並重新傳送要求。 |
| 500 （內部伺服器錯誤） | 服務中發生內部錯誤。 如需詳細資訊，請參閱錯誤響應承載。 重試要求（可能的話，將會設定retry_timeout）。 |
錯誤碼
| 錯誤代碼 | 描述 | HTTP 狀態碼 |
|---|---|---|
| invalid_request | 註冊要求承載的格式不正確/無效。 這通常發生在開發階段。 如需詳細資訊，請參閱error_description。 | 400 |
| device_code_error | 服務無法產生裝置/使用者程式代碼組。 | 500 |
| storage_error | 服務發生後端記憶體的錯誤。 | 500 |
| service_error | 服務中發生錯誤。 如需詳細資訊，請參閱error_description。 | 500 |
1.2.1.1.7 範例
1.2.1.1.7.5 要求 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 回應 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 取得註冊狀態
成功接受註冊要求之後，列印機會輪詢 /register 端點以取得註冊要求的狀態。 印表機應該根據註冊回應中收到的間隔值進行輪詢，而且必須提供 registration_id 收到的 。
1.2.1.2.1 HTTP 要求
GET /api/{version}/register?{Query Parameters}
{version} 是印表機所使用的UP註冊 API/通訊協定版本。
目前支援的版本如下：
- v1.0
{Query Parameters} 在下一節中指定 。
1.2.1.2.2 要求標頭
針對 v1.0：
| 名稱 | 描述 |
|---|---|
| 授權 | 持有人 {token} 必要。 印表機必須登入系統管理員，才能Microsoft Entra ID，或遵循裝置程式代碼流程。 可以使用針對第一個緩存器要求取得的相同令牌。 |
1.2.1.2.3 要求查詢參數
| 參數名稱 | 描述 | 必要 |
|---|---|---|
| registration_id | 從註冊要求回應收到的註冊標識碼。 | Yes |
1.2.1.2.4 成功回應
下列「成功」案例將會傳回下列 HTTP 狀態代碼：
| HTTP 狀態碼 | 註冊階段 |
|---|---|
| 200 (確定) | 註冊完成 |
| 202 (已接受) | 進行中註冊 - 請在間隔時間過後提出另一個要求 |
響應承載
註冊進行中 （202 已接受）：
註冊回應承載會採用 JSON 格式，具有下列值（區分大小寫）：
| 值名稱 | 值類型 | 描述 | 必要 |
|---|---|---|---|
| interval | 整數 | 輪詢間隔時間（以秒為單位），以檢查註冊要求是否完成。 請注意，每次輪詢間隔時間都不需要相同。 | Yes |
註冊完成 （200 OK）：
註冊回應承載會採用 JSON 格式，具有下列值（區分大小寫）：
| 值名稱 | 值類型 | 描述 | 必要 |
|---|---|---|---|
| cloud_device_id | 字串 | 此印表機代表之 Cloud 中印表機的 UUID。 | Yes |
| 憑證 (certificate) | 字串 | Base64 編碼的已簽署 X.509 憑證。 | Yes |
| print_svc_url | 字串 | 處理印表機作業之通用列印 （UP） 服務的URL。 | Yes |
| notification_url | 字串 | 印表機應該用來接聽通知的 URL（新的列印作業、取消列印作業等...）。 | Yes |
| mcp_svc_resource_id | 字串 | UP 服務的資源標識碼。 要求 OAuth 令牌以與 UP 和 UP 通知服務通訊時需要。 | Yes |
| device_token_url | 字串 | 印表機應該用來取得UP和UP通知服務的令牌的安全令牌授權單位 （STA） URL。 | Yes |
1.2.1.2.5 錯誤回應
發生錯誤時，將會傳回下列 HTTP 狀態代碼以及錯誤響應承載。 錯誤響應承載會在第 2 節的格式之後包含錯誤 JSON 物件。
HTTP 狀態碼
| HTTP 狀態碼 | 描述 |
|---|---|
| 400 (錯誤的要求) | 要求無效或格式不正確。 如需詳細資訊，請參閱錯誤響應承載。 應該重新啟動註冊。 |
| 500 （內部伺服器錯誤） | 服務中發生內部錯誤。 如需詳細資訊，請參閱錯誤響應承載。 應該重新啟動註冊。 |
錯誤碼
| 錯誤代碼 | 描述 | HTTP 狀態碼 |
|---|---|---|
| invalid_registration_id | 提供的註冊標識碼無效。 如果註冊標識符儲存不正確，或列印機註冊未在註冊逾時內完成，就可能發生此情況。 應該重新啟動註冊。 | 400 |
| device_already_exists | 已註冊的裝置已經註冊。 系統管理員應該檢查 UP 入口網站，以查看已註冊的裝置是否存在。 如果是，可能是系統管理員忘記刪除/取消註冊的過時專案。 應該重新啟動註冊。 | 400 |
| user_token_error | 服務無法取得使用者令牌以執行註冊。 應該重新啟動註冊。 | 500 |
| storage_error | 服務發生後端記憶體的錯誤。 應該重新啟動註冊。 | 500 |
| service_error | 服務中發生錯誤。 如需詳細資訊，請參閱error_description。 應該重新啟動註冊。 | 500 |
1.2.1.2.6 範例
1.2.1.2.6.3 要求 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 進行中回應 v1.0
HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache
{
"interval": 15
}
1.2.1.2.6.7 已完成回應 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 驗證
註冊印表機之前，必須先遵循裝置程式代碼流程或其他授權流程，驗證系統管理員以Microsoft Entra標識符。 取得的印表機管理員存取令牌必須在要求授權標頭中傳送，才能註冊印表機。 您可以在支援的驗證流程中找到 Microsoft Entra ID 所支援之裝置程式代碼和其他驗證流程的檔。
1.2.1.3.1 裝置程式代碼流程參數
您可以在 OAuth 2.0 裝置程式代碼流程中找到Microsoft Entra 識別碼支援的檔。 下面 client_id 所列是暫時的。 我們將在近期提供其他資訊。
| 參數名稱 | 描述 | 必要 |
|---|---|---|
| tenant | 針對租用戶參數使用「組織」。 | Yes |
| client_id | 用於 registered client ID client_id。 註冊 OEM 用戶端的其他資訊。 |
Yes |
| 範圍 (scope) | https://print.print.microsoft.com/.default用於範圍 |
Yes |
1.2.1.3.2 範例裝置程序代碼流程要求
1.2.1.3.2.1 起始裝置程式代碼流程
要求：
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
回應：
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 擷取使用者令牌
要求：
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
回應： authorization_pending，使用者尚未登入。
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
}
回應： success，使用者已登入，令牌會傳回。 傳送要求向通用列印註冊印表機時，此令牌可以在必要的授權標頭中使用（如第 1.2.1.1.2 節所述）。
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. 錯誤回應結構
針對上述 API，在錯誤時，會以 JSON 格式傳回下列錯誤結構，並具有下列值（區分大小寫）。 這些錯誤回應主要是為了開發目的，而開發人員會視需要向使用者顯示什麼內容。
| 值名稱 | 值類型 | 描述 | 必要 |
|---|---|---|---|
| error | 字串 | 錯誤碼字串，用來分類所發生的錯誤類型。 | Yes |
| error_description | 字串 | 特定錯誤訊息，可協助識別錯誤的根本原因。 | No |
| error_code | 整數 | 可協助診斷問題的其他錯誤碼。 | No |
| http_status_code | 整數 | 以此錯誤回應傳回的 HTTP 狀態代碼。 | No |
| retry_timeout | 整數 | 印表機在重試要求之前應該等候的秒數。 | No |
上述每個 API 都會列出其可能的錯誤碼字串（s）。
2.1 範例回應
{
"error": "invalid_request",
"error_description": "Missing required field device_type"
}
印表機註冊后與通用印表服務的連線
通用列印支援 PWG 5100.18 中定義的必要功能（IPP Infra）。 一旦完成印表機註冊程式，通用列印就緒印表機就應該使用此通訊協定與通用列印通訊。 為了確保呼叫端是具有存取權的印表機，列印機會使用裝置存取令牌，如印表機存取令牌擷取中所述，做為 HTTP Authorization 標頭的持有人值。