Регистрация принтера универсальной печати (UP)
1. Регистрация
Поток 1.1
1.2 API
Следующие API доступны в службе глобальной регистрации UP для регистрации принтеров.
Базовый URL-адрес службы регистрации global UP: https://register.print.microsoft.com
Полный URL-адрес будет сочетанием глобального базового URL-адреса и конечных точек ниже.
1.2.1 /register
Конечная точка /register используется для регистрации принтера. Существует 2 этапа регистрации.
Начальный вызов регистрации для регистрации принтера
Состояние регистрации опроса для завершения запроса на регистрацию
Регистрация, инициируемая 1.2.1.1
Первым этапом является инициирование запроса на регистрацию с помощью глобальной службы регистрации. Это делается путем выдачи запроса POST в конечную точку /register с полезными данными регистрации в формате JSON.
1.2.1.1.1 HTTP-запрос
POST /api/{version}/register
{version} — это версия API регистрации UP или протокола, используемого принтером.
В настоящее время поддерживаются следующие версии:
- Версия 1.0
1.2.1.1.2 Заголовки запросов
Для версии 1.0:
| Имя | Описание |
|---|---|
| Авторизация | Носитель {token} Обязательный. Принтер должен выполнить вход администратора в идентификатор Microsoft Entra, следуя потоку кода устройства или другому потоку авторизации. |
1.2.1.1.3 Запрос типа контента
application/json
1.2.1.1.4 Запрос полезных данных
Полезные данные запроса на регистрацию будут использоваться в формате JSON со следующими значениями (с учетом регистра):
| Имя значения | Тип значения | Description | Обязательное поле |
|---|---|---|---|
| name | строка | Понятное имя принтера. | Да |
| manufacturer | строка | Производитель принтера. | Да |
| модель | строка | Модель принтера. | Да |
| device_id | строка | UUID физического устройства принтера. | Да |
| device_type | строка | Тип устройства. Поддерживаемые значения (без кавычки): "принтер" | Да |
| certificate_request | Объект DeviceCertRequest | Запрос на подпись сертификата X.509 (CSR) для сертификата, созданного и используемого принтером для идентификации себя. См. приложение A.1 для примера кода по созданию CSR с помощью библиотеки BouncyCastle .NET. | Да |
Объект DeviceCertRequest имеет следующие значения (учитывает регистр):
| Имя значения | Тип значения | Description | Обязательное поле |
|---|---|---|---|
| type | строка | Свойство, содержащее pkcs10. | Да |
| . | строка | Свойство, содержащее запрос сертификата в кодировке Base64 PKCS#10 RFC4211. Запрос сертификата должен использовать алгоритм открытого ключа RSA с 2048-разрядным ключом, алгоритмом подписи SHA256WithRSAEncryption и хэш-алгоритмом SHA256. | Да |
| transport_key | строка | Общедоступная часть асимметричного ключа в кодировке Base64, созданная клиентом. | Да |
1.2.1.1.5 Успешный ответ
При успешном выполнении (принято 202), полезные данные ответа регистрации будут в формате JSON со следующими значениями (учитывает регистр):
| Имя значения | Тип значения | Description | Обязательное поле |
|---|---|---|---|
| registration_id | строка | Уникальный идентификатор, представляющий этот запрос на регистрацию. Это будет использоваться при опросе состояния регистрации. | Да |
| interval | integer | Время опроса (в секундах) для проверки завершения запроса на регистрацию. | Да |
Ответ об ошибке 1.2.1.1.6
При ошибке будут возвращены следующие коды состояния HTTP вместе с полезными данными ответа об ошибке. Полезные данные ответа об ошибке будут содержать объект JSON ошибки после формата в разделе 2.
Коды состояния HTTP
| Код состояния HTTP | Description |
|---|---|
| 400 (недопустимый запрос) | Запрос является недопустимым или неправильным. Дополнительные сведения см. в полезных данных ответа об ошибке. Исправьте и повторно отправьте запрос. |
| 500 (внутренняя ошибка сервера) | Внутренняя ошибка произошла в службе. Дополнительные сведения см. в полезных данных ответа об ошибке. Повторите запрос (если это возможно, retry_timeout будет задано). |
Код ошибки
| Коды ошибок | Description | Код состояния 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 Запрос версии 1.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 Ответ версии 1.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} — это версия API регистрации UP или протокола, используемого принтером.
В настоящее время поддерживаются следующие версии:
- Версия 1.0
{Query Parameters} указаны в следующем разделе.
1.2.1.2.2. Заголовки запросов
Для версии 1.0:
| Имя | Описание |
|---|---|
| Авторизация | Носитель {token} Обязательный. Принтер должен войти в систему администратора в Microsoft Entra ID или следовать потоку кода устройства. Можно использовать тот же маркер, полученный для первого запроса на регистрацию. |
1.2.1.2.3 Запрос параметров запроса
| Наименование параметра | Description | Обязательное поле |
|---|---|---|
| registration_id | Идентификатор регистрации, полученный от ответа запроса на регистрацию. | Да |
1.2.1.2.4 Успешные ответы
Для следующих сценариев успешного выполнения будут возвращены следующие коды состояния HTTP:
| Код состояния HTTP | Этап регистрации |
|---|---|
| 200 OK; | Регистрация завершена |
| 202 Accepted (принято). | Регистрация во время выполнения. Выполните еще один запрос после прохождения интервала |
Полезные данные ответа
Регистрация выполняется (принято 202):
Полезные данные ответа регистрации будут использоваться в формате JSON со следующими значениями (с учетом регистра):
| Имя значения | Тип значения | Description | Обязательное поле |
|---|---|---|---|
| interval | integer | Время опроса (в секундах) для проверки завершения запроса на регистрацию. Обратите внимание, что интервал опроса не требуется каждый раз. | Да |
Регистрация завершена (200 ОК):
Полезные данные ответа регистрации будут использоваться в формате JSON со следующими значениями (с учетом регистра):
| Имя значения | Тип значения | Description | Обязательное поле |
|---|---|---|---|
| cloud_device_id | строка | Идентификатор UUID принтера в облаке, который представляет этот принтер. | Да |
| сертификат | строка | Сертификат X.509 с кодировкой Base64. | Да |
| print_svc_url | строка | URL-адрес службы универсальной печати (UP), обрабатывающей операции принтера. | Да |
| notification_url | строка | URL-адрес, который должен использоваться принтером для прослушивания уведомлений (новое задание печати, отмена задания печати и т. д.). | Да |
| mcp_svc_resource_id | строка | Идентификатор ресурса службы UP. Требуется при запросе маркера OAuth для обмена данными со службами уведомлений UP и UP. | Да |
| device_token_url | строка | URL-адрес центра безопасного маркера (STA), который принтер должен использовать для получения маркеров для служб уведомлений UP и UP. | Да |
Ответ об ошибке 1.2.1.2.5
При ошибке будут возвращены следующие коды состояния HTTP вместе с полезными данными ответа об ошибке. Полезные данные ответа об ошибке будут содержать объект JSON ошибки после формата в разделе 2.
Коды состояния HTTP
| Код состояния HTTP | Description |
|---|---|
| 400 (недопустимый запрос) | Запрос является недопустимым или неправильным. Дополнительные сведения см. в полезных данных ответа об ошибке. Регистрация должна быть повторно запущена. |
| 500 (внутренняя ошибка сервера) | Внутренняя ошибка произошла в службе. Дополнительные сведения см. в полезных данных ответа об ошибке. Регистрация должна быть повторно запущена. |
Код ошибки
| Коды ошибок | Description | Код состояния 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 Запрос версии 1.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 В ответе на ход выполнения версии 1.0
HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache
{
"interval": 15
}
1.2.1.2.6.7 Завершенный ответ версии 1.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, можно найти в поддерживаемых потоках проверки подлинности.
1.2.1.3.1 Параметры потока кода устройства
Документация по поддержке кода идентификатора Microsoft Entra для потока кода устройства см. в потоке кода устройства OAuth 2.0. Перечисленные client_id ниже являются временными. В ближайшее время мы предоставим дополнительную информацию.
| имени параметра | Description | Обязательное поле |
|---|---|---|
| tenant | Используйте "Организации" для параметра клиента. | Да |
| client_id | Используется registered client ID для client_id. Дополнительные сведения о регистрации OEM-клиента. |
Да |
| область | Использование 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 со следующими значениями (с учетом регистра). Эти ответы на ошибки в основном предназначены для разработки, и разработчик может показать пользователю, если что-нибудь.
| Имя значения | Тип значения | Description | Обязательное поле |
|---|---|---|---|
| error | строка | Строка кода ошибки, используемая для классификации типа ошибки, возникших. | Да |
| error_description | строка | Определенное сообщение об ошибке, которое может помочь удостоверению первопричины ошибки. | No |
| Error_Code | integer | Дополнительный код ошибки, который может помочь диагностировать проблему. | No |
| http_status_code | integer | Код состояния HTTP, возвращенный с помощью этого ответа об ошибке. | No |
| retry_timeout | integer | Количество секунд, которое должен ждать принтер, прежде чем повторить запрос. | No |
Каждый приведенный выше API выводит возможные строки кода ошибки.
Пример ответа 2.1
{
"error": "invalid_request",
"error_description": "Missing required field device_type"
}
Подключение к универсальной службе печати после регистрации принтера
Универсальная печать поддерживает необходимые функциональные возможности, определенные в PWG 5100.18 (IPP Infra). Ожидается, что принтеры универсальной печати будут использовать этот протокол для взаимодействия с универсальной печатью после завершения процесса регистрации принтера. Чтобы вызывающий объект был принтером с доступом, принтер будет использовать маркер доступа устройства, как описано в методе извлечения маркера доступа принтера, в качестве значения носителя заголовка HTTP Authorization .