Udostępnij za pośrednictwem

Rejestracja drukarki universal print (UP)

1. Rejestracja

1.1 Przepływ

Przepływ rejestracji

1.2 Interfejsy API

Następujące interfejsy API są dostępne w globalnej usłudze rejestracji UP na potrzeby rejestrowania drukarek. Globalny adres URL bazy usługi rejestracji UP: https://register.print.microsoft.com

Pełny adres URL będzie kombinacją globalnego podstawowego adresu URL i poniższych punktów końcowych.

1.2.1 /register

Punkt końcowy /register służy do rejestrowania drukarki. Rejestracja składa się z 2 etapów.

  1. Początkowe wywołanie rejestracji w celu zarejestrowania drukarki

  2. Sondowanie stanu rejestracji w celu ukończenia żądania rejestracji

1.2.1.1 Inicjowanie rejestracji

Pierwszym etapem jest zainicjowanie żądania rejestracji za pomocą globalnej usługi rejestracji. Odbywa się to przez wysłanie żądania POST do punktu końcowego /register z ładunkiem rejestracji w formacie JSON.

1.2.1.1.1.1 Żądanie HTTP
POST /api/{version}/register

{version} jest wersją interfejsu API/protokołu rejestracji UP używanego przez drukarkę. Obecnie obsługiwane wersje to:

  • Wersja 1.0
1.2.1.1.2 Nagłówki żądań

Dla wersji 1.0:

Nazwa/nazwisko opis
Autoryzacja Element nośny {token} jest wymagany. Drukarka musi zalogować się do administratora w usłudze Microsoft Entra ID, postępując zgodnie z przepływem kodu urządzenia lub innym przepływem autoryzacji.
1.2.1.1.3 Żądanie typu zawartości
  • application/json
1.2.1.1.4 Ładunek żądania

Ładunek żądania rejestracji będzie mieć format JSON z następującymi wartościami (wielkość liter jest rozróżniana):

Nazwa wartości Typ wartości opis Wymagania
nazwa string Przyjazna nazwa drukarki. Tak
manufacturer string Producent drukarki. Tak
model string Model drukarki. Tak
device_id string Identyfikator UUID urządzenia fizycznego drukarki. Tak
device_type string Typ urządzenia. Obsługiwane wartości (bez cudzysłowów): "drukarka" Tak
certificate_request DeviceCertRequest , obiekt Żądanie podpisania certyfikatu X.509 (CSR) dla certyfikatu utworzonego i użytego przez drukarkę do zidentyfikowania się. Zapoznaj się z dodatkiem A.1, aby zapoznać się z przykładem kodowania, aby dowiedzieć się, jak utworzyć csr za pomocą biblioteki BouncyCastle .NET. Tak

Obiekt DeviceCertRequest ma następujące wartości (z uwzględnieniem wielkości liter):

Nazwa wartości Typ wartości opis Wymagania
type string Właściwość, która MUSI zawierać wartość "pkcs10". Tak
dane string Właściwość zawierająca żądanie certyfikatu PKCS#10 zakodowane w formacie base64 RFC4211. Żądanie certyfikatu MUSI używać algorytmu klucza publicznego RSA z kluczem 2048-bitowym, algorytmem SHA256WithRSAEncryption i algorytmem wyznaczania wartości skrótu SHA256. Tak
transport_key string Część publiczna zakodowana w formacie base64 klucza asymetrycznego, która jest generowana przez klienta. Tak
1.2.1.1.5 Pomyślna odpowiedź

W przypadku powodzenia (zaakceptowane 202) ładunek odpowiedzi rejestracji będzie w formacie JSON z następującymi wartościami (wielkość liter jest uwzględniana):

Nazwa wartości Typ wartości opis Wymagania
registration_id string Unikatowy identyfikator reprezentujący to żądanie rejestracji. Będzie to używane podczas sondowania stanu rejestracji. Tak
interval integer Czas sondowania (w sekundach) w celu sprawdzenia ukończenia żądania rejestracji. Tak
1.2.1.1.6 Odpowiedź na błąd

Po błędzie zostaną zwrócone następujące kody stanu HTTP wraz z ładunkiem odpowiedzi na błąd. Ładunek odpowiedzi o błędzie będzie zawierać obiekt JSON błędu zgodnie z formatem w sekcji 2.

Kody stanu HTTP

Kod stanu HTTP opis
400 (Nieprawidłowe żądanie) Żądanie jest nieprawidłowe lub źle sformułowane. Aby uzyskać szczegółowe informacje, zobacz ładunek odpowiedzi na błędy. Napraw i wyślij ponownie żądanie.
500 (Wewnętrzny błąd serwera) Wystąpił błąd wewnętrzny w usłudze. Aby uzyskać szczegółowe informacje, zobacz ładunek odpowiedzi na błędy. Ponów próbę żądania (jeśli to możliwe, zostanie ustawiona retry_timeout).

Kody błędów

Kody błędów opis Kod stanu HTTP
invalid_request Ładunek żądania rejestracji był źle sformułowany/nieprawidłowy. Zwykle występuje to na etapach programowania. Aby uzyskać więcej informacji, zobacz error_description. 400
device_code_error Usługa nie może wygenerować pary Kod urządzenia/użytkownika. 500
storage_error Usługa napotkała błąd z magazynem zaplecza. 500
service_error Wystąpił błąd w usłudze. Aby uzyskać więcej informacji, zobacz error_description. 500
Przykłady 1.2.1.1.7
1.2.1.1.7.5 Żądanie w wersji 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 Odpowiedź w wersji 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 Uzyskiwanie stanu rejestracji

Po pomyślnym zaakceptowaniu żądania rejestracji drukarka będzie sondowała /register punkt końcowy pod kątem stanu żądania rejestracji. Drukarka powinna sondować na podstawie wartości interwału otrzymanej w odpowiedzi rejestracji i musi podać odebrane registration_id .

1.2.1.2.1 Żądanie HTTP
GET /api/{version}/register?{Query Parameters}

{version} jest wersją interfejsu API/protokołu rejestracji UP używanego przez drukarkę.
Obecnie obsługiwane wersje to:

  • Wersja 1.0

{Query Parameters} są określone w następnej sekcji.

1.2.1.2.2 Nagłówki żądań

Dla wersji 1.0:

Nazwa/nazwisko opis
Autoryzacja Element nośny {token} jest wymagany. Drukarka musi zalogować się do administratora w usłudze Microsoft Entra ID lub postępować zgodnie z przepływem kodu urządzenia. Można użyć tego samego tokenu uzyskanego dla pierwszego żądania rejestracji.
1.2.1.2.3 Parametry zapytania żądania
Nazwa parametru opis Wymagania
registration_id Identyfikator rejestracji otrzymany od odpowiedzi żądania rejestracji. Tak
1.2.1.2.4 Pomyślne odpowiedzi

Następujące kody stanu HTTP zostaną zwrócone dla następujących scenariuszy "powodzenia":

Kod stanu HTTP Faza rejestracji
200 (OK) Rejestracja zakończona
202 (zaakceptowane) Rejestracja w toku — wyślij kolejne żądanie po upływie interwału

Ładunki odpowiedzi

Rejestracja w toku (zaakceptowano 202):

Ładunek odpowiedzi rejestracji będzie mieć format JSON z następującymi wartościami (wielkość liter jest rozróżniana):

Nazwa wartości Typ wartości opis Wymagania
interval integer Czas sondowania (w sekundach) w celu sprawdzenia ukończenia żądania rejestracji. Należy pamiętać, że czas interwału sondowania nie będzie taki sam za każdym razem. Tak

Rejestracja zakończona (200 OK):

Ładunek odpowiedzi rejestracji będzie mieć format JSON z następującymi wartościami (wielkość liter jest rozróżniana):

Nazwa wartości Typ wartości opis Wymagania
cloud_device_id string Identyfikator UUID drukarki w chmurze reprezentowany przez tę drukarkę. Tak
certyfikat string Certyfikat X.509 zakodowany w formacie Base64. Tak
print_svc_url string Adres URL usługi Universal Print (UP), która obsługuje operacje drukarki. Tak
notification_url string Adres URL, który powinien być używany przez drukarkę do nasłuchiwania powiadomień (nowe zadanie drukowania, anulowanie zadania drukowania itp.). Tak
mcp_svc_resource_id string Identyfikator zasobu usługi UP. Wymagane podczas żądania tokenu OAuth na potrzeby komunikacji z usługami powiadomień UP i UP. Tak
device_token_url string Adres URL bezpiecznego urzędu tokenu (STA), którego drukarka powinna używać do pobierania tokenów dla usług powiadomień UP i UP. Tak
1.2.1.2.5 Odpowiedź na błąd

Po błędzie zostaną zwrócone następujące kody stanu HTTP wraz z ładunkiem odpowiedzi na błąd. Ładunek odpowiedzi o błędzie będzie zawierać obiekt JSON błędu zgodnie z formatem w sekcji 2.

Kody stanu HTTP

Kod stanu HTTP opis
400 (Nieprawidłowe żądanie) Żądanie jest nieprawidłowe lub źle sformułowane. Aby uzyskać szczegółowe informacje, zobacz ładunek odpowiedzi na błędy. Rejestracja powinna zostać ponownie uruchomiona.
500 (Wewnętrzny błąd serwera) Wystąpił błąd wewnętrzny w usłudze. Aby uzyskać szczegółowe informacje, zobacz ładunek odpowiedzi na błędy. Rejestracja powinna zostać ponownie uruchomiona.

Kody błędów

Kody błędów opis Kod stanu HTTP
invalid_registration_id Podany identyfikator rejestracji jest nieprawidłowy. Może się tak zdarzyć, jeśli identyfikator rejestracji został zapisany niepoprawnie lub jeśli rejestracja drukarki nie została ukończona w ramach limitu czasu rejestracji. Rejestracja powinna zostać ponownie uruchomiona. 400
device_already_exists Zarejestrowane urządzenie jest już zarejestrowane. Administrator powinien sprawdzić portal UP, aby sprawdzić, czy zarejestrowane urządzenie jest obecne. Jeśli tak jest, może to być nieaktualny wpis, że administrator zapomniał usunąć/wyrejestrować. Rejestracja powinna zostać ponownie uruchomiona. 400
user_token_error Usługa nie może pobrać tokenu użytkownika do przeprowadzenia rejestracji. Rejestracja powinna zostać ponownie uruchomiona. 500
storage_error Usługa napotkała błąd z magazynem zaplecza. Rejestracja powinna zostać ponownie uruchomiona. 500
service_error Wystąpił błąd w usłudze. Aby uzyskać więcej informacji, zobacz error_description. Rejestracja powinna zostać ponownie uruchomiona. 500
1.2.1.2.6 Przykłady
1.2.1.2.6.3 Żądanie w wersji 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 W toku Odpowiedź w toku 1.0
HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache

{
  "interval": 15
}
1.2.1.2.6.7 Ukończono odpowiedź w wersji 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 Uwierzytelnianie

Przed zarejestrowaniem drukarki należy uwierzytelnić administratora w usłudze Microsoft Entra ID, postępując zgodnie z przepływem kodu urządzenia lub innym przepływem autoryzacji. Uzyskany token dostępu administratora drukarki musi zostać wysłany w nagłówku autoryzacji żądania zarejestrowania drukarki. Dokumentację kodu urządzenia i innych przepływów uwierzytelniania obsługiwanych przez identyfikator Entra firmy Microsoft można znaleźć w artykule Obsługiwane przepływy uwierzytelniania.

1.2.1.3.1 Parametry przepływu kodu urządzenia

Dokumentację obsługi identyfikatora entra firmy Microsoft przepływu kodu urządzenia można znaleźć w artykule OAuth 2.0 device code flow (Przepływ kodu urządzenia OAuth 2.0). Poniższa client_id tabela jest tymczasowa. W najbliższej przyszłości udostępnimy dodatkowe informacje.

Nazwa parametru opis Wymagania
tenant Użyj parametru "Organizacje" dla parametru dzierżawy. Tak
client_id Użyj registered client ID polecenia dla client_id. Dodatkowe informacje na stronie Rejestrowanie klienta OEM. Tak
zakres Użyj https://print.print.microsoft.com/.default dla zakresu Tak
1.2.1.3.2 Przykładowe żądania przepływu kodu urządzenia
1.2.1.3.2.1 Inicjowanie przepływu kodu urządzenia

Żądanie:

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

Reakcja:

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 Pobieranie tokenu użytkownika

Żądanie:

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

Odpowiedź: authorization_pendingużytkownik nie zalogował się jeszcze.

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
}

Odpowiedź: successużytkownik zalogował się, zwracany jest token. Ten token może być używany w wymaganym nagłówku autoryzacji (opisanym w sekcji 1.2.1.1.2) podczas wysyłania żądania zarejestrowania drukarki w usłudze 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. Struktura odpowiedzi na błędy

W przypadku powyższych interfejsów API po błędzie następująca struktura błędów zostanie zwrócona w ładunku w formacie JSON z następującymi wartościami (z uwzględnieniem wielkości liter). Te odpowiedzi na błędy są przeznaczone głównie do celów programistycznych i zależy od dewelopera, co należy pokazać użytkownikowi, jeśli w ogóle.

Nazwa wartości Typ wartości opis Wymagania
error string Ciąg kodu błędu używany do klasyfikowania typu błędu, który wystąpił. Tak
error_description string Określony komunikat o błędzie, który może pomóc w tożsamości głównej przyczyny błędu. Nie.
error_code integer Dodatkowy kod błędu, który może pomóc zdiagnozować problem. Nie.
http_status_code integer Kod stanu HTTP zwrócony z tą odpowiedzią o błędzie. Nie.
retry_timeout integer Liczba sekund oczekiwania drukarki przed ponowną próbą żądania. Nie.

Każdy powyższy interfejs API wyświetli listę możliwych ciągów kodu błędu.

2.1 Przykładowa odpowiedź

{
  "error": "invalid_request",
  "error_description": "Missing required field device_type"
}

Łączność z usługą Universal Print po rejestracji drukarki

Usługa Universal Print obsługuje wymagane funkcje zdefiniowane w programie PWG 5100.18 (IPP Infra). Drukarki gotowe do drukowania uniwersalnego powinny używać tego protokołu do komunikacji z usługą Universal Print po zakończeniu procesu rejestracji drukarki. Aby upewnić się, że obiekt wywołujący jest drukarką z dostępem, drukarka będzie używać tokenu dostępu urządzenia zgodnie z opisem w sekcji Pobieranie tokenu dostępu drukarki jako wartość elementu nośnego dla nagłówka HTTP Authorization .