OData v4 API

Co je to?

Poznámka pro administrátory: Jedná se o „univerzální jazyk“, který umožňuje populárním obchodním nástrojům, jako je Microsoft Excel a Power BI, komunikovat přímo s daty vašeho e-shopu. Je to standardní způsob, jak propojit vaše data s vašimi oblíbenými aplikacemi pro reportování a analýzu.

Pro koho je to určeno? Administrátoři by si měli přečíst tento článek, aby se dozvěděli, jak propojit data svého e-shopu s Excelem nebo Power BI pro vlastní dashboardy a reportování. Zatímco počáteční nastavení v těchto aplikacích je jednoduché (a vysvětleno níže), můžete požádat svého vývojáře nebo datového analytika o pomoc se složitými reporty nebo čištěním dat.

Klíčové výhody pro e-shop:

Snadné reportování: Propojte svá živá data přímo s Excelem nebo Power BI, aniž byste museli ručně exportovat a importovat soubory CSV.
Dashboardy v reálném čase: Vytvářejte profesionální dashboardy, které se automaticky aktualizují s měnícími se prodeji, produkty a zákazníky.
Hloubková analýza: Využijte plný výkon profesionálních BI nástrojů k analýze výkonnosti vašeho podniku, trendů a ziskovosti.
Průmyslový standard: Protože se používá globálně uznávaný standard (OData), funguje s téměř jakýmkoli moderním softwarem pro reportování nebo analýzu dat.

Přehled

OData v4 API poskytuje standardizované RESTful rozhraní pro dotazování a přístup k datům ze všech entit v systému. OData (Open Data Protocol) je standard OASIS, který definuje osvědčené postupy pro vytváření a využívání REST API.

Základní URL pro všechny požadavky OData je:

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

Integrace s PowerBI

OData v4 API lze použít přímo v PowerBI a dalších nástrojích business intelligence, které podporují OData kanály. To vám umožní vytvářet reporty a dashboardy pomocí vašich dat bez vlastních integrací.

V PowerBI vyberte **Získat data** → **OData**
Zadejte URL OData: `{HOSTNAME}/api/odata/{companyId}`
Po zobrazení výzvy k ověření vyberte **Základní** ověření
Zadejte uživatelské jméno: `api` a heslo: váš API klíč
Vyberte entity (tabulky), které chcete importovat

**Vyžadován API klíč**

Před použitím OData kanálu musíte vygenerovat API klíč. [navigate:/apiKeys|Vygenerujte API klíč zde|key]

Klíčové koncové body

Koncový bod	Popis
`GET /api/odata/{companyId}`	Dokument služby s výpisem všech dostupných sad entit
`GET /api/odata/{companyId}/$metadata`	Dokument metadat EDMX popisující všechny entity, vlastnosti a vztahy
`GET /api/odata/{companyId}/{entityName}`	Dotazování kolekce entit s možnostmi dotazu OData
`GET /api/odata/{companyId}/{entityName}({id})`	Načtení jedné entity podle ID
`GET /api/odata/{companyId}/{entityName}/$count`	Získání počtu entit odpovídajících dotazu
`GET /api/odata/{companyId}/{entityName}({id})/{navigationProperty}/$ref`	Získání odkazu (odkazů) na související entity prostřednictvím navigační vlastnosti

Podporované možnosti dotazu

Možnost	Popis	Příklad
`$filter`	Filtrování entit na základě podmínek	`$filter=price gt 100 and active eq true`
`$select`	Výběr konkrétních polí k vrácení	`$select=id,name,price`
`$orderby`	Řazení entit podle polí	`$orderby=name asc,price desc`
`$top`	Omezení počtu výsledků	`$top=10`
`$skip`	Přeskočení určitého počtu entit (stránkování)	`$skip=20`
`$expand`	Zahrnutí souvisejících entit	`$expand=category,supplier`
`$count`	Zahrnutí celkového počtu do odpovědi	`$count=true`
`$apply`	Agregace a transformace dat	`$apply=groupby((category),aggregate($count as total))`

Příklady použití

Základní filtrování

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

Kolekce Lambda (any/all)

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

Rozšiřování vztahů

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

Agregace se seskupováním

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

Řetězcové funkce

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

Funkce data/času

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

Matematické funkce a operátory

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

Odkazy na entity ($ref)

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

Vrací referenční URL na související entitu kategorie.

Příklady kódu s ověření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

Ověření

Koncové body OData API vyžadují ověření pomocí jedné z následujících metod:

Základní ověření HTTP [badge:Doporučeno pro OData|success]

Pro koncové body OData použijte základní ověření HTTP s uživatelským jménem api a vaším API klíčem jako heslem:

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

Příklad s curl:

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

[navigate:/apiKeys|Generovat a spravovat API klíče →|key]

Bearer Token (JWT)

Použijte JWT token získaný z přihlášení pro ověření uživatelského rozhraní:

Authorization: Bearer your-jwt-token

Hlavička API klíče

Alternativní metoda pomocí vlastní hlavičky (ne pro koncové body OData):

X-API-Key: your-api-key

Automatické ověřování založené na relaci pro požadavky prohlížeče:

Cookie: session=...

**Důležité**

Pro koncové body OData (`/api/odata/*`) je vyžadováno základní ověření HTTP. Uživatelské jméno musí být `api` a heslo je váš API klíč. Jiné metody ověřování fungují pro koncové body, které nejsou OData.

ETags pro ukládání do mezipaměti

OData API podporuje ETags (značky entit) pro efektivní ukládání do mezipaměti. ETags pomáhají klientům vyhnout se zbytečným přenosům dat, když se entity nezměnily.

Jak to funguje:

Server vrací hlavičku `ETag` s každou odpovědí
Klient odesílá hlavičku `If-None-Match` s hodnotou ETag v následných požadavcích
Pokud se entita nezměnila, server vrátí **304 Not Modified** (bez těla)
Pokud se entita změnila, server vrátí **200 OK** s aktualizovanými daty a novým ETagem

Implementované funkce

Koncový bod servisního dokumentu
Koncový bod $metadata s generováním EDMX
Anotace schopností v metadatech (FilterRestrictions, SortRestrictions atd.)
Anotace FilterFunctions (oznamuje podporované funkce filtru)
Anotace ApplySupported (oznamuje možnosti agregace)
Dotazy na kolekce entit
Načítání jedné entity podle ID
Koncový bod $count
Koncový bod $ref pro navigační vlastnosti (získání referencí entit)
$filter s operátory porovnání (eq, ne, gt, ge, lt, le)
$filter s logickými operátory (and, or, not)
$filter s matematickými operátory (add, sub, mul, div, mod)
$filter s řetězcovými funkcemi (contains, startswith, endswith, tolower, toupper, concat, substring, indexof, length, trim)
$filter s funkcemi pro extrakci data/času (year, month, day, hour, minute, second, quarter, week, dayofweek)
$filter s funkcemi pro hranice data (startOfYear, endOfYear, startOfMonth, endOfMonth, startOfDay, endOfDay, startOfHour, endOfHour)
$filter s matematickými funkcemi (round, floor, ceiling)
$filter s operátory lambda pro kolekce (any, all) — plně implementováno s podporou vnoření
$select pro projekci polí
$orderby pro řazení
$top pro omezení výsledků
$skip pro stránkování
$expand pro relace (základní)
$count přímo v dotazech
$apply s agregačními transformacemi
$apply s transformacemi groupby
Agregační funkce: count, sum, avg, min, max
Formát odpovědi OData v4 s @odata.context
Správné hlavičky OData (OData-Version, Content-Type)
ETagy pro efektivní ukládání do mezipaměti
Podmíněný GET If-None-Match (vrací 304 Not Modified)

Chybějící funkce (budoucí implementace)

Následující funkce ještě nejsou implementovány:

- `$search` — Fulltextové vyhledávání (parsováno, ale neprovedeno)
- `$filter` s geo funkcemi (`geo.distance`, `geo.intersects` atd.)
- Pokročilé transformace `$apply` (`filter`, `compute`, `concat`, `expand`)
- `$compute` — Počítané vlastnosti
- `$expand` s vnořenými možnostmi (např. `$expand=category($select=name)`)
- `$levels` — Rekurzivní hierarchie
- `$format` — Explicitní specifikace formátu (vždy vrací JSON)
- `POST` — Vytváření nových entit
- `PATCH` — Aktualizace entit
- `PUT` — Nahrazování entit
- `DELETE` — Mazání entit
- `$batch` — Dávkové požadavky
- Sledování delty — `$deltatoken`
- Importy funkcí a importy akcí
- `If-Match` — Optimistická kontrola souběžnosti (ETagy pouze pro ukládání do mezipaměti)
- Stránkování řízené serverem s `@odata.nextLink`

Doporučené postupy

Použijte $select k vyžádání pouze polí, která potřebujete
Implementujte stránkování pomocí $top a $skip pro velké datové sady
Použijte $filter ke snížení přenosu dat namísto filtrování na straně klienta
Využijte ETagy a If-None-Match pro efektivní ukládání do mezipaměti
Použijte $apply pro agregace na straně serveru namísto agregace na straně klienta
Zkontrolujte koncový bod $metadata pro zjištění dostupných entit a jejich vlastností