Príklady rozšíreného dopytovania REST API ABRA Gen

Ďalej sú uvedené príklady pre rozšírené dopytovanie - JSON dokument (v tele POST požiadavky).

Rozšírené dopytovanie sa od základného líši formou vstupných dát (dopytu) a spôsobom ich odovzdávania. Dopyt sa odovzdáva v podobe JSON dokumentu (tzv. dopytový objekt) v tele HTTP POST požiadavky.

Sú dva druhy resourcov (zdrojov), na ktorých je možné rozšírené dopytovanie použiť:

  • Prvým variantom je zaslanie HTTP požiadavky na subresource kolekcie BO /{connection}/{kolekce BO}/query, potom nie je nutné uvádzať vlastnosť class (je známa vďaka nadradenej kolekcii BO).
  • Druhým variantom je zaslanie HTTP požiadavky na všeobecný resource pre rozšírené dopytovanie /{connection}/query, potom je nutné uvádzať vlastnosť class (kvôli všeobecnej povahe zdroja nie je známa).

Pri príkladoch je predpokladané odosielanie na všeobecný resource pre rozšírené dopytovanie, vlastnosť objektu dopytu class je teda vždy špecifikovaná.

Parameter /query vykonáva dopyt na základe práv užívateľa v závislosti na triede (class), nad ktorou dopyt beží.

  • Trieda s BO kontrolerom - Práva sa vyhodnocujú podľa kontrolera spojeného s touto triedou (napr. issuedinvoices).
  • Trieda bez BO kontrolera - Práva sa overujú na základe sprístupnenia položiek pre API. Pokiaľ nie je možné nastaviť oprávnenie k spusteniu dopytu, dopyt nebude realizovaný.

Užívatelia majú právo spúšťať dopyty (opRun) na vybrané položky. Prístup k ďalším položkám sa nastavuje v agende Sprístupnenie položiek pre API.

Ide o objekt, ktorý obsahuje dopyt (platí i pre vnorené dopyty).

Dopytový objekt
Vlastnosť JSON typ Význam
class string Identifikátor kolekcie, nad ktorou je dopyt vykonávaný
select array Vlastný dopyt, viac viď klauzula select
where string Obmedzenie kolekcie, viac viď klauzula where
groupby string Agregácia kolekcie, viac viď klauzula groupby
orderby array Radenie kolekcie, viac viď klauzula orderby

Ide o objekt, ktorý je možné použiť v klauzule select rozšíreného variantu dopytovania.

Výrazový objekt
Vlastnosť JSON typ Význam
name string Názov fieldu vo výslednom objekte.
value string/array/object
string Výraz, ktorý je vyhodnotený do výslednej hodnoty.
array Pole obsahujúce reťazce s výrazmi, ktoré sú vyhodnotené do výslednej hodnoty.
object Objekt môže mať tri rôzne typy:
  • dopytovaný objekt - pri použití dopytovaného objektu ide o vnorený dopyt, možnosť dostupnú len v rozšírenom variante dopytovania
  • array - pokiaľ je vo vlastnosti name nadradeného výrazového objektu uvedený field BO odkazujúci na iný BO alebo kolekciu BO, obsahuje fieldy odkazovaného BO, ktoré majú byť zahrnuté do výsledku dopytu
  • špecifikačný objekt - pokiaľ vlastnosť name nadradeného výrazového objektu nezodpovedá názvu fieldu BO odkazujúceho na iný BO alebo kolekciu BO (ktorý chceme pod zvolený názov dosadiť) ako v prechádzajúcom prípade, umožňuje špecifikovať field BO, z ktorého bude výsledná hodnota čerpaná, vrátane konkrétnych fieldov odkazovaného BO (viď tabuľka Špecifikačný objekt)
Špecifikačný objekt
Vlastnosť JSON typ Význam
field string Názov fieldu BO, z ktorého sa vychádza.
query object Objekt obsahujúci vlastnosť select, ktorých hodnotou je pole výrazov, ktoré sú zahrnuté do výsledku dopytu.

Klauzula select sa v rozšírenom variante dopytovania používa i namiesto klauzuly expand (expand v rozšírenom variante nie je).

Výber kolekcie faktúr, každý objekt faktúry bude obsahovať ID, sumu (Amount) a DisplayName, ktoré je zložené pomocou polí načítaných z previazaných objektov. Ide o rýchlejší variant ako je uvedený v prvom príklade, v ktorom je použitá neperzistentná položka (DisplayName); ako už bolo spomenuté vyššie, neperzistentné položky znamenajú degradáciu výkonu.

Klauzula select je v rozšírenom variante dopytovania reprezentovaná JSON poľom obsahujúcim jednotlivé požadované fieldy. Fieldy samotné sú reprezentované buď reťazcom obsahujúcim výraz alebo výrazovým objektom.

POST http://localhost:81/data/query

Telo požiadavky:

{
  "class": "issuedinvoices",
  "select": [
	"ID",
	"Amount",
	{ "name": "DocNumber", "value": "DocQueue_ID.Code || '-' || OrdNumber || '/' || Period_ID.Code" }
  ]
}

Výber z agendy Adresár firiem, pre výber fieldu FirmOffices je využitý výrazový objekt, pre výber bankových účtov (field BankAccounts, na BO firmy sú bank. účty vedené ako riadky Rows) je naviac použitý špecifikačný objekt. 

POST http://localhost:81/data/query

Telo požiadavky:

{
  "class": "firms",
  "select": [
	"ID",
	"Code",
	"Name",
	{ "name": "FirmOffices",
	  "value": ["Name"]
	},
	{ "name": "BankAccounts",
	  "value": {
	  "field": "Rows",
	  "query": {
		"select": ["ID", "Name", "BankAccount"]
	  }
	}
  }
 ]
}

Výber kolekcie cenníkov, ku každému cenníku je vo výsledku dopytu zahrnutý zoznam firiem, ktoré ho majú nastavený. Ide o ukážku použitia výrazového objektu v rámci selectu, možnosti využiteľnej len v rozšírenom variante dopytovania. Všimnite si v klauzule where vnoreného výrazového objektu použitie :ID - referencia na field nadradeného BO v poddopyte. Pomocou takejto syntaxi (:{názov fieldu BO z nadradeného dopytu}) je možné do obmedzenia (where) poddopytu dosadzovať kontextuálne hodnoty z nadradeného dopytu (len z nadradeného dopytu). Táto možnosť je dôležitá vo chvíli, kedy je potrebné filtrovať za vopred neznámej hodnoty. (Viac viď Klauzula where s kontextuálnymi parametrami.) 

POST http://localhost:81/data/query

Telo požiadavky:

{
  "class": "pricelists",
  "select": [
	"ID", 
	"Code", 
	"Name",
	{
	  "name": "Firms",
	  "value":
	  {
		"class": "firms",
		"select": ["ID", "Code", "Name"],
		"where": "PriceList_ID = :ID"
	 }
     }
  ]
}

Klauzula where má v rozšírenom variante dopytovania podobnú sémantiku ako where v základnej forme dopytovania. Výraz pre určenie platnosti sa zapisuje do reťazcovej hodnoty vlastnosti where dopytovaného objektu.

Klauzula where môže obsahovať kontextuálne parametre, ktoré umožňujú dosadzovať hodnoty z nadradeného dopytu. Kontextuálne parametre sú identifikované pomocou špeciálnej "dvojbodkovej“ syntaxe:

:{názov fieldu BO z nadradeného dopytu}

Je tiež možné využívať kontextuálne parametre v bodkovej notácii. Ďalej je možné vytvárať užívateľsky pomenované kontextuálne parametre, ktoré môžu zjednodušiť tvorbu a čitateľnosť zložitejších dopytov.

POST http://localhost:81/data/query

Telo požiadavky:

{
    "class": "StoreSubcards",
    "select": [
      "Storecard_ID.code",
      { "name": "superid", "value": "Storecard_ID.ID" },
      {
        "name": "cards",
        "value": {
          "class": "StoreCards",
          "select": [
            { "name": "code", "value": "code" }
          ],
          "where": "code=:Storecard_ID.code and id=:superid"
        }
      }
    ],
    "orderby": "Storecard_ID.Code"
}

Klauzula orderby slúži na radenie výstupu rovnakým spôsobom ako v SQL. Radenie sa špecifikuje vo vlastnosti orderbydopytového objektu. Hodnotou tejto vlastnosti je JSON pole, ktoré môže obsahovať reťazce obsahujúce výrazy pre radenie, alebo objekty radenia (objekt radenia je nutné použiť v situácii, kedy chceme radiť zostupne - východiskové radenie je vzostupné).

Objekt radenia
Vlastnosť JSON typ Výraz
value string Výraz pre radenie
desc boolean Indikácia, či je radenie zostupné (true = zostupné; false = vzostupné)

Výber kolekcie faktúr vydaných, každý objekt faktúry obsahuje sumu (Amount) a objekt firmy, na ktorú je faktúra vystavená (Firm_ID). Faktúry sú radené podľa kódu firmy, na ktorú sú vystavené vzostupne, a následne podľa sumy zostupne. 

POST http://localhost:81/data/query

Telo požiadavky:

{
  "class": "issuedinvoices",
  "select": [
	"Amount", 
	{
	  "name": "Firm_ID",
	  "value":
	  {
		"select": ["ID", "Code", "Name"]
	  }
   }
],
	"orderby": [
	  "Firm_ID.Code",
	  { "value": "Amount", "desc": true }
]
}

Klauzula groupby má v rozšírenom variante dopytovania rovnakú sémantiku ako groupby v základnej forme dopytovania. Výraz pre agregáciu sa zapisuje do reťazcovej hodnoty vlastnosti groupby dopytového objektu.

Získanie trojice firiem s najväčšou celkovou fakturovanou sumou (Amount). Firmy sú zoradené podľa tejto celkovej sumy zostupne (ukážka použitia kombinácie klauzulí orderby, groupby a take).

POST http://localhost:81/data/issuedinvoices/query

Telo požiadavky:

{
	"select": [
		{ "name": "Amount", "value": "Sum(Amount)" },
		{
			"name": "Firm_ID",
			"value":
				{
					"select": ["ID", "Code", "Name"]
				}
		}
	],
	"orderby": [
		{ "value": "Sum(Amount)", "desc": true }
	],
	"groupby": [
		"Firm_ID"
	],
	"take": 3
}