Oracle APEX 4.2 – APEX_IR API

apex

Wraz z najnowszą wersją Oracle APEX 4.2 otrzymaliśmy prostszą komunikację z raportami interaktywnymi za pośrednictwem api APEX_IR. Przed wersją 4.2 za komunikację z raportami interaktywnymi odpowiadały procedury z pakietu APEX_UTIL. W wersji 4.2 pakiet APEX_UTIL został wyczyszczony ze wszystkich tego typu funkcji. Powstał za to dedykowany pakiet APEX_IR. Zawiera on procedury, które ułatwiają operacje na raporcie oraz pozyskiwanie zapytania na jakim oparty jest raport. W swoim artykule przedstawię najważniejsze funkcjonalności dostarczane poprzez api APEX_IR.

Dostarczany w APEX 4.2 pakiet APEX_IR pozwala na następujące operacje:

  • dodanie filtrów do raportu interaktywnego,
  • wyczyszczenie ustawień raportu,
  • zmianę języka subskrypcji,
  • usunięcie raportu,
  • usunięcie subskrypcji,
  • pobranie szczegółowych danych o raporcie, w tym zapytania, na jakich się opiera,
  • pobranie identyfikatora ostatnio wyświetlanego raportu,
  • przywrócenie raportu do ustawień domyślnych.

Aby zaprezentować możliwości pakietu APEX_IR, stworzyłem prostą aplikację. Zawiera ona raport interaktywny oparty na poniższym zapytaniu.

1
2
3
4
5
6
7
8
9
10
11
SELECT emp.empno,
       emp.ename,
       emp.job,
       emp.mgr,
       emp.hiredate,
       emp.sal,
       emp.deptno,
       dept.dname,
       dept.loc
FROM scott.emp emp
LEFT OUTER JOIN scott.dept dept ON dept.deptno=emp.deptno

Raport interaktywny oparty na zapytaniu

Dodawanie filtrów do raportu

Za dodawanie filtrów do raportu odpowiadają dwie procedury:

  1. z wykorzystaniem identyfikatora raportu
    1
    2
    3
    4
    5
    6
    7
    APEX_IR.ADD_FILTER(
        p_page_id       IN NUMBER,
        p_region_id     IN NUMBER,
        p_report_column IN VARCHAR2,
        p_filter_value  IN VARCHAR2,
        p_operator_abbr IN VARCHAR2 DEFAULT NULL,
        p_report_id     IN NUMBER DEFAULT NULL);
  2. z wykorzystaniem aliasu raportu
    1
    2
    3
    4
    5
    6
    7
    APEX_IR.ADD_FILTER(
        p_page_id       IN NUMBER,
        p_region_id     IN NUMBER,
        p_report_column IN VARCHAR2,
        p_filter_value  IN VARCHAR2,
        p_operator_abbr IN VARCHAR2 DEFAULT NULL,
        p_report_alias  IN VARCHAR2 DEFAULT NULL);

Jeżeli nie przekażemy parametrów p_report_id lub p_report_alias, filtry zostaną dodane do ostatnio wyświetlanego raportu w regionie o przekazanym ID. Natomiast aby pobrać identyfikator regionu, w którym znajduje się raport interaktywny, musimy wykonać następujące zapytanie.

1
2
3
4
SELECT interactive_report_id,region_id
FROM apex_application_page_ir
WHERE application_id = :APP_ID
  AND page_id = :APP_PAGE_ID;

:APP_ID – identyfikator aplikacji
:APP_PAGE_ID – identyfikator strony

Jako przykład dodamy do raportu filtr na kolumnie „JOB“. Do naszej strony dodajemy przycisk, który wykonuje procedurę. Parametr p_operator_abbr określa typ filtru i został szczegółowo opisany w dokumentacji. Aby nadać filtr sprawdzający, czy wartość kolumny jest równa wartości, parametr przyjmuje wartość „EQ“ od „equals“.

1
2
3
4
5
6
7
APEX_IR.ADD_FILTER(
p_page_id => :APP_PAGE_ID,
p_region_id => id regionu,
p_report_column => 'JOB',
p_filter_value => 'MANAGER',
p_operator_abbr => 'EQ',
p_report_id => null);

Po wykonaniu procedury do naszego raportu został dodany filtr.

Pobranie danych o raporcie

Do pobrania szczegółowych danych o raporcie służy funkcja APEX_IR.GET_REPORT. Zwraca ona rekord typu T_REPORT, który zawiera w sobie:

  • SQL_QUERY – zmienną tekstową przechowującą zapytanie, na którym został oparty raport,
  • BINDS – kolekcję wartości przekazanych do zapytania.
1
2
3
4
APEX_IR.GET_REPORT(
    p_page_id   IN NUMBER,
    p_region_id IN NUMBER,
    p_report_id IN NUMBER DEFAULT NULL);

W funkcji tej możemy pominąć parametr p_report_id, co sprawi, że uzyskamy dane o ostatnio wyświetlanym raporcie. Dane o regionie pobieramy tak samo, jak w punkcie pierwszym. Zapytanie, na którym został oparty raport interaktywny przed wprowadzeniem filtrów, wygląda następująco:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
SELECT "EMPNO",
       "ENAME",
       "JOB",
       "MGR",
       "HIREDATE",
       "SAL",
       "DEPTNO",
       "DNAME",
       "LOC"
FROM
  (SELECT *
   FROM
     (SELECT emp.empno,
             emp.ename,
             emp.job,
             emp.mgr,
             emp.hiredate,
             emp.sal,
             emp.deptno,
             dept.dname,
             dept.loc
      FROM scott.emp emp
      LEFT OUTER JOIN scott.dept dept ON dept.deptno=emp.deptno) r) r
WHERE rownum <= to_number(:APXWS_MAX_ROW_CNT)

Binds:
APXWS_MAX_ROW_CNT=1000000

Po zastosowaniu filtru z punktu pierwszego:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
SELECT "EMPNO",
       "ENAME",
       "JOB",
       "MGR",
       "HIREDATE",
       "SAL",
       "DEPTNO",
       "DNAME",
       "LOC"
FROM
  (SELECT *
   FROM
     (SELECT emp.empno,
             emp.ename,
             emp.job,
             emp.mgr,
             emp.hiredate,
             emp.sal,
             emp.deptno,
             dept.dname,
             dept.loc
      FROM scott.emp emp
      LEFT OUTER JOIN scott.dept dept ON dept.deptno=emp.deptno) r
   WHERE ("JOB" = :APXWS_EXPR_1)) r
WHERE rownum <= to_number(:APXWS_MAX_ROW_CNT)

Binds:
APXWS_EXPR_1=MANAGER
APXWS_MAX_ROW_CNT=1000000

Nie trudno zauważyć, że w zapytaniu po zastosowaniu filtru pojawił się warunek „where“.

Funkcja APEX_IR.GET_REPORT pozwala łatwo pozyskać zapytanie, na jakim został oparty raport interaktywny, jednak ma swoje ograniczenia. W zwracanym przez funkcję zapytaniu uwzględniane są:

Kolejność kolumn TAK
Widoczne kolumny TAK
Sortowanie TAK
Filtrowanie TAK
Wyszukiwanie TAK
Agregacje TAK
Obliczenia TAK
Grupowanie NIE

Podsumowanie

Wprowadzone wraz z wersją APEX 4.2 api wspomagające komunikację z raportem interaktywnym znacznie ułatwia proces pozyskiwania danych o zapytaniu, na którym oparto raport. Pozwala też definiować filtry. Możliwość usunięcia raportu użytkownika lub przywrócenia go do ustawień deweloperskich znacznie ułatwia proces zarządzania raportami. Obsługa raportu interaktywnego za pomocą procedur pozwoli na uproszczenie aplikacji, które dotychczas używały filtrów definiowanych poprzez URL. Niestety dużym brakiem w API jest obsługa operacji grupowania (group by) w funkcji zwracającej zapytanie, na którym oparty jest raport.

Dodaj komentarz

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