Pendaftaran Printer Universal Print (UP)
1. Pendaftaran
1.1 Alur
1.2 API
API berikut tersedia dengan Layanan Pendaftaran UP Global untuk mendaftarkan printer.
URL Dasar Layanan Pendaftaran UP Global: https://register.print.microsoft.com
URL lengkap akan menjadi kombinasi URL dasar Global dan titik akhir di bawah ini.
1.2.1 /register
Titik akhir /register digunakan untuk mendaftarkan printer. Ada 2 tahap untuk pendaftaran.
Panggilan pendaftaran awal untuk mendaftarkan printer
Status pendaftaran polling untuk penyelesaian permintaan pendaftaran
1.2.1.1 Memulai Pendaftaran
Tahap pertama adalah memulai permintaan pendaftaran dengan layanan pendaftaran global. Ini dilakukan dengan mengeluarkan permintaan POST ke titik akhir /register dengan payload pendaftaran dalam format JSON.
1.2.1.1.1 Permintaan HTTP
POST /api/{version}/register
{version} adalah versi API/protokol Pendaftaran UP yang digunakan printer.
Versi yang saat ini didukung adalah:
- v1.0
1.2.1.1.2 Header Permintaan
Untuk v1.0:
| Nama | Deskripsi |
|---|---|
| Authorization | Pembawa {token} Diperlukan. Printer harus memasukkan admin ke ID Microsoft Entra, dengan mengikuti alur Kode Perangkat atau alur otorisasi lainnya. |
1.2.1.1.3 Meminta Tipe Konten
application/json
1.2.1.1.4 Payload Permintaan
Payload permintaan pendaftaran akan dalam format JSON dengan nilai berikut (peka huruf besar/kecil):
| Nama nilai | Jenis nilai | Deskripsi | Wajib |
|---|---|---|---|
| nama | string | Nama printer yang mudah diingat. | Ya |
| produsen | string | Produsen Printer. | Ya |
| model | string | The model of the Printer. | Ya |
| device_id | string | UUID perangkat fisik Printer. | Ya |
| device_type | string | Jenis perangkat. Nilai yang didukung (tanpa tanda kutip): "printer" | Ya |
| certificate_request | Objek DeviceCertRequest | Permintaan Penandatanganan Sertifikat (CSR) X.509 untuk sertifikat yang dibuat dan digunakan oleh printer untuk mengidentifikasi dirinya sendiri. Silakan lihat Lampiran A.1 untuk sampel pengodean tentang cara membuat CSR dengan pustaka BouncyCastle .NET. | Ya |
Objek DeviceCertRequest memiliki nilai berikut (peka huruf besar/kecil):
| Nama nilai | Jenis nilai | Deskripsi | Wajib |
|---|---|---|---|
| jenis | string | Properti yang HARUS berisi "pkcs10". | Ya |
| data | string | Properti yang berisi permintaan sertifikat PKCS#10 yang dikodekan base64 RFC4211. Permintaan sertifikat HARUS menggunakan algoritma kunci umum RSA dengan kunci 2048-bit, algoritma tanda tangan SHA256WithRSAEncryption, dan algoritma hash SHA256. | Ya |
| transport_key | string | Bagian publik yang dikodekan base64 dari kunci asimetris yang dihasilkan oleh klien. | Ya |
1.2.1.1.5 Respons Berhasil
Pada keberhasilan (202 Diterima), payload respons pendaftaran akan dalam format JSON dengan nilai berikut (peka huruf besar/kecil):
| Nama nilai | Jenis nilai | Deskripsi | Wajib diisi |
|---|---|---|---|
| registration_id | string | ID unik yang mewakili permintaan pendaftaran ini. Ini akan digunakan saat polling untuk status pendaftaran. | Ya |
| interval | Integer | Waktu interval polling (dalam detik) untuk memeriksa penyelesaian permintaan pendaftaran. | Ya |
1.2.1.1.6 Respons Kesalahan
Jika terjadi kesalahan, kode status HTTP berikut akan dikembalikan bersama dengan payload respons kesalahan. Payload respons kesalahan akan berisi kesalahan objek JSON setelah format di bagian 2.
Kode status HTTP
| Kode Status HTTP | Deskripsi |
|---|---|
| 400 (Permintaan Buruk) | Permintaan tidak valid atau salah bentuk. Lihat payload respons kesalahan untuk detailnya. Perbaiki dan mengirim ulang permintaan. |
| 500 (Kesalahan Server Internal) | Terjadi kesalahan internal dalam layanan. Lihat payload respons kesalahan untuk detailnya. Coba lagi permintaan (jika memungkinkan, retry_timeout akan diatur). |
Kode Kesalahan
| Kode Kesalahan | Deskripsi | Kode Status HTTP |
|---|---|---|
| invalid_request | Payload permintaan pendaftaran salah bentuk/tidak valid. Ini biasanya terjadi selama tahap pengembangan. Lihat error_description untuk detail selengkapnya. | 400 |
| device_code_error | Layanan tidak dapat menghasilkan pasangan Kode Perangkat/Pengguna. | 500 |
| storage_error | Layanan ini mengalami kesalahan dengan Penyimpanan Back-end. | 500 |
| service_error | Terjadi kesalahan dalam layanan. Lihat error_description untuk detail selengkapnya. | 500 |
1.2.1.1.7 Contoh
1.2.1.1.7.5 Permintaan 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 Respons 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 Mendapatkan Status Pendaftaran
Setelah permintaan pendaftaran berhasil diterima, printer akan melakukan polling /register titik akhir untuk status permintaan pendaftaran. Pencetak harus melakukan polling berdasarkan nilai interval yang diterima dalam respons pendaftaran dan harus menyediakan yang registration_id diterima.
1.2.1.2.1 Permintaan HTTP
GET /api/{version}/register?{Query Parameters}
{version} adalah versi API/protokol Pendaftaran UP yang digunakan printer.
Versi yang saat ini didukung adalah:
- v1.0
{Query Parameters} ditentukan di bagian berikutnya.
1.2.1.2.2 Header Permintaan
Untuk v1.0:
| Nama | Deskripsi |
|---|---|
| Authorization | Pembawa {token} Diperlukan. Printer harus memasukkan admin ke ID Microsoft Entra, atau mengikuti alur Kode Perangkat. Token yang sama yang diperoleh untuk permintaan register pertama dapat digunakan. |
1.2.1.2.3 Parameter Kueri Permintaan
| Nama Parameter | Deskripsi | Wajib diisi |
|---|---|---|
| registration_id | ID pendaftaran diterima dari respons permintaan pendaftaran. | Ya |
1.2.1.2.4 Respons yang Berhasil
Kode status HTTP berikut akan dikembalikan untuk skenario "sukses" berikut:
| Kode Status HTTP | Fase Pendaftaran |
|---|---|
| 200 (OK) | Pendaftaran Selesai |
| 202 (Diterima) | Pendaftaran Sedang Berlangsung - Silakan buat permintaan lain setelah waktu interval berlalu |
Payload Respons
Pendaftaran Sedang Berlangsung (202 Diterima):
Payload respons pendaftaran akan dalam format JSON dengan nilai berikut (peka huruf besar/kecil):
| Nama nilai | Jenis nilai | Deskripsi | Wajib diisi |
|---|---|---|---|
| interval | Integer | Waktu interval polling (dalam detik) untuk memeriksa penyelesaian permintaan pendaftaran. Perhatikan, waktu interval polling tidak perlu sama setiap kali. | Ya |
Pendaftaran Selesai (200 OK):
Payload respons pendaftaran akan dalam format JSON dengan nilai berikut (peka huruf besar/kecil):
| Nama nilai | Jenis nilai | Deskripsi | Wajib diisi |
|---|---|---|---|
| cloud_device_id | string | UUID printer di Cloud yang diwakili printer ini. | Ya |
| sertifikat | string | Sertifikat X.509 yang dikodekan base64. | Ya |
| print_svc_url | string | URL ke layanan Universal Print (UP) yang menangani operasi printer. | Ya |
| notification_url | string | URL yang harus digunakan oleh printer untuk mendengarkan pemberitahuan (pekerjaan cetak baru, membatalkan tugas cetak, dll...). | Ya |
| mcp_svc_resource_id | string | ID Sumber Daya layanan UP. Diperlukan saat meminta token OAuth untuk komunikasi dengan Layanan Pemberitahuan UP dan UP. | Ya |
| device_token_url | string | URL Secure Token Authority (STA) yang harus digunakan printer untuk mendapatkan token untuk Up dan UP Notification Services. | Ya |
1.2.1.2.5 Respons Kesalahan
Jika terjadi kesalahan, kode status HTTP berikut akan dikembalikan bersama dengan payload respons kesalahan. Payload respons kesalahan akan berisi kesalahan objek JSON setelah format di bagian 2.
Kode status HTTP
| Kode Status HTTP | Deskripsi |
|---|---|
| 400 (Permintaan Buruk) | Permintaan tidak valid atau salah bentuk. Lihat payload respons kesalahan untuk detailnya. Pendaftaran harus dimulai kembali. |
| 500 (Kesalahan Server Internal) | Terjadi kesalahan internal dalam layanan. Lihat payload respons kesalahan untuk detailnya. Pendaftaran harus dimulai kembali. |
Kode Kesalahan
| Kode Kesalahan | Deskripsi | Kode Status HTTP |
|---|---|---|
| invalid_registration_id | ID pendaftaran yang disediakan tidak valid. Ini dapat terjadi jika ID pendaftaran disimpan dengan tidak benar atau jika pendaftaran printer belum selesai dalam batas waktu pendaftaran. Pendaftaran harus dimulai kembali. | 400 |
| device_already_exists | Perangkat yang sedang didaftarkan sudah terdaftar. Admin harus memeriksa portal UP untuk melihat apakah perangkat yang terdaftar ada. Jika ya, itu bisa menjadi entri kedaluarsa bahwa Admin lupa menghapus/membatalkan pendaftaran. Pendaftaran harus dimulai kembali. | 400 |
| user_token_error | Layanan gagal mendapatkan token pengguna untuk melakukan pendaftaran. Pendaftaran harus dimulai kembali. | 500 |
| storage_error | Layanan ini mengalami kesalahan dengan Penyimpanan Back-end. Pendaftaran harus dimulai kembali. | 500 |
| service_error | Terjadi kesalahan dalam layanan. Lihat error_description untuk detail selengkapnya. Pendaftaran harus dimulai kembali. | 500 |
1.2.1.2.6 Contoh
1.2.1.2.6.3 Permintaan 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 Sedang Berlangsung Respons v1.0
HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache
{
"interval": 15
}
1.2.1.2.6.7 Respons Selesai 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 Autentikasi
Sebelum mendaftarkan printer harus mengautentikasi admin ke ID Microsoft Entra, dengan mengikuti alur Kode Perangkat atau alur otorisasi lainnya. Token akses admin printer yang diperoleh harus dikirim di header otorisasi permintaan untuk mendaftarkan printer. Dokumentasi kode perangkat dan alur autentikasi lain yang didukung oleh ID Microsoft Entra dapat ditemukan di Alur autentikasi yang didukung.
1.2.1.3.1 Parameter Alur Kode Perangkat
Dokumentasi dukungan ID Microsoft Entra dari alur kode perangkat dapat ditemukan di alur kode perangkat OAuth 2.0. Daftar client_id di bawah ini bersifat sementara. Kami akan memberikan informasi tambahan dalam waktu dekat.
| Nama Parameter | Deskripsi | Wajib diisi |
|---|---|---|
| penyewa | Gunakan "Organisasi" untuk parameter penyewa. | Ya |
| client_id | Gunakan registered client ID untuk client_id. Informasi tambahan di Mendaftarkan Klien OEM. |
Ya |
| cakupan | Gunakan https://print.print.microsoft.com/.default untuk cakupan |
Ya |
1.2.1.3.2 Contoh Permintaan Alur Kode Perangkat
1.2.1.3.2.1 Memulai alur kode perangkat
Permintaan:
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
Respons:
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 Mengambil token pengguna
Permintaan:
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
Respons: authorization_pending, pengguna belum masuk.
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
}
Respons: success, pengguna telah masuk, token dikembalikan. Token ini dapat digunakan di header otorisasi yang diperlukan (dijelaskan dalam bagian 1.2.1.1.2) saat mengirim permintaan untuk mendaftarkan printer dengan 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. Struktur Respons Kesalahan
Untuk API di atas, jika terjadi kesalahan, struktur kesalahan berikut akan dikembalikan dalam payload dalam format JSON dengan nilai berikut (peka huruf besar/kecil). Respons kesalahan ini terutama untuk tujuan pengembangan dan terserah pengembang apa yang harus ditampilkan kepada pengguna, jika ada.
| Nama nilai | Jenis nilai | Deskripsi | Wajib diisi |
|---|---|---|---|
| kesalahan | string | String kode kesalahan yang digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi. | Ya |
| error_description | string | Pesan kesalahan tertentu yang dapat membantu mengidentifikasi akar penyebab kesalahan. | No |
| kode_kesalahan | Integer | Kode kesalahan tambahan yang dapat membantu mendiagnosis masalah. | No |
| http_status_code | Integer | Kode status HTTP yang dikembalikan dengan respons kesalahan ini. | No |
| retry_timeout | Integer | Jumlah detik yang harus ditunggu printer sebelum mencoba kembali permintaan. | No |
Setiap API di atas akan mencantumkan kemungkinan string kode kesalahannya.
2.1 Contoh Respons
{
"error": "invalid_request",
"error_description": "Missing required field device_type"
}
Konektivitas dengan layanan Universal Print setelah pendaftaran printer
Universal Print mendukung fungsionalitas yang diperlukan yang ditentukan dalam PWG 5100.18 (IPP Infra). Printer siap Universal Print diharapkan menggunakan protokol ini untuk berkomunikasi dengan Universal Print setelah menyelesaikan proses pendaftaran printer. Untuk memastikan pemanggil adalah printer dengan akses, printer akan menggunakan Token Akses perangkat, seperti yang dijelaskan dalam Pengambilan Token Akses Printer, sebagai nilai Pembawa untuk header HTTP Authorization .