REST-végpontok meghívása

A Data API Builder (DAB) egy RESTful webes API-t biztosít, amellyel táblákat, nézeteket és tárolt eljárásokat érhet el egy csatlakoztatott adatbázisból. Minden közzétett adatbázis-objektum entitásként van definiálva a futtatókörnyezet konfigurációjában.

Alapértelmezés szerint a DAB a KÖVETKEZŐ helyen üzemelteti a REST-végpontokat:

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

Megjegyzés:

Minden elérési útösszetevő és lekérdezési paraméter megkülönbözteti a kis- és nagybetűket.

A Data API Builderben támogatott kulcsszavak

Fogalom	REST	Alkalmazás célja
Projection	$select	Adja meg, hogy mely mezőket adja vissza
Filtering	$filter	Sorok korlátozása feltétel szerint
Rendezés	$orderby	Rendezési sorrend meghatározása
Oldalméret	$first	Az elemek korlátozása oldalanként
Folytatás	$after	Folytatás az utolsó oldalról

Alapszintű struktúra

REST API meghívásához hozzon létre egy kérést az alábbi mintával:

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

Példa az entitás összes rekordjának olvasására book :

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

A válasz egy tömböt tartalmazó value JSON-objektum. A lapozási és hibainformációk csak akkor jelennek meg, ha vannak.

Megjegyzés:

Alapértelmezés szerint a DAB lekérdezésenként legfeljebb 100 elemet ad vissza, kivéve, ha másként van konfigurálva (runtime.pagination.default-page-size).

HTTP

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

Siker:

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

Siker az oldalkezeléssel:

{
  "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"
}

Üres eredmény (az elem nem található):

{
  "value": []
}

Megjegyzés:

A nem létező elsődleges kulcsra irányuló GET-kérés egy üres value tömböt ad vissza, nem 404 Not Found.200 OK Keressen egy üres tömböt annak megállapításához, hogy az elem létezik-e.

cURL

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

C#

A következő modellosztályok deszerializálják a DAB-válaszokat:

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; }
}

Hívja meg az API-t, és deszerializálja a választ:

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 ?? [];
}

Python

Az alábbi adatosztályok DAB-válaszokat modellezhetnek:

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

Hívja meg az API-t, és elemezje a választ:

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", [])]

JavaScript

A következő függvény meghívja az API-t:

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éldahasználat:

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

Lekérdezéstípusok

Minden REST-entitás támogatja a kollekciós, valamint az egyrekordos olvasást is.

Operation	Leírás
GET /api/{entity}	Rekordlistát ad vissza
GET /api/{entity}/{primary-key-column}/{primary-key-value}	Egy rekordot ad vissza elsődleges kulcs szerint

Példa egy rekord visszaadására:

GET /api/book/id/1010

Több értéket visszaadó példa:

GET /api/book

Eredmények szűrése

A lekérdezési $filter paraméterrel korlátozhatja a visszaadott rekordokat.

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

Ez a lekérdezés az összes olyan könyvet visszaadja, amelynek a címe "Foundation" (Alapozás) értékű.

A szűrők logikai operátorokat is tartalmazhatnak összetettebb lekérdezésekhez:

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

További információ: $filter argumentum referenciája.

Találatok rendezése

A $orderby paraméter határozza meg a rekordok rendezésének módját.

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

Ez visszaadja a year szerint csökkenő sorrendben, majd a title alapján rendezett könyveket.

További információ: $orderby argumentum referenciája.

Eredmények korlátozása {#first-and-after}

A $first paraméter korlátozza, hogy egy kérelem hány rekordot ad vissza.

GET /api/book?$first=5

Ez az első öt könyvet adja vissza, alapértelmezés szerint az elsődleges kulcs szerint rendezve. A konfigurált maximális oldalméretet is kérheti $first=-1 , amely alapértelmezés szerint 100 elem. Konfigurálja ezt a korlátot runtime.pagination.default-page-size a konfigurációs fájlban.

További információ: $first argumentum referenciája.

Folyamatos eredmények

A következő oldal lekéréséhez használja $after az előző válaszból származó folytatási tokent.

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

A $after jogkivonat azonosítja, hogy hol fejeződött be az utolsó lekérdezés. További információ: $after argumentum referenciája.

Mezőválasztás (projekció)

A válaszban szereplő mezők szabályozására használható $select .

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

Ez csak a megadott oszlopokat adja vissza. Ha egy mező hiányzik vagy nem érhető el, a DAB ad vissza 400 Bad Request.

További információ: $select argumentum referenciája.

Adatok módosítása

A REST API az entitásengedélyek függvényében támogatja a létrehozási, frissítési és törlési műveleteket is.

Módszer	Action
POST	Új elem létrehozása
PUT	Meglévő elem cseréje (vagy ha hiányzik a létrehozás)
PATCH	Meglévő elem frissítése (vagy ha hiányzik a létrehozás)
DELETE	Elem eltávolítása elsődleges kulcs alapján

Fontos

Az upsert (insert-if-missing) viselkedése PUTPATCH csak akkor működik, ha az adatbázis explicit elsődleges kulcsértékeket engedélyez. Az automatikusan generált kulcsokkal rendelkező táblák esetén (mint például az SQL Server IDENTITY oszlopaiban vagy a PostgreSQL SERIAL oszlopaiban) egy PUT vagy PATCH egy nem létező kulcshoz a 404 Not Found értéket ad vissza, mivel az adatbázis elutasítja az explicit beszúrásokat az automatikusan generált oszlopokba. Rekordokat POST hozhat létre automatikus kulcsokkal rendelkező táblákon, vagy kulcs nélküli PUT és PATCH használatával lehetővé teszi, hogy a DAB automatikusan hozzárendelje a kulcsot.

Új rekord létrehozása

Új elem létrehozásához használható POST .

HTTP

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

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

cURL

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

C#

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}");
}

Python

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']}")

JavaScript

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}`);
}

Egy létező rekord frissítése

Egy meglévő elem adott mezőinek frissítésére használható PATCH .

HTTP

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

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

cURL

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}'

C#

Jótanács

Alapértelmezés szerint a DAB elutasítja a kérelem törzsében azokat a mezőket, amelyek nem léteznek az adatbázisban, vagy amelyek az URL-címhez tartoznak (például a PATCH és a DELETE elsődleges kulcsmezőihez). Ez a viselkedés külön C#-típust igényel: egyet a POST kulcsaival, egyet pedig frissítések nélkül. Ha az összes művelethez hasonló Book egyetlen típust szeretne újra felhasználni, állítsa be runtime.rest.request-body-strictfalse a konfigurációban.

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}");
}

Python

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']}")

JavaScript

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}`);
}

Rekord törlése

Használja a DELETE-t egy elem elsődleges kulcs szerinti eltávolításához.

HTTP

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

cURL

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

C#

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}");
}

Python

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']}")

JavaScript

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}`);
}

Speciális REST-útvonalak alkönyvtárakkal

Megjegyzés:

Az ebben a szakaszban ismertetett Data API Builder 2.0 funkció jelenleg előzetes verzióban érhető el, és az általános rendelkezésre állás előtt változhat. További információ: A 2.0-s verzió újdonságai.

Az entitás REST útvonalai tartalmazhatnak perjeleket, hogy alkönyvtár stílusú URL-szegmenseket hozzanak létre. Ez a konfiguráció kifejezőbb és hierarchikusabb URL-struktúrákat tesz lehetővé az API-hoz.

Az entitás rest.path tulajdonságában egy alkönyvtár elérési útját konfigurálja:

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

Ez a konfiguráció a végpontot eredményezi:

GET /api/shopping-cart/item

A DAB a leghosszabb előtag-megfeleltetéseket használja az útválasztáshoz, így a rövidebbek előtt konkrétabb útvonalakat kell egyeztetni. A biztonság érdekében az érvényesítés blokkolja az elérési utak bejárási mintáit (például ..), a visszaperjeleket és a százalékban kódolt elválasztókat.

További információkért tekintse meg a REST-útvonal konfigurációját.

Kulcs nélküli PUT és PATCH az automatikusan létrehozott elsődleges kulcsokhoz

Megjegyzés:

Az ebben a szakaszban ismertetett Data API Builder 2.0 funkció jelenleg előzetes verzióban érhető el, és az általános rendelkezésre állás előtt változhat. További információ: A 2.0-s verzió újdonságai.

Ha egy entitás összes elsődleges kulcsoszlopa automatikusan létrejön (például IDENTITY az SQL Server oszlopai), az URL-címben szereplő elsődleges kulcs megadása nélkül is küldhet PUT és PATCH kérhet. A DAB automatikusan hozzárendeli a kulcsot a beszúrás során.

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

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

Ez a kérés létrehoz egy új Book rekordot egy automatikusan létrehozott elsődleges kulccsal.

Kulcs nélküli műveletek szabályai

• Az összes kihagyott elsődleges kulcsoszlopot automatikusan létre kell hozni. Ha a kihagyott kulcsoszlop nem automatikusan jön létre, a kérés meghiúsul.
• Összetett elsődleges kulcsok esetén továbbra is meg kell adnia a kulcs nem automatikusan létrehozott részeit az URL-címben.
• A tárolt eljárásokat ez a funkció nem érinti. Továbbra is saját paraméterkezelést használnak.
• Az OpenAPI-dokumentum az alapentitási útvonal kulcs nélküli műveleteit tükrözi (például PUT /api/Book kulcsszegmensek nélkül).

HTTP-választömörítés

Megjegyzés:

Az ebben a szakaszban ismertetett Data API Builder 2.0 funkció jelenleg előzetes verzióban érhető el, és az általános rendelkezésre állás előtt változhat. További információ: A 2.0-s verzió újdonságai.

A DAB támogatja a HTTP-választömörítést a hasznos adatok méretének csökkentése és az átviteli sebesség javítása érdekében. Konfigurálja a tömörítést a runtime.compression konfigurációs fájl szakaszában:

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

Elérhető tömörítési szintek:

szint	Leírás
optimal	Tömörítési arány és sebesség kiegyensúlyozása (a legtöbb forgatókönyv esetében ajánlott)
fastest	Rangsorolja a tömörítési sebességet az arányhoz viszonyítva
none	A tömörítés letiltása

A tömörítés konfigurálásáról további információt a futtatókörnyezeti tömörítés konfigurálásával kapcsolatban talál.