Oracle APEX 4.2 – RESTful Web Services

apex_cloud_32

Podczas jednej z konferencji Gartner AADI w Las Vegas Daniel Sholler – dyrektor oraz analityk firmy Gartner, specjalizujący się w architekturze aplikacji, integracji oraz procesie wytwarzania aplikacji –powiedział: ”What we are seeing is that the design of APIs has become as important as the design of the user interface”. Usługi REST są dominującym trendem w projektowaniu API. W swoim artykule przedstawię, jak w prosty sposób możemy wytworzyć oraz obsługiwać usługi REST z aplikacji opartych na technologii APEX.

Wstęp

Korzystanie z usług REST w aplikacjach wytworzonych w technologii APEX wymaga użycia i poprawnego skonfigurowania Oracle APEX Listener w wersji 2.0 lub nowszej.

http://www.oracle.com/technetwork/developer-tools/apex-listener/overview/index.html

Aby aktywować usługi REST w naszej aplikacji, należy:

  1. w panelu administracyjnym APEX przejść do zakładki „Manage Instance” -> „Feature Configuration”;
  2. w zakładce „SQL Workshop” ustawić parametr „Enable RESTful Services” na „YES” (domyślnie ustawiony jest na „No”);
  3. zatwierdzić zmiany.

Udostępnianie danych raportów poprzez usługi REST

Na potrzeby prezentacji stworzymy raport interaktywny oparty na zapytaniu:

1
2
3
4
5
6
7
8
9
select e.ename    nazwa,
       e.job      stanowisko,
       e.hiredate data_zatrudnienia,
       e.sal      place,
       d.dname    biuro,
       d.loc      lokalizacja
  from emp e
  left outer join dept d
    on d.deptno = e.deptno


Aby udostępnić dane raportu jako usługę REST, należy:

  1. upublicznić stronę, na której znajduje się raport – w ustawieniach strony zmienić sposób autentyfikacji na „Page Is Public”;
  2. w konfiguracji raportu w sekcji „Attributes” nadać identyfikator statyczny raportu, np. „Pracownicy” oraz aktywować dostęp REST „Enable RESTful Access”;
  3. w regionie „Attributes” zostanie automatycznie wygenerowany link dostępu do danych raportu.
    1
    http://url/apex/apex_rest.getReport?app=103&page=1&reportid=Pracownicy

Domyślnie dane udostępniane są w formacie XML, ale możemy to zmienić za pomocą parametru „output”.

1
http://url/apex/apex_rest.getReport?app=103&page=1&reportid=Pracownicy&output=json

Listę parametrów, jakie możemy przekazać do usługi „apex_rest.getReport”, możemy znaleźć w dokumentacji:
http://docs.oracle.com/cd/E17556_01/doc/user.40/e15517/advnc.htm

Tworzenie usług REST

W celach prezentacyjnych stworzymy usługę zwracającą takie same dane jak w raporcie z punktu 1.

Aby stworzyć usługę REST, należy:

  1. przejść do zakładki „SQL Workshop” – > „RESTful Services”;
  2. w kolejnym kroku wybrać opcję „Create” i uzupełnić informację o tworzonej usłudze, tak jak na rysunku poniżej:

  3. zatwierdzić wprowadzone dane przyciskiem „Create module”.

Utworzona przez nas usługa jest dostępna pod adresem:

1
http://url/apex/pr/pracownicy

Aby do naszego przypadku dodać obsługę parametru, należy zmienić „URI Template” na „pracownicy/{id}”, a w „Source” dodać odpowiedni warunek „select * from emp e where e.empno=:id”.

Dane mogą być zwracane w formacie „JSON” lub „CSV”.
W analogiczny sposób możemy utworzyć metody „GET”, „DELETE”, „POST” i „PUT”.

Obsługa usług REST na przykładzie danych z raportu interaktywnego utworzonego w punkcie 1

Obsługa usług REST w APEX jak tak samo prosta, jak ich wytwarzanie. Aby zaprezentować ten proces wykorzystamy usługę przygotowaną w punkcie 1. Nasza usługa zwraca dane raportu interaktywnego opartego na zapytaniu:

1
2
3
4
5
6
7
8
9
select e.ename    nazwa,
       e.job      stanowisko,
       e.hiredate data_zatrudnienia,
       e.sal      place,
       d.dname    biuro,
       d.loc      lokalizacja
  from emp e
  left outer join dept d
    on d.deptno = e.deptno

Adres usługi:

1
http://url/apex/apex_rest.getReport?app=103&page=1&reportid=Pracownicy

Aby dodać do aplikacji obsługę usługi REST, należy:

  1. wybrać aplikację, w której chcemy wykorzystać usługę i przejść na zakładkę „Shared Components” -> „Web Service References”;
  2. w zakładce „Web Service References” dodać usługę, klikając w przycisk „Create”;
  3. wybrać typ usługi „REST”;
  4. w następnym kroku uzupełnić nazwę usługi oraz adres:
  5. uzupełnić parametry wejściowe: app, page, reportid;
  6. skonfigurować format zwracany przez usługę;
  7. stworzyć referencję do usługi i przejść do stworzenia raportu w oparciu dane usługi wybierając „Create Form & Report on Web Service”;
  8. wybrać stworzoną referencję do usługi:
  9. skonfigurować parametry strony, na której ma być umieszczony raport;
  10. ustawić nazwy i identyfikatory kontrolek przechowujących parametry wejściowe do usługi:
  11. wybrać, które parametry spośród dostarczanych przez usługę mają być wyświetlane na raporcie:
  12. do stworzonej strony przypisać zakładki i zakończyć proces.

Po przejściu całego procesu otrzymujemy stronę, na której umieszczona została formatka wyboru parametrów usługi oraz raport.

Podsumowanie

W swoim artykule zaprezentowałem, jak:

  • udostępnić dane z raportu interaktywnego jako usługę REST;
  • utworzyć usługę REST na podstawie zapytania SQL;
  • pobrać dane z gotowej usługi REST i wyświetlić na raporcie.

Obsługa usług REST w aplikacjach wykonanych z wykorzystaniem technologii APEX jest bardzo prosta, szybka i intuicyjna. Wystawienie usługi zwracającej wynik zapytania SQL sprowadza się do przygotowania samego zapytania. Udostępnienie danych raportu w postaci usługi REST poprzez zmianę jednego pola w konfiguracji raportu znacznie przyspiesza proces wytwórczy aplikacji. Dzięki tak prostemu modułowi obsługi usług REST bardzo łatwo możemy przygotować API naszej aplikacji.

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *