Volání koncových bodů REST

Tvůrce rozhraní DAB (Data API Builder) poskytuje webové rozhraní RESTful, které umožňuje přístup k tabulkám, zobrazením a uloženým procedurami z připojené databáze. Každý vystavený databázový objekt je definován jako entita v konfiguraci modulu runtime.

Ve výchozím nastavení DAB hostuje koncové body REST na adrese:

https://{base_url}/api/{entity}

Poznámka:

U všech komponent cesty a parametrů dotazu se rozlišují malá a velká písmena.

Klíčová slova podporovaná v Tvůrci rozhraní Data API

Koncepce	REST	Purpose
Projekce	$select	Vyberte pole, která se mají vrátit
Filtrování	$filter	Omezení řádků podle podmínky
Řazení	$orderby	Definování pořadí řazení
Velikost stránky	$first	Omezení položek na stránku
Pokračování	$after	Pokračovat z poslední stránky

Základní struktura

Pokud chcete volat rozhraní REST API, vytvořte požadavek pomocí tohoto vzoru:

{HTTP method} https://{base_url}/{rest-path}/{entity}

Příklad čtení všech záznamů z book entity:

GET https://localhost:5001/api/book

Odpověď je objekt JSON s polem value . Stránkování a informace o chybách se zobrazí pouze v případě, že je to možné.

Poznámka:

Ve výchozím nastavení daB vrátí až 100 položek na dotaz, pokud není nakonfigurovaný jinak (runtime.pagination.default-page-size).

GET https://localhost:5001/api/book

Úspěch:

{
  "value": [
    { "id": 1, "title": "Dune", "year": 1965, "pages": 412 },
    { "id": 2, "title": "Foundation", "year": 1951, "pages": 255 }
  ]
}

Úspěch se stránkováním:

{
  "value": [
    { "id": 1, "title": "Dune", "year": 1965, "pages": 412 },
    { "id": 2, "title": "Foundation", "year": 1951, "pages": 255 }
  ],
  "nextLink": "https://localhost:5001/api/book?$after=WyJCb29rMiJd"
}

Prázdný výsledek (položka nebyla nalezena):

{
  "value": []
}

Poznámka:

Požadavek GET na neexistující primární klíč se vrátí 200 OK s prázdným value polem, nikoli 404 Not Found. Zkontrolujte prázdné pole a určete, jestli položka existuje.

curl -X GET "https://localhost:5001/api/book"

Následující třídy modelu deserializují odpovědi DAB:

using System.Text.Json.Serialization;

public class DabResponse<T>
{
    [JsonPropertyName("value")]
    public List<T>? Value { get; set; }

    [JsonPropertyName("nextLink")]
    public string? NextLink { get; set; }

    [JsonPropertyName("error")]
    public DabError? Error { get; set; }

    [JsonIgnore]
    public bool IsSuccess => Error is null;

    [JsonIgnore]
    public bool HasNextPage => NextLink is not null;
}

public class DabError
{
    [JsonPropertyName("code")]
    public string Code { get; set; } = string.Empty;

    [JsonPropertyName("message")]
    public string Message { get; set; } = string.Empty;

    [JsonPropertyName("status")]
    public int Status { get; set; }
}

public class Book
{
    [JsonPropertyName("id")]
    public int Id { get; set; }

    [JsonPropertyName("title")]
    public string Title { get; set; } = string.Empty;

    [JsonPropertyName("year")]
    public int? Year { get; set; }

    [JsonPropertyName("pages")]
    public int? Pages { get; set; }
}

Volání rozhraní API a deserializace odpovědi:

public async Task<List<Book>> GetBooksAsync()
{
    var response = await httpClient.GetAsync("api/book");
    response.EnsureSuccessStatusCode();
    var result = await response.Content.ReadFromJsonAsync<DabResponse<Book>>();

    if (result?.Error is not null)
    {
        throw new Exception($"{result.Error.Code}: {result.Error.Message}");
    }

    return result?.Value ?? [];
}

Následující datové třídy modelují odpovědi DAB:

from dataclasses import dataclass
import requests

@dataclass
class Book:
    id: int
    title: str
    year: int | None = None
    pages: int | None = None

@dataclass
class DabError:
    code: str
    message: str
    status: int

@dataclass
class DabResponse:
    value: list[Book] | None = None
    next_link: str | None = None
    error: DabError | None = None

    @property
    def is_success(self) -> bool:
        return self.error is None

    @property
    def has_next_page(self) -> bool:
        return self.next_link is not None

Volání rozhraní API a analýza odpovědi:

def get_books(base_url: str) -> list[Book]:
    response = requests.get(f"{base_url}/api/book")
    response.raise_for_status()
    data = response.json()

    if "error" in data:
        err = data["error"]
        raise Exception(f"{err['code']}: {err['message']}")

    return [Book(**item) for item in data.get("value", [])]

Následující funkce volá rozhraní API:

async function getBooks(baseUrl) {
  const response = await fetch(`${baseUrl}/api/book`);
  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }
  const data = await response.json();

  if (data.error) {
    throw new Error(`${data.error.code}: ${data.error.message}`);
  }

  return data.value ?? [];
}

Příklad použití:

const books = await getBooks("https://localhost:5001");
console.log(`Fetched ${books.length} books from the API.`);

Typy dotazů

Každá entita REST podporuje čtení kolekce i jednoho záznamu.

Operation	Description
`GET /api/{entity}`	Vrátí seznam záznamů.
`GET /api/{entity}/{primary-key-column}/{primary-key-value}`	Vrátí jeden záznam podle primárního klíče.

Příklad vrácení jednoho záznamu:

GET /api/book/id/1010

Příklad vracející mnoho dat:

GET /api/book

Filtrování výsledků

Pomocí parametru $filter dotazu omezte, které záznamy se vrátí.

GET /api/book?$filter=title eq 'Foundation'

Tento dotaz vrátí všechny knihy, jejichž název je "Foundation."

Filtry můžou zahrnovat logické operátory pro složitější dotazy:

GET /api/book?$filter=year ge 1970 or title eq 'Dune'

Další informace najdete v referenci argumentu $filter.

Řazení výsledků

Parametr $orderby definuje způsob řazení záznamů.

GET /api/book?$orderby=year desc, title asc

Vrátí knihy seřazené podle year sestupně, pak podle title.

Další informace najdete v referenčním $orderby argumentu.

Omezení výsledků :{#first-and-after}

Parametr $first omezuje počet vrácených záznamů v jednom požadavku.

GET /api/book?$first=5

Tím se vrátí prvních pět knih seřazených podle primárního klíče ve výchozím nastavení. Můžete také použít $first=-1 k vyžádání nakonfigurované maximální velikosti stránky, která má výchozí hodnotu 100 položek. Tento limit nakonfigurujte v konfiguračním runtime.pagination.default-page-size souboru.

Další informace najdete v referenci $first argumentu.

Pokračování výsledků

Pokud chcete načíst další stránku, použijte $after s tokenem pro pokračování z předchozí odpovědi.

GET /api/book?$first=5&$after={continuation-token}

Token $after identifikuje, kde byl poslední dotaz ukončen. Další informace najdete v referenčním $after argumentu.

Výběr pole (projekce)

Pomocí $select určíte, která pole jsou zahrnuta v odpovědi.

GET /api/book?$select=id,title,price

Tím se vrátí pouze zadané sloupce. Pokud pole chybí nebo není přístupné, DAB vrátí 400 Bad Request.

Další informace najdete v referenčním $select argumentu.

Úprava dat

Rozhraní REST API také podporuje operace vytváření, aktualizace a odstraňování v závislosti na oprávněních entity.

Metoda	Action
`POST`	Vytvoření nové položky
`PUT`	Nahrazení existující položky (nebo vytvoření, pokud chybí)
`PATCH`	Aktualizace existující položky (nebo vytvoření, pokud chybí)
`DELETE`	Odebrání položky podle primárního klíče

Důležité

Chování funkce upsert (insert-if-missing) u PUT a PATCH funguje pouze v případě, že databáze umožňuje explicitní hodnoty primárního klíče. U tabulek s automaticky vygenerovanými klíči (například IDENTITY sloupce v SQL Serveru nebo SERIAL v PostgreSQL) pokus o PATCH nebo 404 Not Found do neexistujícího klíče vrátí PUT, protože databáze odmítne explicitní vložení do automaticky generovaného sloupce. Použijte POST k vytváření záznamů v tabulkách s automaticky vygenerovanými klíči, nebo použijte bezklíčové operace PUT a PATCH k automatickému přiřazení klíčů systémem DAB.

Vytvoření nového záznamu

Slouží POST k vytvoření nové položky.

POST https://localhost:5001/api/book
Content-Type: application/json

{
  "id": 2000,
  "title": "Leviathan Wakes",
  "year": 2011,
  "pages": 577
}

curl -X POST "https://localhost:5001/api/book" \
  -H "Content-Type: application/json" \
  -d '{"id": 2000, "title": "Leviathan Wakes", "year": 2011, "pages": 577}'

var book = new Book
{
    Id = 2000,
    Title = "Leviathan Wakes",
    Year = 2011,
    Pages = 577
};
var response = await httpClient.PostAsJsonAsync("api/book", book);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<DabResponse<Book>>();

if (result?.Error is not null)
{
    throw new Exception($"{result.Error.Code}: {result.Error.Message}");
}

book = {"id": 2000, "title": "Leviathan Wakes", "year": 2011, "pages": 577}
response = requests.post(f"{base_url}/api/book", json=book)
response.raise_for_status()
data = response.json()

if "error" in data:
    err = data["error"]
    raise Exception(f"{err['code']}: {err['message']}")

const book = { id: 2000, title: "Leviathan Wakes", year: 2011, pages: 577 };
const response = await fetch(`${baseUrl}/api/book`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(book),
});
const data = await response.json();

if (data.error) {
  throw new Error(`${data.error.code}: ${data.error.message}`);
}

Aktualizovat existující záznam

Slouží PATCH k aktualizaci konkrétních polí u existující položky.

PATCH https://localhost:5001/api/book/id/2000
Content-Type: application/json

{
  "id": 2000,
  "title": "Leviathan Wakes",
  "year": 2011,
  "pages": 577
}

curl -X PATCH "https://localhost:5001/api/book/id/2000" \
  -H "Content-Type: application/json" \
  -d '{"id": 2000, "title": "Leviathan Wakes", "year": 2011, "pages": 577}'

Návod

Ve výchozím nastavení DAB odmítne pole v textu požadavku, která v databázi neexistují nebo která patří do adresy URL (například pole primárního klíče pro PATCH a DELETE). Toto chování vyžaduje samostatné typy jazyka C#: jeden s klíči pro POST a jeden bez aktualizací. Pokud chcete znovu použít stejný typ, jako je Book, pro všechny operace, nastavte runtime.rest.request-body-strict ve vaší konfiguraci false.

var book = new Book
{
    Id = 2000,
    Title = "Leviathan Wakes",
    Year = 2011,
    Pages = 577
};
var response = await httpClient.PatchAsJsonAsync("api/book/id/2000", book);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<DabResponse<Book>>();

if (result?.Error is not null)
{
    throw new Exception($"{result.Error.Code}: {result.Error.Message}");
}

book = {"id": 2000, "title": "Leviathan Wakes", "year": 2011, "pages": 577}
response = requests.patch(f"{base_url}/api/book/id/2000", json=book)
response.raise_for_status()
data = response.json()

if "error" in data:
    err = data["error"]
    raise Exception(f"{err['code']}: {err['message']}")

const book = { id: 2000, title: "Leviathan Wakes", year: 2011, pages: 577 };
const response = await fetch(`${baseUrl}/api/book/id/2000`, {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(book),
});
const data = await response.json();

if (data.error) {
  throw new Error(`${data.error.code}: ${data.error.message}`);
}

Odstranění záznamu

Použijte DELETE k odebrání položky podle primárního klíče.

DELETE https://localhost:5001/api/book/id/2000

curl -X DELETE "https://localhost:5001/api/book/id/2000"

var response = await httpClient.DeleteAsync("api/book/id/2000");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<DabResponse<Book>>();

if (result?.Error is not null)
{
    throw new Exception($"{result.Error.Code}: {result.Error.Message}");
}

response = requests.delete(f"{base_url}/api/book/id/2000")
response.raise_for_status()
data = response.json()

if "error" in data:
    err = data["error"]
    raise Exception(f"{err['code']}: {err['message']}")

const response = await fetch(`${baseUrl}/api/book/id/2000`, {
  method: "DELETE",
});
const data = await response.json();

if (data.error) {
  throw new Error(`${data.error.code}: ${data.error.message}`);
}

Pokročilé cesty REST s podadresáři

Poznámka:

Funkce tvůrce rozhraní Data API 2.0 popsané v této části jsou aktuálně ve verzi Preview a můžou se změnit před obecnou dostupností. Další informace najdete v tématu Co je nového ve verzi 2.0.

Cesty REST pro entity mohou zahrnovat lomítka k vytvoření segmentů adres URL ve stylu podadresáře. Tato konfigurace umožňuje pro vaše rozhraní API výraznější hierarchické struktury adres URL.

Nakonfigurujte cestu podadresáře ve vlastnosti entity rest.path :

{
  "entities": {
    "ShoppingCartItem": {
      "source": "dbo.ShoppingCartItem",
      "rest": {
        "path": "shopping-cart/item"
      }
    }
  }
}

Výsledkem této konfigurace je koncový bod:

GET /api/shopping-cart/item

Jazyk DAB používá pro směrování nejdelší porovnávání předpon, takže se před kratšími cestami shodují konkrétnější cesty. Kvůli bezpečnosti, ověřování blokuje vzory procházení cest (například ..), zpětná lomítka a oddělovače s procentovým kódováním.

Další informace najdete v konfiguraci cesty REST.

PUT a PATCH bez vyžadování klíčů pro automaticky generované primární klíče

Poznámka:

Pokud jsou všechny sloupce primárního klíče pro entitu automaticky generované (například IDENTITY sloupce v SQL Serveru), můžete odesílat PUT a PATCH požadavky bez zadání primárního klíče v adrese URL. DAB automaticky přiřazuje klíč během vkládání.

PUT /api/Book
Content-Type: application/json

{
  "title": "My New Book",
  "publisher_id": 1234
}

Tento požadavek vytvoří nový Book záznam s automaticky vygenerovaným primárním klíčem.

Pravidla pro operace bez klíčů

Všechny vynechané sloupce primárního klíče musí být automaticky vygenerovány. Pokud některý vynechaný klíčový sloupec není automaticky vygenerovaný, požadavek selže.
U složených primárních klíčů musíte do adresy URL zadat všechny negenerované části klíče, které nejsou automaticky generovány.
Tato funkce nemá vliv na uložené procedury. Nadále používají vlastní zpracování parametrů.
Dokument OpenAPI odráží bezklíčové operace na základní cestě entity (například PUT /api/Book bez klíčových segmentů).

Komprese odpovědí HTTP

Poznámka:

DAB podporuje kompresi odpovědí HTTP, aby se snížily velikosti datových částí a zlepšily rychlost přenosu. Konfigurace komprese v runtime.compression části konfiguračního souboru:

{
  "runtime": {
    "compression": {
      "level": "optimal"
    }
  }
}

Dostupné úrovně komprese:

Úroveň	Description
`optimal`	Vyrovnává poměr komprese a rychlost (doporučeno pro většinu scénářů)
`fastest`	Určuje prioritu rychlosti komprese oproti poměru.
`none`	Zakáže kompresi.

Další informace o konfiguraci komprese naleznete v tématu Konfigurace komprese modulu runtime.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-04-01

Sdílet prostřednictvím

Volání koncových bodů REST

Klíčová slova podporovaná v Tvůrci rozhraní Data API

Základní struktura

Typy dotazů

Filtrování výsledků

Řazení výsledků

Omezení výsledků :{#first-and-after}

Pokračování výsledků

Výběr pole (projekce)

Úprava dat

Vytvoření nového záznamu

Aktualizovat existující záznam

Odstranění záznamu

Pokročilé cesty REST s podadresáři

PUT a PATCH bez vyžadování klíčů pro automaticky generované primární klíče

Pravidla pro operace bez klíčů

Komprese odpovědí HTTP

Váš názor

Další materiály