Drukowanie za pomocą interfejsu REST API

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.

Proces drukowania za pomocą REST API

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:

  1. Klient tworzy szablony etykiet w aplikacji JustLabel i konfiguruje drukarki, nadając im nazwy. Automatycznie tworzona jest kolejka drukarki dla każdej dodanej drukarki.
  2. Dowolny system klienta (system ERP, system WMS, aplikacja niestandardowa itp.) jest konfigurowany do wysyłania żądań zawierających nazwę kolejki drukarki, nazwę szablonu etykiety i ciało JSON z danymi do miejsc na zmienniki.
  3. Aplikacja pobiera odpowiednie dane, odczytuje szablon etykiety, zastępuje dane JSON w odpowiednich miejscach, przekształca to wszystko w ostateczny kod ZPL i wysyła go do odpowiedniej drukarki przez sieć.

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.

Badanie punktów końcowych

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.

Przykładowy zestaw danych do samouczka

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.

  • host – nazwa (lub adres IP) maszyny, na której działa instancja JustLabel – nasz przykład: localhost
  • port – port instancji JustLabel – nasz przykład: 5987
  • printer – nazwa zdefiniowanej drukarki w zakładce Printers – nasz przykład: testPrinter
  • printer queue – nazwa kolejki drukarki, która domyślnie jest automatycznie tworzona w zakładce Printouts – nasz przykład: pq_testPrinter
  • template – nazwa szablonu etykiety, który chcemy wydrukować – nasz przykład: testTemplate
  • placeholders – nazwy zmienników używanych w szablonie – nasze przykładowe pary zmienników i wartości:
    • namePlaceholder = „The Name
    • descriptionPlaceholder = „The Description

Prosty punkt końcowy drukowania

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:

  1. Parametr ścieżki printerQueueName – nazwa kolejki drukarki, aby powiedzieć programowi, do której drukarki chcesz drukować. Nasz przykład: pq_testPrinter
  2. Parametr zapytania templateName – nazwa szablonu, który ma zostać wydrukowany. Nasz przykład: testTemplate
  3. 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",
  },
]

Standardowy punkt końcowy drukowania

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:

  1. Parametr ścieżki printerQueueName – nazwa kolejki drukarki, aby powiedzieć programowi, do której drukarki chcesz drukować. Nasz przykład: pq_testPrinter
  2. 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.

  • parametr zapytania templateName został tu uwzględniony w ciele JSON jako pole obiektu template i ma krótką nazwę name. W naszym przypadku przyjmie wartość testTemplate
  • pojawia się nowy parametr o nazwie numberOfCopies, który po prostu wskazuje, ile kopii etykiety chcesz wydrukować
  • w obiekcie 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"
        }
      }
    ]
  }
}

Drukowanie z surowymi danymi

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"
    }
  ]
}

Zabezpieczanie drukarek kluczem API

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.

Table of contents