Čo je to?

Poznámka pre administrátora: Toto je „univerzálny jazyk“, ktorý umožňuje populárnym obchodným nástrojom, ako sú Microsoft Excel a Power BI, priamo komunikovať s dátami vášho e-shopu. Je to štandardný spôsob pripojenia vašich dát k vašim obľúbeným aplikáciám na vytváranie reportov a analýzu.

Pre koho je to určené? Administrátori by si mali prečítať tento článok, aby sa dozvedeli, ako pripojiť dáta svojho e-shopu k Excelu alebo Power BI pre vlastné dashboardy a reporty. Hoci počiatočné nastavenie v týchto aplikáciách je jednoduché (a vysvetlené nižšie), možno budete chcieť požiadať svojho vývojára alebo dátového analytika o pomoc s komplexnými reportmi alebo čistením dát.

Kľúčové výhody pre e-shop:

• Jednoduché reportovanie: Pripojte svoje živé dáta priamo k Excelu alebo Power BI bez potreby manuálneho exportu a importu súborov CSV.
• Dashboardy v reálnom čase: Vytvárajte profesionálne dashboardy, ktoré sa automaticky aktualizujú s meniacimi sa predajmi, produktmi a zákazníkmi.
• Hĺbková analýza: Využite plný výkon profesionálnych BI nástrojov na analýzu výkonnosti vášho podnikania, trendov a ziskovosti.
• Priemyselný štandard: Pretože sa používa globálne uznávaný štandard (OData), funguje to s takmer akýmkoľvek moderným softvérom na reportovanie alebo analýzu dát.

Prehľad

OData v4 API poskytuje štandardizované RESTful rozhranie pre dopytovanie a prístup k dátam zo všetkých entít v systéme. OData (Open Data Protocol) je štandard OASIS, ktorý definuje osvedčené postupy pre vytváranie a používanie REST API.

Základná URL pre všetky požiadavky OData je:

`{HOSTNAME}/api/odata/{companyId}`

Integrácia s PowerBI

OData v4 API možno použiť priamo v PowerBI a iných nástrojoch business intelligence, ktoré podporujú OData kanály. To vám umožňuje vytvárať reporty a dashboardy pomocou vašich dát bez vlastných integrácií.

V PowerBI vyberte **Získať údaje** → **OData**
Zadajte URL OData: `{HOSTNAME}/api/odata/{companyId}`
Keď sa zobrazí výzva na overenie, vyberte **Základné** overenie
Zadajte používateľské meno: `api` a heslo: váš API kľúč
Vyberte entity (tabuľky), ktoré chcete importovať

**Vyžaduje sa API kľúč**

Pred použitím OData kanála musíte vygenerovať API kľúč. [navigate:/apiKeys|Vygenerujte API kľúč tu|key]

Kľúčové koncové body

Podporované možnosti dopytu

Príklady použitia

Základné filtrovanie

GET /api/odata/{companyId}/products?$filter=price gt 100&$orderby=name&$top=10

Kolekcia Lambda (any/all)

GET /api/odata/{companyId}/products?$filter=reviews/any(r: r/rating gt 4)

Rozširovanie vzťahov

GET /api/odata/{companyId}/products?$expand=category,supplier&$select=name,price

Agregácia so zoskupovaním

GET /api/odata/{companyId}/products?$apply=groupby((category_id),aggregate($count as count,price with sum as total))

Reťazcové funkcie

GET /api/odata/{companyId}/products?$filter=contains(name,'widget') and startswith(sku,'PRD')

Funkcie dátumu/času

GET /api/odata/{companyId}/orders?$filter=year(orderDate) eq 2024 and month(orderDate) ge 6

Matematické funkcie a operátory

GET /api/odata/{companyId}/products?$filter=round(price) gt 100 and (price mul 0.8) lt 500

Referencie entít ($ref)

GET /api/odata/{companyId}/products(123)/category/$ref

Vráti referenčnú URL na súvisiacu entitu kategórie.

Príklady kódu s overením

tab: JavaScript
// Using HTTP Basic Authentication
const apiKey = 'your-api-key';
const auth = btoa('api:' + apiKey); // base64 encode

fetch('/api/odata/{companyId}/products?$top=10', {
  headers: {
    'Authorization': 'Basic ' + auth
  }
})
  .then(response => response.json())
  .then(data => console.log(data.value));
---
tab: cURL
# Using HTTP Basic Authentication (-u flag)
curl -u api:YOUR_API_KEY "/api/odata/{companyId}/products?\$filter=price gt 100&\$top=10"

# Or manually specify Authorization header
curl -H "Authorization: Basic $(echo -n 'api:YOUR_API_KEY' | base64)" \
  "/api/odata/{companyId}/products"
---
tab: Python
import requests
from requests.auth import HTTPBasicAuth

api_key = 'your-api-key'
url = '/api/odata/{companyId}/products'

# Using HTTP Basic Authentication
response = requests.get(
    url,
    auth=HTTPBasicAuth('api', api_key),
    params={'$filter': 'price gt 100', '$top': 10}
)

data = response.json()
print(data['value'])
---
tab: PowerShell
$apiKey = "your-api-key"
$credentials = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("api:$apiKey"))

$headers = @{
    "Authorization" = "Basic $credentials"
}

$response = Invoke-RestMethod -Uri "/api/odata/{companyId}/products?`$top=10" -Headers $headers
$response.value

Overenie

Koncové body OData API vyžadujú overenie pomocou jednej z nasledujúcich metód:

HTTP Basic Authentication [badge:Odporúčané pre OData|success]

Pre koncové body OData použite HTTP Basic Authentication s používateľským menom api a vaším API kľúčom ako heslom:

Authorization: Basic {base64(api:your-api-key)}

Príklad s curl:

curl -u api:YOUR_API_KEY \
  /api/odata/{companyId}/products

[navigate:/apiKeys|Generovať a spravovať API kľúče →|key]

Bearer Token (JWT)

Použite JWT token získaný z prihlásenia pre overenie UI:

Authorization: Bearer your-jwt-token

Hlavička API kľúča

Alternatívna metóda pomocou vlastnej hlavičky (nie pre koncové body OData):

X-API-Key: your-api-key

Súbor cookie relácie

Automatické overenie založené na relácii pre požiadavky prehliadača:

Cookie: session=...

**Dôležité**

Pre koncové body OData (`/api/odata/*`) je vyžadované HTTP Basic Authentication. Používateľské meno musí byť `api` a heslo je váš API kľúč. Ostatné metódy overenia fungujú pre koncové body, ktoré nie sú OData.

ETags pre ukladanie do vyrovnávacej pamäte

OData API podporuje ETags (Entity Tags) pre efektívne ukladanie do vyrovnávacej pamäte. ETags pomáhajú klientom vyhnúť sa zbytočným prenosom dát, keď sa entity nezmenili.

Ako to funguje:

Server vráti hlavičku `ETag` s každou odpoveďou
Klient odošle hlavičku `If-None-Match` s hodnotou ETag pri následných požiadavkách
Ak sa entita nezmenila, server vráti **304 Not Modified** (bez tela)
Ak sa entita zmenila, server vráti **200 OK** s aktualizovanými dátami a novým ETagom

Implementované funkcie

• Koncový bod servisného dokumentu
• Koncový bod $metadata s generovaním EDMX
• Anotácie schopností v metadátach (FilterRestrictions, SortRestrictions atď.)
• Anotácie FilterFunctions (oznamuje podporované funkcie filtra)
• Anotácie ApplySupported (oznamuje možnosti agregácie)
• Dotazy na kolekcie entít
• Načítanie jednej entity podľa ID
• Koncový bod $count
• Koncový bod $ref pre navigačné vlastnosti (získanie referencií entít)
• $filter s porovnávacími operátormi (eq, ne, gt, ge, lt, le)
• $filter s logickými operátormi (and, or, not)
• $filter s matematickými operátormi (add, sub, mul, div, mod)
• $filter s reťazcovými funkciami (contains, startswith, endswith, tolower, toupper, concat, substring, indexof, length, trim)
• $filter s funkciami extrakcie dátumu/času (year, month, day, hour, minute, second, quarter, week, dayofweek)
• $filter s funkciami hraníc dátumu (startOfYear, endOfYear, startOfMonth, endOfMonth, startOfDay, endOfDay, startOfHour, endOfHour)
• $filter s matematickými funkciami (round, floor, ceiling)
• $filter s operátormi lambda kolekcií (any, all) — plne implementované s podporou vnorenia
• $select pre projekciu polí
• $orderby pre triedenie
• $top pre obmedzenie výsledkov
• $skip pre stránkovanie
• $expand pre vzťahy (základné)
• $count vložené do dotazov
• $apply s agregačnými transformáciami
• $apply s transformáciami groupby
• Agregačné funkcie: count, sum, avg, min, max
• Formát odpovede OData v4 s @odata.context
• Správne hlavičky OData (OData-Version, Content-Type)
• ETagy pre efektívne ukladanie do vyrovnávacej pamäte
• Podmienený GET If-None-Match (vracia 304 Not Modified)

Chýbajúce funkcie (budúca implementácia)

Nasledujúce funkcie ešte nie sú implementované:

- `$search` — Fulltextové vyhľadávanie (parsované, ale nevykonané)
- `$filter` s geo funkciami (`geo.distance`, `geo.intersects` atď.)
- Pokročilé transformácie `$apply` (`filter`, `compute`, `concat`, `expand`)
- `$compute` — Vypočítané vlastnosti
- `$expand` s vnorenými možnosťami (napr. `$expand=category($select=name)`)
- `$levels` — Rekurzívne hierarchie
- `$format` — Explicitná špecifikácia formátu (vždy vracia JSON)
- `POST` — Vytvorenie nových entít
- `PATCH` — Aktualizácia entít
- `PUT` — Nahradenie entít
- `DELETE` — Vymazanie entít
- `$batch` — Dávkové požiadavky
- Sledovanie delty — `$deltatoken`
- Importy funkcií a importy akcií
- `If-Match` — Optimistické riadenie súbežnosti (ETagy len pre ukladanie do vyrovnávacej pamäte)
- Stránkovanie riadené serverom s `@odata.nextLink`

Osvedčené postupy

• Použite $select na vyžiadanie iba polí, ktoré potrebujete
• Implementujte stránkovanie pomocou $top a $skip pre veľké súbory dát
• Použite $filter na zníženie prenosu dát namiesto filtrovania na strane klienta
• Využite ETagy a If-None-Match pre efektívne ukladanie do vyrovnávacej pamäte
• Použite $apply pre agregácie na strane servera namiesto agregácie na strane klienta
• Skontrolujte koncový bod $metadata na objavenie dostupných entít a ich vlastností