Punkty końcowe drukowania interfejsu REST API to potężne narzędzie umożliwiające integrację aplikacji z dowolnym źródłem danych zdolnym do wysłania prostego żądania pod określony adres w sieci. Dzięki temu JustLabel może współpracować z systemem klienta niezależnie od języka jego implementacji i używanej architektury.
Aplikacja uruchomiona w wersji serwerowej lub na pulpicie dostarcza publiczne API umożliwiające integrację z dowolnym systemem klienta. W skrócie, proces drukowania wygląda następująco:
Należy zauważyć, że to rozwiązanie jest całkowicie niezależne od systemów operacyjnych klienta i serwera, języków programowania i fizycznego położenia urządzeń. Jedynym wymaganiem do drukowania jest możliwość połączenia wszystkich tych urządzeń z siecią Ethernet.
Możesz uzyskać dostęp do dokumentacji interfejsu REST API na stronie dokumentacji oraz bezpośrednio na maszynie lokalnej lub maszynie serwerowej uruchamiającej aplikację. Aby wyświetlić stronę dokumentacji dostarczoną przez aplikację, musisz znać adres hosta i numer portu działającej instancji JustLabel. Dla wersji desktopowej będzie to localhost:5987
. W dowolnej przeglądarce internetowej odwiedź podany adres z dodatkową ścieżką /swagger-ui/index.html
. Ostateczny adres dokumentacji dla wersji desktopowej powinien wyglądać tak:
http://localhost:5987/swagger-ui/index.html
W przykładach tego samouczka zakładamy wersję desktopową i używamy przedstawionego adresu. Jeśli aplikacja działa w wersji serwerowej, w powyższym adresie localhost:5987
należy zastąpić nazwą hosta lub adresem IP serwera oraz odpowiednim numerem portu.
Po odwiedzeniu tej strony powinna zostać wyświetlona treść podobna do przedstawionej poniżej. Zawiera opisy punktów końcowych interfejsu REST API i obiektów transferu danych (DTO).
Pamiętaj, że możesz testować punkty końcowe bezpośrednio z tej strony. Po prostu użyj przycisku Spróbuj teraz
na wybranym punkcie końcowym, wypełnij wszystkie niezbędne dane i naciśnij Uruchom
, aby wysłać żądanie.
Ten samouczek opiera się na wysoko spersonalizowanych ustawieniach. Użytkownik może korzystać z wersji desktopowej lub serwerowej programu, może mieć dowolne nazwy drukarek i kolejek drukarek, a także dowolne nazwy etykiet oraz zmienników. Dlatego musimy przygotować zestaw danych, na którym będziemy budować kolejne przykłady. Poniżej przedstawiamy zestaw przykładowych danych wraz z opisem poszczególnych elementów. Pozwoli to łatwo przenieść logikę przykładów do rzeczywistych przypadków użycia klienta.
localhost
5987
testPrinter
pq_testPrinter
testTemplate
namePlaceholder
= „The Name„descriptionPlaceholder
= „The Description„Punkt końcowy simple print
umożliwia użytkownikowi wydrukowanie jednej kopii etykiety z określonym szablonem i kolejką drukarki. Ścieżka punktu końcowego to
/simple-print/{printerQueueName}
Aby drukować za pomocą tego punktu końcowego, trzeba dostarczyć pewne części żądania:
printerQueueName
– nazwa kolejki drukarki, aby powiedzieć programowi, do której drukarki chcesz drukować. Nasz przykład: pq_testPrinter
templateName
– nazwa szablonu, który ma zostać wydrukowany. Nasz przykład: testTemplate
Ciało żądania
– obiekt ciała żądania JSON zawierający listę zmienników szablonu z parami nazwa i wartość, owiniętych w nawiasy kwadratowe: [ ]
. Nasze przykładowe zmienne to namePlaceholder
i descriptionPlaceholder
Ostateczne żądanie simple-print
dla naszych przykładowych danych powinno wyglądać tak:
URL
http://localhost:5987/simple-print/pq_testPrinter?templateName=testTemplate
JSON
[
{
"namePlaceholder": "The Name",
"descriptionPlaceholder": "The Description",
},
]
Punkt końcowy print
umożliwia użytkownikowi drukowanie wielu kopii etykiety za pomocą szablonu lub surowych danych. W tej sekcji omówimy wersję z użyciem szablonu. Ścieżka punktu końcowego to
/print/{printerQueueName}
Aby drukować za pomocą tego punktu końcowego, trzeba dostarczyć pewne części żądania:
printerQueueName
– nazwa kolejki drukarki, aby powiedzieć programowi, do której drukarki chcesz drukować. Nasz przykład: pq_testPrinter
Ciało żądania
– obiekt ciała żądania JSON zawierający niezbędne informacje do drukowania szablonu. Schemat ciała żądania dla wersji drukowania szablonu wygląda tak:{
"template": {
"name": "string",
"options": [
{
"numberOfCopies": 0,
"placeholderValues": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
]
}
}
Jak widać, ciało JSON jest nieco bardziej skomplikowane w tej wersji niż w przypadku simple-print
, ale łatwo zrozumiesz wszystko, patrząc na przykład uzupełniony naszymi przykładowymi danymi.
templateName
został tu uwzględniony w ciele JSON jako pole obiektu template
i ma krótką nazwę name
. W naszym przypadku przyjmie wartość testTemplate
numberOfCopies
, który po prostu wskazuje, ile kopii etykiety chcesz wydrukowaćplaceholderValues
możesz określić nazwy i wartości zmienników szablonu. W naszym przypadku będą to namePlaceholder
i descriptionPlaceholder
Ostateczna wersja żądania punktu końcowego print
wygląda tak:
URL
http://localhost:5987/print/pq_testPrinter
JSON
{
"template": {
"name": "testTemplate",
"options": [
{
"numberOfCopies": 1,
"placeholderValues": {
"namePlaceholder": "The Name",
"descriptionPlaceholder": "The Description"
}
}
]
}
}
Punkt końcowy print
opisany w poprzedniej sekcji umożliwia również drukowanie surowych danych. Oznacza to, że aplikacja nie modyfikuje dostarczonych danych, ale wysyła je bezpośrednio do drukarki. Kontynuując logikę z poprzedniego przykładu, musisz wskazać drukarkę przy użyciu parametru ścieżki, więc adres URL nie zmienia się, a nasza przykładowa kolejka drukarek to pq_testPrinter
:
URL
http://localhost:5987/print/pq_testPrinter
W ciele JSON jednak nie używasz obiektu template
. Zamiast tego powinieneś użyć obiektu raw
i wstaw kod ZPL jako wartość pola code
. Skorzystamy z kodu ZPL dla pustej etykiety, aby zademonstrować przykładowe ciało JSON z obiektem surowego kodu.
JSON
{
"raw": [
{
"numberOfCopies": 1,
"code": "^XA
^CI28
^PON
^BY2,3,0,10
^LH0,0
^FO10,10^A0N,30,30^FH^FD_53_6F_6D_65_20^FS
^XZ"
}
]
}
Czasami konieczne jest zapobieżenie niechcianym żądaniom drukowania. Wyobraź sobie sytuację, w której opracowałeś aplikację, która tworzy wydruki za pomocą interfejsu REST API, ale już utworzono nową wersję, a ty chcesz zablokować uprawnienia do drukowania wszystkim wcześniej wydanym programom, lub po prostu chcesz zapobiec nieautoryzowanym wydrukom z jakiegoś innego powodu.
Możesz to osiągnąć łatwo, zabezpieczając kolejkę drukarki za pomocą klucza API. Opis, jak to zrobić, znajdziesz w [tym samoucz
ku](/docs/tutorial/print-authorization).
Jeśli kolejka drukarki jest już zabezpieczona kluczem API, wydruki bez klucza autoryzacji zostaną odrzucone. Jeśli wymagana jest autoryzacja do drukowania, wartość klucza API powinna być dołączana do każdego żądania drukowania jako jedna z nagłówka o nazwie X-API-Key
.