Rejestracja drukarki universal print (UP)
1. Rejestracja
1.1 Przepływ
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.
Początkowe wywołanie rejestracji w celu zarejestrowania drukarki
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_pending
uż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ź: success
uż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
.