[badge:OData v4|info]

Přehled

OData v4 API poskytuje standardizované rozhraní RESTful 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 feedy. To vám umožní vytvářet sestavy a řídicí panely 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

**Je vyžadován API klíč**

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

Klíčové koncové body

Podporované možnosti dotazu

Příklady použití

Základní filtrování

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

Kolekční Lambda (any/all)

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

Rozšíření 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

Vrátí odkaz URL na související entitu kategorie.

Příklady kódu s ověřením

tab: JavaScript
// Použití 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
# Použití HTTP Basic Authentication (-u flag)
curl -u api:YOUR_API_KEY "/api/odata/{companyId}/products?\$filter=price gt 100&\$top=10"

# Nebo ručně zadejte hlavičku Authorization
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'

# Použití 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:

HTTP Basic Authentication [badge:Doporučeno pro OData|success]

Pro koncové body OData použijte HTTP Basic Authentication 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|Generování a správa API klíčů →|key]

Bearer Token (JWT)

Použijte JWT token získaný z přihlášení pro ověření UI:

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

Session Cookie

Automatické ověření 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 HTTP Basic Authentication. Uživatelské jméno musí být `api` a heslo je váš API klíč. Ostatní metody ověření fungují pro koncové body, které nejsou OData.

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

OData API podporuje ETags (Entity Tags) 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 u následných požadavků
Pokud se entita nezměnila, server vrátí **304 Not Modified** (žádné tělo)
Pokud se entita změnila, server vrátí **200 OK** s aktualizovanými daty a novým ETag

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čtení jedné entity podle ID
• Koncový bod $count
• Koncový bod $ref pro navigační vlastnosti (získání odkazů na entity)
• $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 extrakce data/času (year, month, day, hour, minute, second, quarter, week, dayofweek)
• $filter s funkcemi ohraničení data (startOfYear, endOfYear, startOfMonth, endOfMonth, startOfDay, endOfDay, startOfHour, endOfHour)
• $filter s matematickými funkcemi (round, floor, ceiling)
• $filter s operátory lambda 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 vztahy (základní)
• $count inline 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)
• ETags 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` — Vypočí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` — Vytvoření nových entit
- `PATCH` — Aktualizace entit
- `PUT` — Nahrazení entit
- `DELETE` — Odstranění entit
- `$batch` — Dávkové požadavky
- Sledování změn — `$deltatoken`
- Importy funkcí a importy akcí
- `If-Match` — Optimistická kontrola souběžnosti (ETags pouze pro ukládání do mezipaměti)
- Stránkování řízené serverem s `@odata.nextLink`

Osvědč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 ETags 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 a zjistěte dostupné entity a jejich vlastnosti