Hostování koncových bodů REST v Tvůrci rozhraní Data API

Článek
12/19/2024

Tvůrce rozhraní DATA API poskytuje webové rozhraní RESTful API, které umožňuje přístup k tabulkám, zobrazením a uloženým procedurám z připojené databáze. Entity představují databázový objekt v konfiguraci modulu runtime tvůrce rozhraní Data API. Aby byla entita dostupná v koncovém bodu rozhraní REST API, musí být nastavená v konfiguraci modulu runtime.

Volání metody ROZHRANÍ REST API

Pokud chcete číst z prostředku (nebo entitu) nebo zapisovat do tohoto prostředku, vytvořte požadavek pomocí následujícího vzoru:

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

Poznámka

U všech součástí cesty URL, včetně entit a parametrů dotazu, se rozlišují malá a velká písmena.

Mezi komponenty požadavku patří:

	Popis
`{HTTP method}`	Metoda HTTP použitá v požadavku na tvůrce rozhraní API pro data
`{base_url}`	Doména (nebo server a port localhost), který hostuje instanci Tvůrce rozhraní Data API
`{rest-path}`	Základní cesta koncového bodu rozhraní REST API nastaveného v konfiguraci modulu runtime
`{entity}`	Název databázového objektu definovaný v konfiguraci modulu runtime

Tady je příklad požadavku GET na entitu book umístěnou v základním koncovém bodu REST /api v místním vývojovém prostředí localhost:

GET https:/localhost:5001/api/Book

Metody HTTP

Tvůrce rozhraní API pro data na vašem požadavku používá metodu HTTP k určení akce, která se má provést u určené entity požadavku. K dispozici jsou následující příkazy HTTP, které jsou závislé na oprávněních nastavených pro konkrétní entitu.

Metoda	Popis
`GET`	Získání nuly, jedné nebo více položek
`POST`	Vytvoření nové položky
`PATCH`	Aktualizujte položku s novými hodnotami, pokud existuje. Jinak vytvořte novou položku.
`PUT`	Položku nahraďte novou, pokud existuje. Jinak vytvořte novou položku.
`DELETE`	Odstranění položky

Cesta k restu

Cesta rest určuje umístění rozhraní REST API tvůrce dat. Cesta je konfigurovatelná v konfiguraci modulu runtime a ve výchozím nastavení je nastavena na hodnotu /api. Pro více informací si přečtěte kapitolu Konfigurace cesty REST.

Entita

entity je terminologie použitá k odkazování na prostředek rozhraní REST API v Tvůrci rozhraní Data API. Ve výchozím nastavení je hodnota trasy adresy URL entity název entity definovaný v konfiguraci modulu runtime. Hodnota cesty k adrese URL REST entity je konfigurovatelná v nastavení REST entity. Pro více informací se podívejte na konfigurace entity.

Formát sady výsledků

Vrácený výsledek je objekt JSON s tímto formátem:

{
    "value": []    
}

Položky související s požadovanou entitou jsou k dispozici v poli value. Například:

{
  "value": [
    {
      "id": 1000,
      "title": "Foundation"
    },
    {
      "id": 1001,
      "title": "Foundation and Empire"
    }
  ]
}

Poznámka

Ve výchozím nastavení se vrátí pouze prvních 100 položek.

DOSTAT

Pomocí metody GET můžete načíst jednu nebo více položek požadované entity.

Parametry adresy URL

Koncové body REST umožňují načíst položku podle primárního klíče pomocí parametrů adresy URL. U entit s jedním primárním klíčem je formát jednoduchý:

GET /api/{entity}/{primary-key-column}/{primary-key-value}

K načtení knihy s ID 1001použijete:

GET /api/book/id/1001

U entit s složenými primárními klíči, kde se k jedinečné identifikaci záznamu používá více než jeden sloupec, obsahuje formát adresy URL všechny klíčové sloupce v posloupnosti:

GET /api/{entity}/{primary-key-column1}/{primary-key-value1}/{primary-key-column2}/{primary-key-value2}

Pokud má entita books složený klíč skládající se z id1 a id2, načtete konkrétní knihu takto:

GET /api/books/id1/123/id2/abc

Například:

Takto by volání vypadalo:

### Retrieve a book by a single primary key
GET /api/book/id/1001

### Retrieve an author by a single primary key
GET /api/author/id/501

### Retrieve a book by compound primary keys (id1 and id2)
GET /api/books/id1/123/id2/abc

### Retrieve an order by compound primary keys (orderId and customerId)
GET /api/orders/orderId/789/customerId/456

### Retrieve a product by compound primary keys (categoryId and productId)
GET /api/products/categoryId/electronics/productId/987

### Retrieve a course by compound primary keys (departmentCode and courseNumber)
GET /api/courses/departmentCode/CS/courseNumber/101

Parametry dotazu

Koncové body REST podporují následující parametry dotazu (rozlišují se malá a velká písmena) pro řízení vrácených položek:

$select: vrátí pouze vybrané sloupce.
$filter: filtruje vrácené položky.
$orderby: definuje způsob řazení vrácených dat.
$first a $after: vrátí pouze nejlepší n položky.

Parametry dotazu je možné použít společně.

`$select`

Parametr dotazu $select umožňuje určit, která pole se musí vrátit. Například:

### Get all fields
GET /api/author

### Get only first_name field
GET /api/author?$select=first_name

### Get only first_name and last_name fields
GET /api/author?$select=first_name,last_name

Poznámka

Pokud některá z požadovaných polí neexistuje nebo není přístupná kvůli nakonfigurovaným oprávněním, vrátí se 400 - Bad Request.

Parametr dotazu $select označovaný také jako projekce se používá k řízení velikosti dat vrácených v odpovědi rozhraní API. Pouze s potřebnými sloupci $select snižuje velikost datové části, což může zlepšit výkon tím, že minimalizuje čas analýzy, snižuje spotřebu šířky pásma a zrychluje zpracování dat. Tato optimalizace se vztahuje na databázi. Tam se načtou jenom požadované sloupce.

`$filter`

Hodnota možnosti $filter je predikátový výraz (výraz, který vrací booleovský výsledek) využívající pole entity. Do odpovědi se zahrnou pouze položky, ve kterých se výraz vyhodnotí jako Pravda. Například:

### Get books titled "Hyperion" (Equal to)
GET /api/book?$filter=title eq 'Hyperion'

### Get books not titled "Hyperion" (Not equal to)
GET /api/book?$filter=title ne 'Hyperion'

### Get books published after 1990 (Greater than)
GET /api/book?$filter=year gt 1990

### Get books published in or after 1990 (Greater than or equal to)
GET /api/book?$filter=year ge 1990

### Get books published before 1991 (Less than)
GET /api/book?$filter=year lt 1991

### Get books published in or before 1990 (Less than or equal to)
GET /api/book?$filter=year le 1990

### Get books published between 1980 and 1990 (Logical and)
GET /api/book?$filter=year ge 1980 and year le 1990

### Get books published before 1960 or titled "Hyperion" (Logical or)
GET /api/book?$filter=year le 1960 or title eq 'Hyperion'

### Get books not published before 1960 (Logical negation)
GET /api/book?$filter=not (year le 1960)

### Get books published in 1970 or later, and either titled "Foundation" or with more than 400 pages (Grouping)
GET /api/book?$filter=(year ge 1970 or title eq 'Foundation') and pages gt 400

Operátory podporované možností $filter jsou:

Operátor	Typ	Popis	Příklad
`eq`	Porovnání	Rovný	`title eq 'Hyperion'`
`ne`	Porovnání	Nerovná se	`title ne 'Hyperion'`
`gt`	Porovnání	Větší než	`year gt 1990`
`ge`	Porovnání	Větší než nebo rovno	`year ge 1990`
`lt`	Porovnání	Méně než	`year lt 1990`
`le`	Porovnání	Menší než nebo rovno	`year le 1990`
`and`	Logický	Logické a	`year ge 1980 and year lt 1990`
`or`	Logický	Logická nebo	`year le 1960 or title eq 'Hyperion'`
`not`	Logický	Logická negace	`not (year le 1960)`
`( )`	Seskupení	Seskupování priorit	`(year ge 1970 or title eq 'Foundation') and pages gt 400`

Poznámka

$filter je argument rozlišující velká a malá písmena.

Parametr dotazu $filter v Azure Data API Builderu může připomenout některé uživatele OData, a to proto, že byl přímo inspirovaný možnostmi filtrování OData. Syntaxe je téměř identická a vývojářům, kteří už znají OData, můžou vybírat a používat. Tato podobnost byla záměrná, zaměřená na poskytování známého a výkonného způsobu filtrování dat napříč různými rozhraními API.

`$orderby`

Hodnota parametru orderby je čárkami oddělený seznam výrazů použitých k řazení položek.

Každý výraz v hodnotě parametru orderby může obsahovat příponu desc pro sestupné pořadí, která je oddělena od výrazu jednou nebo více mezerami.

Například:

### Order books by title in ascending order
GET /api/book?$orderby=title

### Order books by title in ascending order
GET /api/book?$orderby=title asc

### Order books by title in descending order
GET /api/book?$orderby=title desc

### Order books by year of publication in ascending order, then by title in ascending order
GET /api/book?$orderby=year asc, title asc

### Order books by year of publication in descending order, then by title in ascending order
GET /api/book?$orderby=year desc, title asc

### Order books by number of pages in ascending order, then by title in descending order
GET /api/book?$orderby=pages asc, title desc

### Order books by title in ascending order, then by year of publication in descending order
GET /api/book?$orderby=title asc, year desc

Poznámka

$orderBy je argument citlivý na velikost písmen.

Parametr dotazu $orderby je cenný pro řazení dat přímo na serveru, snadno se zpracovává i na straně klienta. Nicméně, to je užitečné v kombinaci s jinými parametry dotazu, jako jsou $filter a $first. Parametr umožňuje stránkování udržovat stabilní a předvídatelnou datovou sadu při stránkování prostřednictvím velkých kolekcí.

`$first` a `$after`

Parametr dotazu $first omezuje počet položek vrácených v jednom požadavku. Například:

GET /api/book?$first=5

Tento požadavek vrátí prvních pět knih. Parametr dotazu $first v Azure Data API Builderu je podobný klauzuli TOP v SQL. Obě se používají k omezení počtu záznamů vrácených z dotazu. Stejně jako TOP v SQL umožňuje zadat množství řádků, které se mají načíst, $first umožňuje řídit počet položek vrácených rozhraním API. $first je užitečné, když chcete načíst malou podmnožinu dat, například prvních 10 výsledků, aniž byste museli načíst celou datovou sadu. Hlavní výhodou je efektivita, protože snižuje množství přenášených a zpracovávaných dat.

Poznámka

V Tvůrci rozhraní Azure Data API je počet řádků vrácených ve výchozím nastavení omezený nastavením v konfiguračním souboru. Uživatelé můžou tento limit přepsat pomocí parametru $first k vyžádání dalších řádků, ale stále existuje nakonfigurovaný maximální počet řádků, které se dají vrátit celkově. Kromě toho platí omezení celkového počtu megabajtů, které se dají vrátit v jedné odpovědi, což je také možné konfigurovat.

Pokud je k dispozici více položek nad rámec zadaného limitu, odpověď obsahuje vlastnost nextLink:

{
    "value": [],
    "nextLink": "dab-will-generate-this-continuation-url"
}

K načtení další sady položek můžete použít nextLink s parametrem dotazu $after:

GET /api/book?$first={n}&$after={continuation-data}

Tento přístup pro pokračování používá stránkování na základě kurzoru. Jedinečný kurzor je odkaz na konkrétní položku v datové sadě, která určuje, kde pokračovat v načítání dat v další sadě. Na rozdíl od stránkování indexu, která používá posuny nebo indexy, se stránkování založené na kurzorech nespoléhá na přeskakování záznamů. Pokračování kurzoru usnadňuje práci s velkými datovými sadami nebo často se měnícími daty. Místo toho zajišťuje hladký a konzistentní tok načítání dat tím, že začne přesně tam, kde poslední dotaz skončil, na základě zadaného kurzoru.

Například:

### Get the first 5 books explicitly
GET /api/book?$first=5

### Get the next set of 5 books using the continuation token
GET /api/book?$first=5&$after={continuation-token}

### Get the first 10 books, ordered by title
GET /api/book?$first=10&$orderby=title asc

### Get the next set of 10 books after the first set, ordered by title
GET /api/book?$first=10&$after={continuation-token}&$orderby=title asc

### Get books without specifying $first (automatic pagination limit)
GET /api/book

### Get the next set of books using the continuation token without specifying $first
GET /api/book?$after={continuation-token}

POST

Vytvořte novou položku pro zadanou entitu. Například:

POST /api/book
Content-type: application/json

{
  "id": 2000,
  "title": "Do Androids Dream of Electric Sheep?"
}

Požadavek POST vytvoří novou knihu. Všechna pole, která nemohou mít hodnotu null, musí být zadána. Pokud se celý objekt entity včetně všech polí null úspěšně vrátí:

{
  "value": [
    {
      "id": 2000,
      "title": "Do Androids Dream of Electric Sheep?",
      "year": null,
      "pages": null
    }
  ]
}

DÁT

PUT vytvoří nebo nahradí položku zadané entity. Vzor dotazu je následující:

PUT /api/{entity}/{primary-key-column}/{primary-key-value}

Například:

PUT /api/book/id/2001
Content-type: application/json

{  
  "title": "Stranger in a Strange Land",
  "pages": 525
}

Pokud je položka se zadaným primárním klíčem 2001, zadaná data zcela nahradí dané položky. Pokud položka s tímto primárním klíčem neexistuje, vytvoří se nová položka.

V obou případech je výsledek podobný následujícímu:

{
  "value": [
    {
      "id": 2001,
      "title": "Stranger in a Strange Land",
      "year": null,
      "pages": 525
    }
  ]
}

Hlavička požadavku HTTP `If-Match: *`

Hlavička HTTP If-Match: * zajišťuje operaci aktualizace, se provádí pouze v případě, že prostředek existuje. Pokud prostředek neexistuje, operace selže se stavovým kódem HTTP: 404 Not Found. Pokud je hlavička If-Matchvynechána, výchozím chováním je provedení upsert, který vytvoří prostředek, pokud ještě neexistuje.

Příklad :

PUT /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json

{
  "title": "Stranger in a Strange Land",
  "pages": 525
}

Poznámka

Pokud v hlavičce If-Match zadáte jinou hodnotu než *, tvůrce rozhraní Data API vrátí 400 Bad Request chybu, protože porovnávání na základě značky ETag se nepodporuje.

ZÁPLATA

PATCH vytvoří nebo aktualizuje položku zadané entity. Ovlivněna jsou pouze zadaná pole. Všechna pole nezadaná v textu požadavku nejsou ovlivněna. Pokud položka se zadaným primárním klíčem neexistuje, vytvoří se nová položka.

Vzor dotazu je následující:

PATCH /api/{entity}/{primary-key-column}/{primary-key-value}

Například:

PATCH /api/book/id/2001
Content-type: application/json

{    
  "year": 1991
}

Výsledek vypadá přibližně takto:

{
  "value": [
    {
      "id": 2001,
      "title": "Stranger in a Strange Land",
      "year": 1991,
      "pages": 525
    }
  ]
}

Hlavička požadavku HTTP `If-Match: *`

Příklad :

PATCH /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json

{
    "year": 1991
}

Poznámka

Pokud v hlavičce If-Match zadáte jinou hodnotu než *, tvůrce rozhraní Data API vrátí 400 Bad Request chybu, protože porovnávání na základě značky ETag se nepodporuje.

VYMAZAT

DELETE odstraní položku zadané entity. Vzor dotazu je následující:

DELETE /api/{entity}/{primary-key-column}/{primary-key-value}

Například:

DELETE /api/book/id/2001

V případě úspěchu je výsledkem prázdná odpověď se stavovým kódem 204.

Databázové transakce pro požadavky rozhraní REST API

Zpracování požadavků ROZHRANÍ POST, PUT, PATCH a DELETE API; Tvůrce rozhraní Data API vytváří a spouští databázové dotazy v transakci.

Následující tabulka uvádí úrovně izolace, se kterými se transakce vytvářejí pro každý typ databáze.

Typ databáze	Úroveň izolace	Další informace
Azure SQL (nebo) SQL Server	Přečteno potvrzeno	Azure SQL
MySQL	Opakovatelné čtení	MySQL
PostgreSQL	Přečteno potvrzeno	PostgreSQL

OpenAPI
Referenční konfigurace REST

Sdílet prostřednictvím

Hostování koncových bodů REST v Tvůrci rozhraní Data API

Volání metody ROZHRANÍ REST API

Metody HTTP

Cesta k restu

Entita

Formát sady výsledků

DOSTAT

Parametry adresy URL

Například:

Parametry dotazu

`$select`

`$filter`

`$orderby`

`$first` a `$after`

POST

DÁT

Hlavička požadavku HTTP `If-Match: *`

ZÁPLATA

Hlavička požadavku HTTP `If-Match: *`

VYMAZAT

Databázové transakce pro požadavky rozhraní REST API

Váš názor

Další materiály

Sdílet prostřednictvím

Hostování koncových bodů REST v Tvůrci rozhraní Data API

Volání metody ROZHRANÍ REST API

Metody HTTP

Cesta k restu

Entita

Formát sady výsledků

DOSTAT

Parametry adresy URL

Například:

Parametry dotazu

$select

$filter

$orderby

$first a $after

POST

DÁT

Hlavička požadavku HTTP If-Match: *

ZÁPLATA

Hlavička požadavku HTTP If-Match: *

VYMAZAT

Databázové transakce pro požadavky rozhraní REST API

Související obsah

Váš názor

Další materiály

`$select`

`$filter`

`$orderby`

`$first` a `$after`

Hlavička požadavku HTTP `If-Match: *`

Hlavička požadavku HTTP `If-Match: *`