Zdroj dynsql ve Web API ABRA Gen

Požadavek:

GET http://localhost:699/demodata/dynsql

Zkrácený výsledek zpracování požadavku:

Status: 200 OK

[
	{
		"id": "0012IW1H1BH4X24ZFUJKXGA5US",
		"name": "INTRASTAT - Přijetí"
	},
	{
		"id": "01B4XCTHYNDL3C5P00CA141B44",
		"name": "Země"
	},
	...
	{
		"id": "WY15XY0ZAXLO10IB1GALYIP1XK",
		"name": "Výběr docházky pro uzávěrku"
	}
]

Požadavek:

GET http://localhost:699/demodata/dynsql/01B4XCTHYNDL3C5P00CA141B44

Chceme získat kolekci faktur vydaných splňujících určité podmínky. V aplikaci ABRA Gen bychom spustili agendu Faktury vydané, na záložce Omezení podmínky zadali a funkcí Získat záznamy získali požadovanou množinu záznamů. Totéž je od ABRA Gen 20.3 možné realizovat také prostřednictvím Web API.

Budeme potřebovat Packed CLSID dynamického SQL, které nalezneme v DynSQL editoru - naimportujeme repozitoř a v seznamu označíme dynamický SQL příkaz Faktury vydané. Požadovaná hodnota se zobrazí v položce ID příkazu pod seznamem (40SBPEINEFD13ACM03KIU0CLP4).

Požadavek:

POST http://localhost:699/demodata/dynsql/40SBPEINEFD13ACM03KIU0CLP4/exec

Samotný dotaz se předává v těle požadavku v JSON formátu. Může obsahovat následující objekty:

Objekt	Význam	Popis
"select"	Seznam položek, které se mají vrátit.	Zadává se jako pole řetězců, v případě jedné hodnoty se nemusí zadávat jako pole.
"where"	Seznam omezujících podmínek.	Zadává se jako pole objektů, v případě jedné podmínky se nemusí zadávat jako pole.
"id"	Identifikátor podmínky v definici DynSQL.	Odpovídá hodnotě položky Identifikátor na záložce Podmínky v DynSQL editoru.
"value"	Hodnota dosazená do podmínky.	V závislosti na definici podmínky v DynSQL se může jednat o jednu hodnotu nebo o pole hodnot, případně nemusí být uvedena. Bližší vysvětlení viz komentář k níže uvedenému vzorovému příkladu.
"flags"	Volitelné pole textových hodnot, kterými je možné vyhodnocování podmínky ovlivnit.	Některé flagy jsou obecné, některé mají význam jen pro některé typy podmínek: "WithChildren” - u hierarchických číselníků (střediska apod.) omezí i za podřízená ID k vybraným hodnotám “CaseInsensitive” - podmínka není case sensitive Je-li nějaká položka case insensitive, znamená to, že není citlivá na velká a malá písmena, neboli nerozlišuje velká a malá písmena. Tzn., že není rozdíl, je-li napsáno např. "Abc" nebo "abc". Opak je case sensitive. “Negation” - neguje celou podmínku “WithNull” - omezí i za null hodnoty “WithDocumentsWithoutRows” - přidá dokumenty bez řádků
"orderby"	Seznam klíčů, podle kterých se výsledek seřadí.	Zadává se jako pole objektů, v případě jedné hodnoty se nemusí zadávat jako pole. Může obsahovat objekty: "id" - identifikátor podmínky (shodné s “Identifikátor” v DynSQL editoru) "ordering" - může nabývat hodnot “asc” pro vzestupné třídění a “desc” pro sestupné třídění, výchozí hodnota je “asc”
"datasets"	Pole podřízených datasetů, které se připojí k výstupu.	Zadává se jako pole objektů, které můžou obsahovat “select”, “where” a “orderby” popsané výše. Jejich možné použití záleží na tom, jestli jsou podmínky nebo třídící klíče pro podřízený dataset definované.

Tělo požadavku:

{
    "select": ["ID", "DocQueue_Code", "Period_Code", "OrdNumber", "NotPaidAmount", "DocDate$DATE"],
    "where" : [
        {
            "id": "Firm_ID",
            "value": ["J000000101","7000000101","2000000101"]
        },
        {
            "id": "SimplifiedVATDocument",
            "value": true
        },
        {
            "id": "TradeType",
            "value": "3;9"
        },
        {
            "id": "Rows",
            "flags": ["WithDocumentsWithoutRows"]
        },
        {
            "id": "IntrastatCompleteKind",
            "value": "0"
        },
        {
            "id": "DocDate",
            "value": ["2020-11-14T23:00:00.000Z","2020-11-14T12:00:00.000Z"]
        },
        {
            "id": "description",
            "value": "*hello*",
            "flags": ["CaseInsensitive"]
        },
        {
            "id": "OrdNumber",
            "value": [3,5]
        },
        {
            "ID": "ESLCompleteKind"
        }
    ],
    "orderby" : [
        {
            "id": "DocDate",
            "ordering": "desc"
        },
        {
            "id": "OrdNumber"
        }
    ],
    "datasets": [
        {
            "name": "batches",
            "select": ["PosIndex", "qunit", "unitrate"]
        },
        {
            "name": "vatrates",
            "select": ["VRVATUsageRowsCount", "Name"]
        }
    ]
}

Podmínky jsou v DynSQL editoru definovány pomocí SQL fragmentů. V závislosti na vlastnostech těchto fragmentů se podmínky v těle požadavku (resp. hodnota "value") definují různými způsoby:

• Některé podmínky hodnotu nemají (typicky mají fragmenty deklarované v subzáložkách Link nebo Special). V uvedeném příkladu jde o jednotku Rows, kde se pomocí flagu nastavil výběr včetně dokumentů bez řádků (WithDocumentsWithoutRows) a podmínka ESLCompleteKind (Jen nevyplněné pro ESL), která má spec. subtyp 11 (v těle Web API požadavku ji stačí jen použít, do SQL se doplní fragment v podobě definované v sekci Special v DynSQL editoru).

  Datový typ a subtyp jsou součástí definice podmínky (v DynSQL editoru se zobrazují v horní části záložky Podmínky).

• Některé podmínky podporují právě jednu hodnotu. (V příkladu například podmínka Description.)

  Jednu hodnotu je možné použít i v případě podmínky reprezentující vazbu na číselník - pro podmínku “Firm_ID” by hodnota mohla vypadat i takto: “value”: “X000000101”.

• Některé podmínky podporují právě dvě hodnoty (rozsah). Typicky se jedná o podmínku typu datum, v příkladu podmínka DocDate.
• Některé podmínky podporují více než dvě hodnoty (seznam). Typicky se jedná o výběr množiny ID z číselníků, v příkladu podmínka Firm_ID.

• Některé podmínky se editují ve speciálním režimu a vyžadují zadání speciální hodnoty - viz definice v DynSQL editoru:

  • Podmínka SimplifiedVATDocument (Zjednodušený daňový doklad) je typu boolean (v DynSQL editoru ctBoolean), povolené hodnoty true nebo false.

  • Podmínka TradeType (Typ obchodu) je spec. subtyp 14 - v definici má deklarován seznam názvů a hodnot oddělených středníkem. Jako hodnotu je třeba zadat podmnožinu seznamu hodnot oddělených středníkem. V aplikaci ABRA Gen je reprezentována sadou přepínačů.

  • Podmínka IntrastatCompleteKind (Jen nevyplněné pro INTRASTAT) je spec. subtyp 1 - v definici má deklarován seznam názvů a hodnot oddělených středníkem. Do podmínky je zapotřebí předat právě jednu hodnotu ze seznamu. V aplikaci ABRA Gen je reprezentována zatrhávací položkou.

Vrácený JSON obsahuje objekt s následujícími vlastnostmi:

Vlastnost	Význam	Komentář
"name"	Název datasetu.
"items"	Pole vrácených objektů. Může obsahovat pole podřízených datasetů "datasets” v případě, že výsledek nějaké podřízené datasety obsahuje.	Pole datasetů jsou do sebe vnořená podle definice DynSQL. Dataset VATRates (Sumář DPH) je podřízený datasetu MAIN. Dataset BATCHES (Pohyby sériových čísel a šarží) je podřízený datasetu ROWS (Řádky). Dataset ROWS není v níže uvedeném dotazu explicitně uveden, proto se připojil automaticky a nevrátil žádné položky (samotné řádky), jen data sobě podřízených datasetů (pohyby sériových čísel a šarží). Struktura datasetů v definici DynSQL vypadá následovně: MAIN ROWS BATCHES VATRates

Požadavek:

POST http://localhost:699/demodata/dynsql/40SBPEINEFD13ACM03KIU0CLP4/exec

Tělo požadavku:

{
    "select": ["ID", "DocQueue_Code", "Period_Code", "OrdNumber", "NotPaidAmount", "DocDate$DATE"],
    "where" : {
            "id": "ID",
            "value": "2E00000101"
    },
    "datasets": [
        {
            "name": "batches",
            "select": ["PosIndex", "qunit", "unitrate"]
        },
        {
            "name": "vatrates",
            "select": ["VRVATUsageRowsCount", "Name"]
        }
    ]
}

Výsledek zpracování požadavku:

Status: 200 OK

{
	"name": "MAIN",
	"items": [
		{
			"ID": "2E00000101",
			"DOCQUEUE_CODE": "FV",
			"PERIOD_CODE": "2020",
			"ORDNUMBER": 5,
			"NOTPAIDAMOUNT": 0,
			"DOCDATE$DATE": "2020-10-14T22:00:00.000Z",
			"datasets": [
				{
					"name": "ROWS",
					"items": [
						{
							"datasets": [
								{
									"name": "BATCHES",
									"items": []
								}
							]
						},
						{
							"datasets": [
								{
									"name": "BATCHES",
									"items": []
								}
							]
						},
						{
							"datasets": [
								{
									"name": "BATCHES",
									"items": [
										{
											"POSINDEX": 1,
											"QUNIT": "ks",
											"UNITRATE": 1
										}
									]
								}
							]
						},
						{
							"datasets": [
								{
									"name": "BATCHES",
									"items": []
								}
							]
						}
					]
				},
				{
					"name": "VATRates",
					"items": [
						{
							"VRVATUSAGEROWSCOUNT": 0,
							"NAME": "základní sazba"
						}
					]
				}
			]
		}
	]
}