ユニバーサル プリント (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 の場合:
| 名前 | 説明 |
|---|---|
| 承認 | ベアラー {トークン} (必須)。 プリンターは、デバイス コード フローまたは別の承認フローに従って、管理者を Azure AD にサインインさせる必要があります。 |
1.2.1.1.3 Content-Type の要求
application/json
1.2.1.1.4 要求ペイロード
登録要求ペイロードは、JSON 形式で、次の値 (大文字と小文字が区別されます) を含んでいます。
| 値の名前 | 値の型 | 説明 | 必須 |
|---|---|---|---|
| name | string | プロセスのフレンドリ名。 | はい |
| manufacturer | string | プリンターの製造元。 | はい |
| model | string | プリンターのモデル。 | はい |
| device_id | string | プリンターの物理デバイス UUID。 | はい |
| device_type | string | デバイスの種類。 サポートされている値 (引用符なし): 「printer」 | はい |
| certificate_request | DeviceCertRequest オブジェクト | プリンターによって作成され、自身を識別するために使用される認定資格証の X.509 証明書署名要求 (CSR)。 BouncyCastle .NET ライブラリを使用して CSR を作成する方法のコーディング サンプルについては、付録 A.1 を参照してください。 | はい |
DeviceCertRequest オブジェクトには、次の値があります (大文字と小文字が区別されます)。
| 値の名前 | 値の型 | 説明 | 必須 |
|---|---|---|---|
| 型 | string | 「pkcs10」を含む必要があるプロパティ。 | はい |
| データ | string | base64 エンコードされた PKCS#10証明書の要求 RFC4211を含むプロパティ。 証明書の要求では、2048 ビット キー、SHA256WithRSAEncryption 署名アルゴリズム、SHA256 ハッシュ アルゴリズムを持つ、RSA 公開キー アルゴリズムを使用する必要があります。 | はい |
| transport_key | string | クライアントによって生成される非対称キーの base64 エンコードされた公開部分。 | はい |
1.2.1.1.5 成功した応答
成功した場合 (202 AccepAccepted)、登録応答ペイロードは次の値 (大文字と小文字が区別されます) を持つ、JSON 形式となります。
| 値の名前 | 値の型 | 説明 | 必須 |
|---|---|---|---|
| registration_id | string | この登録要求を表す一意の ID。 これは、登録状態のポーリング時に使用されます。 | はい |
| interval | integer | 登録要求の完了をチェックするポーリング時間間隔 (秒)。 | はい |
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 の場合:
| 名前 | 説明 |
|---|---|
| 承認 | ベアラー {トークン} 必須。 プリンターは、管理者を Azure AD にサインインさせるか、デバイス コード フローに従う必要があります。 最初の登録要求に対して取得したものと同じトークンを使用できます。 |
1.2.1.2.3 要求クエリ パラメーター
| パラメーター名 | 説明 | 必須 |
|---|---|---|
| registration_id | 登録要求の応答から受信した登録 ID。 | はい |
1.2.1.2.4 応答成功
次の 「成功」 シナリオでは、次の HTTP 状態コードが返されます。
| HTTP 状態コード | 登録フェーズ |
|---|---|
| 200 (OK) | 登録の完了 |
| 202 (承認済み) | 登録の進行中 - サイクル間隔時刻が経過した後に別の要求を行ってください |
応答ペイロード
登録の進行中 (202 承認済み):
登録応答ペイロードは JSON 形式で、次の値 (大文字と小文字が区別されます) を含んでいます。
| 値の名前 | 値の型 | 説明 | 必須 |
|---|---|---|---|
| interval | integer | 登録要求の完了をチェックするポーリング時間間隔 (秒)。 注: ポーリング間隔は毎回同じである必要はありません。 | はい |
登録完了 (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 (内部サーバー エラー) | サービスで内部エラーが発生しました。 詳細については、「エラー応答ペイロード」を参照してください。 登録をやり直す必要があります。 |
エラー コード
| エラー コード | 説明 | 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 認証
プリンターを登録する前に、デバイス コード フローまたは別の承認フローに従って、管理者を Azure AD に認証する必要があります。 取得したプリンター管理者アクセス トークンは、プリンターを登録するための要求の承認ヘッダーで送信する必要があります。 Azure AD でサポートされているデバイス コードとその他の認証フローのドキュメントについては、「サポートされている認証フロー」を参照してください。
1.2.1.3.1 デバイス コード フロー パラメータ
デバイス コード フローの Azure AD サポートのドキュメントは、OAuth 2.0 デバイス コード フローにあります。 次の client_id のリストは一時的なものです。 近い将来、追加情報を提供する予定です。
| パラメーター名 | 説明 | Required |
|---|---|---|
| テナント | テナント パラメーターには 「Organizations」を使用します。 | はい |
| 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 形式のペイロードで返されます。 これらのエラー応答は主に開発目的であり、ユーザーに何を表示するかは開発者次第です (もしある場合)。
| 値の名前 | 値の型 | 説明 | 必須 |
|---|---|---|---|
| エラー | string | 発生したエラーの種類を分類するために使用できるエラー コード文字列。 | はい |
| error_description | string | エラーの根本原因が特定しやすくなる具体的なエラー メッセージ。 | いいえ |
| error_code | integer | 問題点の診断に役立つその他のエラー コード。 | いいえ |
| http_status_code | integer | このエラー応答で返された HTTP 状態コード。 | いいえ |
| retry_timeout | integer | プリンターが要求を再試行する前に待機する秒数。 | いいえ |
上記の各 API では、考えられるエラー コード文字列が一覧表示されます。
2.1 応答の例
{
"error": "invalid_request",
"error_description": "Missing required field device_type"
}
プリンター登録後のユニバーサル プリント サービスとの接続
ユニバーサル プリントでは、PWG 5100.18 (IPP Infra) で定義されている必要な機能がサポートされています。 ユニバーサル プリント対応プリンターでは、プリンターの登録プロセスが完了したら、このプロトコルを使用してユニバーサル プリントと通信することが期待されます。 呼び出し元がアクセス権を持つプリンターであることを確認するために、プリンターは、「プリンター アクセス トークンの取得」で説明されているように、HTTP Authorization ヘッダーのベアラー値としてデバイス アクセス トークンを使用します。