Příklady rozšířeného dotazování REST API ABRA Gen

Dále jsou uvedeny příklady pro rozšířené dotazování - JSON dokument (v těle POST požadavku).

Rozšířené dotazování se od základního liší formou vstupních dat (dotazu) a způsobem jejich předávání. Dotaz je předáván v podobě JSON dokumentu (tzv. dotazový objekt) v těle HTTP POST požadavku.

Jsou dva druhy resourců (zdrojů), na kterých je možné rozšířené dotazování použít:

  • První variantou je zaslání HTTP požadavku na subresource kolekce BO /{connection}/{kolekce BO}/query, pak není nutné uvádět vlastnost class (je známa díky nadřízené kolekci BO).
  • Druhou variantou je zaslání HTTP požadavku na obecný resource pro rozšířené dotazování /{connection}/query, pak je nutné uvádět vlastnost class (kvůli obecné povaze zdroje není známa).

U příkladů je předpokládáno odesílání na obecný resource pro rozšířené dotazování, vlastnost objektu dotazu class je tedy vždy specifikována.

Parametr /query provádí dotaz na základě práv uživatele v závislosti na třídě (class), nad kterou dotaz běží.

  • Třída s BO kontrolerem - Práva se vyhodnocují podle kontroleru spojeného s touto třídou (např. issuedinvoices).
  • Třída bez BO kontroleru - Práva se ověřují na základě zpřístupnění položek pro API. Pokud nelze nastavit oprávnění ke spuštění dotazu, dotaz nebude proveden.

Uživatelé mají právo spouštět dotazy (opRun) na vybrané položky. Přístup k dalším položkám se nastavuje v agendě Zpřístupnění položek pro API.

Jedná se o objekt, který obsahuje dotaz (platí i pro vnořené dotazy).

Dotazový objekt
Vlastnost JSON typ Význam
class string Identifikátor kolekce, nad kterou je dotaz vykonáván
select array Vlastní dotaz, více viz klauzule select
where string Omezení kolekce, více viz klauzule where
groupby string Agregace kolekce, více viz klauzule groupby
orderby array Řazení kolekce, více viz klauzule orderby

Jedná se o objekt, který je možné použít v klauzuli select rozšířené varianty dotazování.

Výrazový objekt
Vlastnost JSON typ Význam
name string Název fieldu ve výsledném objektu.
value string/array/object
string Výraz, který je vyhodnocen ve výslednou hodnotu.
array Pole obsahující řetězce s výrazy, které jsou vyhodnoceny ve výsledné hodnoty.
object Objekt může mít tři různé typy:
  • dotazový objekt - při použití dotazového objektu se jedná o vnořený dotaz, možnost dostupnou pouze v rozšířené variantě dotazování
  • array - pokud je ve vlastnosti name nadřazeného výrazového objektu uveden field BO odkazující na jiný BO nebo kolekci BO, obsahuje fieldy odkazovaného BO, které mají být zahrnuty do výsledku dotazu
  • specifikační objekt - pokud vlastnost name nadřazeného výrazového objektu neodpovídá názvu fieldu BO odkazujícího na jiný BO nebo kolekci BO (který chceme pod zvolený název dosadit) jako v předchozím případě, umožňuje specifikovat field BO, ze kterého bude výsledná hodnota čerpána, včetně konkrétních fieldů odkazovaného BO (viz tabulka Specifikační objekt)
Specifikační objekt
Vlastnost JSON typ Význam
field string Název fieldu BO, ze kterého se vychází.
query object Objekt obsahující vlastnost select, jejíž hodnotou je pole výrazů, které jsou zahrnuty do výsledku dotazu.

Klauzule select se v rozšířené variantě dotazování používá i namísto klauzule expand (expand v rozšířené variantě není).

Výběr kolekce faktur, každý objekt faktury bude obsahovat ID, částku (Amount) a DisplayName, které je složené pomocí polí načtených z provázaných objektů. Jedná se o rychlejší variantu než je uvedena v prvním příkladu, ve kterém je použita nepersistentní položka (DisplayName); jak již bylo zmíněno výše, nepersistentní položky znamenají degradaci výkonu.

Klauzule select je v rozšířené variantě dotazování reprezentována JSON polem obsahujícím jednotlivé požadované fieldy. Fieldy samotné jsou reprezentovány buď řetězcem obsahujícím výraz nebo výrazovým objektem.

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

Tělo požadavku:

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

Výběr z agendy Adresář firem, pro výběr fieldu FirmOffices je využit výrazový objekt, pro výběr bankovních účtů (field BankAccounts, na BO firmy jsou bank. účty vedeny jako řádky Rows) je navíc použit specifikační objekt. 

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

Tělo požadavku:

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

Výběr kolekce ceníků, ke každému ceníku je ve výsledku dotazu zahrnut seznam firem, které jej mají nastavený. Jedná se o ukázku použití výrazového objektu v rámci selectu, možnosti využitelné pouze v rozšířené variantě dotazování. Všimněte si v klauzuli where vnořeného výrazového objektu použití :ID - reference na field nadřazeného BO v poddotazu. Pomocí takovéto syntaxe (:{název fieldu BO z nadřízeného dotazu}) lze do omezení (where) poddotazu dosazovat kontextuálně hodnoty z nadřazeného dotazu (pouze z nadřazeného dotazu). Tato možnost je důležitá ve chvíli, kdy je potřeba filtrovat za předem neznámé hodnoty. (Více viz Klauzule where s kontextuálními parametry.) 

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

Tělo požadavku:

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

Klauzule where má v rozšířené variantě dotazování podobnou sémantiku jako where v základní formě dotazování. Výraz pro určení platnosti se zapisuje do řetězcové hodnoty vlastnosti where dotazového objektu.

Klauzule where může obsahovat kontextuální parametry, které umožňují dosazovat hodnoty z nadřazeného dotazu. Kontextuální parametry jsou identifikovány pomocí speciální "dvojtečkové" syntaxe:

:{název fieldu BO z nadřízeného dotazu}

Lze také využívat kontextuální parametry v tečkové notaci. Dále je možné vytvářet uživatelsky pojmenované kontextuální parametry, které mohou zjednodušit tvorbu a čitelnost složitějších dotazů.

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

Tělo požadavku:

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

Klauzule orderby slouží k řazení výstupu stejným způsobem jako v SQL. Řazení se specifikuje ve vlastnosti orderbydotazového objektu. Hodnotou této vlastnosti je JSON pole, které může obsahovat řetězce obsahující výrazy pro řazení, a nebo objekty řazení (objekt řazení je nutné použít v situaci, kdy chceme řadit sestupně - výchozí řazení je vzestupné).

Objekt řazení
Vlastnost JSON typ Výraz
value string Výraz pro řazení
desc boolean Indikace, zda je řazení sestupné (true = sestupné; false = vzestupné)

Výběr kolekce faktur vydaných, každý objekt faktury obsahuje částku (Amount) a objekt firmy, na kterou je faktura vystavena (Firm_ID). Faktury jsou řazeny dle kódu firmy, na kterou jsou vystaveny vzestupně, a následně podle částky sestupně. 

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

Tělo požadavku:

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

Klauzule groupby má v rozšířené variantě dotazování stejnou sémantiku jako groupby v základní formě dotazování. Výraz pro agregaci se zapisuje do řetězcové hodnoty vlastnosti groupby dotazového objektu.

Získání trojice firem s největší celkovou fakturovanou částkou (Amount). Firmy jsou seřazeny podle této celkové částky sestupně (ukázka použití kombinace klauzulí orderby, groupby a take).

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

Tělo požadavku:

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