UP(유니버설 인쇄) 프린터 등록
1. 등록
1.1 흐름
1.2 API
다음 API는 전역 UP 등록 서비스에서 프린터 등록에 사용할 수 있습니다.
전역 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의 경우:
| 속성 | 설명 |
|---|---|
| Authorization | 전달자 {token}이(가) 필요합니다. 프린터는 디바이스 코드 흐름 또는 다른 권한 부여 흐름을 따라 관리자가 Microsoft Entra ID에 로그인해야 합니다. |
1.2.1.1.3 콘텐츠 형식 요청
application/json
1.2.1.1.4 요청 페이로드
등록 요청 페이로드는 다음 값(대/소문자 구분)이 있는 JSON 형식입니다.
| 값 이름 | 값 유형 | 설명 | 필수 |
|---|---|---|---|
| name | string | 프린터의 이름입니다. | 예 |
| 제조업체 | string | 프린터 제조업체입니다. | 예 |
| model | string | 프린터의 모델입니다. | 예 |
| device_id | string | 프린터의 물리적 디바이스 UUID입니다. | 예 |
| device_type | string | 디바이스의 유형입니다. 지원되는 값(따옴표 제외): "printer" | 예 |
| certificate_request | DeviceCertRequest 개체 | 프린터에서 자체 식별을 위해 만들고 사용하는 인증서에 대한 X.509 CSR(인증서 서명 요청)입니다. BouncyCastle .NET 라이브러리를 사용하여 CSR을 만드는 방법에 대한 코딩 샘플은 부록 A.1을 참조하세요. | 예 |
DeviceCertRequest 개체의 값은 다음과 같습니다(대/소문자 구분).
| 값 이름 | 값 유형 | 설명 | 필수 |
|---|---|---|---|
| type | string | "pkcs10"을 포함해야 하는 속성입니다. | 예 |
| 데이터 | string | base64로 인코딩된 PKCS#10 인증서 요청 RFC4211 포함하는 속성입니다. 인증서 요청은 2048비트 키, SHA256WithRSAEncryption 서명 알고리즘 및 SHA256 해시 알고리즘과 함께 RSA 공개 키 알고리즘을 사용해야 합니다. | 예 |
| transport_key | string | 클라이언트에서 생성되는 비대칭 키의 base64로 인코딩된 공용 부분입니다. | 예 |
1.2.1.1.5 성공적인 응답
성공 시(202 수락됨) 등록 응답 페이로드는 다음 값(대/소문자 구분)이 있는 JSON 형식입니다.
| 값 이름 | 값 유형 | 설명 | 필수 |
|---|---|---|---|
| registration_id | string | 이 등록 요청을 나타내는 고유 ID입니다. 등록 상태를 폴링할 때 사용됩니다. | 예 |
| interval | 정수 | 등록 요청 완료를 확인하기 위한 폴링 간격 시간(초)입니다. | 예 |
1.2.1.1.6 오류 응답
오류가 발생하면 오류 응답 페이로드와 함께 다음 HTTP 상태 코드가 반환됩니다. 오류 응답 페이로드에는 섹션 2의 형식에 따라 오류 JSON 개체가 포함됩니다.
HTTP 상태 코드
| HTTP 상태 코드 | 설명 |
|---|---|
| 400(잘못된 요청) | 요청이 잘못되었거나 형식이 잘못되었습니다. 자세한 내용은 오류 응답 페이로드를 참조하세요. 요청을 수정하고 다시 보냅니다. |
| 500(Internal Server Error) | 서비스에서 내부 오류가 발생했습니다. 자세한 내용은 오류 응답 페이로드를 참조하세요. 요청을 다시 시도합니다(가능한 경우 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의 경우:
| 속성 | 설명 |
|---|---|
| Authorization | 전달자 {token} 이(가) 필요합니다. 프린터는 관리자를 Microsoft Entra ID에 로그인하거나 디바이스 코드 흐름을 따라야 합니다. 첫 번째 등록 요청에 대해 획득한 동일한 토큰을 사용할 수 있습니다. |
1.2.1.2.3 쿼리 매개 변수 요청
| 매개 변수 이름 | 설명 | 필수 |
|---|---|---|
| registration_id | 등록 요청의 응답에서 받은 등록 ID입니다. | 예 |
1.2.1.2.4 성공적인 응답
다음 "성공" 시나리오에 대해 다음 HTTP 상태 코드가 반환됩니다.
| HTTP 상태 코드 | 등록 단계 |
|---|---|
| 200(OK) | 등록 완료 |
| 202(수락됨) | 등록 진행 중 - 간격 시간이 경과한 후 다른 요청을 수행하세요. |
응답 페이로드
등록 진행 중(202 허용):
등록 응답 페이로드는 다음 값(대/소문자 구분)이 있는 JSON 형식입니다.
| 값 이름 | 값 유형 | 설명 | 필수 |
|---|---|---|---|
| interval | 정수 | 등록 요청 완료를 확인하기 위한 폴링 간격 시간(초)입니다. 폴링 간격 시간은 매번 동일할 필요가 없습니다. | 예 |
등록 완료(200 OK):
등록 응답 페이로드는 다음 값(대/소문자 구분)이 있는 JSON 형식입니다.
| 값 이름 | 값 유형 | 설명 | 필수 |
|---|---|---|---|
| cloud_device_id | string | 이 프린터가 나타내는 클라우드의 프린터 UUID입니다. | 예 |
| 인증서(certificate) | string | Base64로 인코딩된 서명된 X.509 인증서입니다. | 예 |
| print_svc_url | string | 프린터 작업을 처리하는 UP(유니버설 인쇄) 서비스의 URL입니다. | 예 |
| notification_url | string | 프린터에서 알림을 수신 대기하는 데 사용해야 하는 URL입니다(새 인쇄 작업, 인쇄 작업 취소 등). | 예 |
| mcp_svc_resource_id | string | UP 서비스의 리소스 ID입니다. UP 및 UP Notification Services와의 통신을 위해 OAuth 토큰을 요청할 때 필요합니다. | 예 |
| device_token_url | string | 프린터에서 UP 및 UP Notification Services에 대한 토큰을 가져오는 데 사용해야 하는 STA(보안 토큰 기관)의 URL입니다. | 예 |
1.2.1.2.5 오류 응답
오류가 발생하면 오류 응답 페이로드와 함께 다음 HTTP 상태 코드가 반환됩니다. 오류 응답 페이로드에는 섹션 2의 형식에 따라 오류 JSON 개체가 포함됩니다.
HTTP 상태 코드
| HTTP 상태 코드 | 설명 |
|---|---|
| 400(잘못된 요청) | 요청이 잘못되었거나 형식이 잘못되었습니다. 자세한 내용은 오류 응답 페이로드를 참조하세요. 등록을 다시 시작해야 합니다. |
| 500(Internal Server Error) | 서비스에서 내부 오류가 발생했습니다. 자세한 내용은 오류 응답 페이로드를 참조하세요. 등록을 다시 시작해야 합니다. |
오류 코드
| 오류 코드 | 설명 | HTTP 상태 코드 |
|---|---|---|
| invalid_registration_id | 제공된 등록 ID가 잘못되었습니다. 등록 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 ID에 인증해야 합니다. 가져온 프린터 관리자 액세스 토큰은 프린터 등록 요청의 권한 부여 헤더에 보내야 합니다. Microsoft Entra ID에서 지원하는 디바이스 코드 및 기타 인증 흐름에 대한 설명서는 지원되는 인증 흐름에서 찾을 수 있습니다.
1.2.1.3.1 디바이스 코드 흐름 매개 변수
디바이스 코드 흐름의 Microsoft Entra ID 지원에 대한 설명서는 OAuth 2.0 디바이스 코드 흐름에서 찾을 수 있습니다. client_id 아래에 나열된 임시 항목입니다. 가까운 장래에 추가 정보를 제공할 예정입니다.
| 매개 변수 이름 | 설명 | 필수 |
|---|---|---|
| 테넌트 | 테넌트 매개 변수에 "조직"을 사용합니다. | 예 |
| client_id | client_id 사용합니다 registered client ID . OEM 클라이언트 등록에 대한 추가 정보입니다. |
예 |
| scope | 범위에 사용 https://print.print.microsoft.com/.default |
예 |
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 | string | 발생한 오류 유형을 분류하는 데 사용되는 오류 코드 문자열입니다. | 예 |
| error_description | string | 오류의 근본 원인을 파악하는 데 도움이 될 수 있는 특정 오류 메시지입니다. | 아니요 |
| error_code | 정수 | 문제를 진단하는 데 도움이 되는 추가 오류 코드입니다. | 아니요 |
| http_status_code | 정수 | 이 오류 응답과 함께 반환된 HTTP 상태 코드입니다. | 아니요 |
| retry_timeout | 정수 | 요청을 다시 시도하기 전에 프린터에서 대기해야 하는 시간(초)입니다. | 아니요 |
위의 각 API는 가능한 오류 코드 문자열을 나열합니다.
2.1 예제 응답
{
"error": "invalid_request",
"error_description": "Missing required field device_type"
}
프린터 등록 후 유니버설 인쇄 서비스와 연결
유니버설 인쇄는 PWG 5100.18(IPP 인프라)에 정의된 필수 기능을 지원합니다. 유니버설 인쇄 준비 프린터는 프린터 등록 프로세스가 완료되면 이 프로토콜을 사용하여 유니버설 인쇄와 통신해야 합니다. 호출자가 액세스 권한이 있는 프린터인지 확인하기 위해 프린터는 프린터 액세스 토큰 검색에 설명된 대로 디바이스 액세스 토큰을 HTTP Authorization 헤더의 전달자 값으로 사용합니다.