Gazdagép REST-végpontjai a Data API Builderben
A Data API Builder egy RESTful webes API-t biztosít, amely lehetővé teszi táblák, nézetek és tárolt eljárások elérését egy csatlakoztatott adatbázisból. Az entitások egy adatbázis-objektumot jelölnek a Data API Builder futtatókörnyezet-konfigurációjában. Egy entitást a futtatókörnyezet konfigurációjában kell beállítani ahhoz, hogy elérhető legyen a REST API-végponton.
REST API-metódus meghívása
Egy erőforrásból (vagy entitásból) való olvasáshoz vagy íráshoz a következő mintával kell létrehoznia egy kérést:
{HTTP method} https://{base_url}/{rest-path}/{entity}
Jegyzet
Az URL-elérési út minden összetevője, beleértve az entitásokat és a lekérdezési paramétereket is, megkülönbözteti a kis- és nagybetűket.
A kérés összetevői a következők:
Leírás | |
---|---|
{HTTP method} |
A Data API buildernek küldött kéréshez használt HTTP-metódus |
{base_url} |
A Data API Builder egy példányát üzemeltető tartomány (vagy localhost-kiszolgáló és port) |
{rest-path} |
A futtatókörnyezet konfigurációjában beállított REST API-végpont alapútvonala |
{entity} |
Az adatbázis-objektum neve a futtatókörnyezet konfigurációjában meghatározottak szerint |
Íme egy példa GET kérés az book
entitásra, amely a REST-végpont alapja /api
egy helyi fejlesztési környezetben localhost
:
GET https:/localhost:5001/api/Book
HTTP-metódusok
A Data API Builder a kérelem HTTP-metódusával határozza meg, hogy milyen műveletet kell elvégeznie a kérelem által kijelölt entitáson. Az alábbi HTTP-parancsok érhetők el egy adott entitás engedélyeinek függvényében.
Módszer | Leírás |
---|---|
GET |
Nulla, egy vagy több elem lekérése |
POST |
Új elem létrehozása |
PATCH |
Frissítsen egy elemet új értékekkel, ha van ilyen. Ellenkező esetben hozzon létre egy új elemet |
PUT |
Ha van ilyen, cserélje le az elemet egy újra. Ellenkező esetben hozzon létre egy új elemet |
DELETE |
Elem törlése |
Rest path
A rest elérési út a Data API Builder REST API-jának helyét jelöli. Az elérési út konfigurálható a futtatókörnyezet konfigurációjában, és alapértelmezés szerint /api. További információ: REST-útvonal konfigurációs.
Entitás
Entitás a Rest API-erőforrásra való hivatkozáshoz használt terminológia a Data API Builderben. Alapértelmezés szerint egy entitás URL-útvonalának értéke a futtatókörnyezet konfigurációjában definiált entitásnév. Az entitás REST URL-elérési útvonalának értéke konfigurálható az entitás REST-beállításai között. További információ: entitáskonfigurációs.
Eredményhalmaz formátuma
A visszaadott eredmény egy ilyen formátumú JSON-objektum:
{
"value": []
}
A kért entitáshoz kapcsolódó elemek a value
tömbben érhetők el. Például:
{
"value": [
{
"id": 1000,
"title": "Foundation"
},
{
"id": 1001,
"title": "Foundation and Empire"
}
]
}
Jegyzet
Alapértelmezés szerint csak az első 100 elem lesz visszaadva.
KAP
A GET metódussal lekérheti a kívánt entitás egy vagy több elemét.
URL-paraméterek
A REST-végpontok lehetővé teszik egy elem lekérését az elsődleges kulcs alapján URL-paraméterekkel. Egyetlen elsődleges kulccsal rendelkező entitások esetében a formátum egyszerű:
GET /api/{entity}/{primary-key-column}/{primary-key-value}
Ha 1001
azonosítójú könyvet szeretne lekérni, használja a következőt:
GET /api/book/id/1001
Összetett elsődleges kulcsokkal rendelkező entitások esetén, ahol egy rekord egyedi azonosítására több oszlopot használnak, az URL-formátum az összes egymás utáni kulcsoszlopot tartalmazza:
GET /api/{entity}/{primary-key-column1}/{primary-key-value1}/{primary-key-column2}/{primary-key-value2}
Ha egy books
entitás id1
és id2
álló összetett kulccsal rendelkezik, a következőhöz hasonló könyvet kell lekérni:
GET /api/books/id1/123/id2/abc
Például:
A hívás így nézne ki:
### 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
Lekérdezési paraméterek
A REST-végpontok a következő lekérdezési paramétereket támogatják (a kis- és nagybetűk megkülönböztetik) a visszaadott elemek szabályozásához:
-
$select
: csak a kijelölt oszlopokat adja vissza -
$filter
: szűri a visszaadott elemeket -
$orderby
: meghatározza a visszaadott adatok rendezésének módját -
$first
és$after
: csak a felsőn
elemeket adja vissza
A lekérdezési paraméterek együtt használhatók.
$select
A lekérdezési paraméter $select
lehetővé teszi annak megadását, hogy mely mezőket kell visszaadni. Például:
### 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
Jegyzet
Ha a kért mezők egyike nem létezik, vagy a konfigurált engedélyek miatt nem érhető el, a rendszer egy 400 - Bad Request
ad vissza.
A $select
lekérdezési paraméter, más néven "előrejelzés" az API-válaszban visszaadott adatok méretének szabályozására szolgál. Csak a szükséges oszlopok esetén $select
csökkenti a hasznos adatok méretét, ami az elemzési idő minimalizálásával, a sávszélesség-használat csökkentésével és az adatfeldolgozás felgyorsításával javíthatja a teljesítményt. Ez az optimalizálás az adatbázisra is kiterjed. Itt csak a kért oszlopok lesznek lekérve.
$filter
A $filter
beállítás értéke egy predikátumkifejezés (logikai eredményt visszaadó kifejezés) az entitás mezőivel. A válasz csak azokat az elemeket tartalmazza, amelyekben a kifejezés igaz értéket ad ki. Például:
### 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
A $filter
beállítás által támogatott operátorok a következők:
Operátor | Típus | Leírás | Példa |
---|---|---|---|
eq |
Összehasonlítás | Egyenlő | title eq 'Hyperion' |
ne |
Összehasonlítás | Nem egyenlő | title ne 'Hyperion' |
gt |
Összehasonlítás | Nagyobb, mint | year gt 1990 |
ge |
Összehasonlítás | Nagyobb vagy egyenlő | year ge 1990 |
lt |
Összehasonlítás | Kisebb, mint | year lt 1990 |
le |
Összehasonlítás | Kisebb vagy egyenlő | year le 1990 |
and |
Logikus | Logikai és | year ge 1980 and year lt 1990 |
or |
Logikus | Logikai vagy | year le 1960 or title eq 'Hyperion' |
not |
Logikus | Logikai tagadás | not (year le 1960) |
( ) |
Csoportosítás | Elsőbbségi csoportosítás | (year ge 1970 or title eq 'Foundation') and pages gt 400 |
Jegyzet
$filter
egy kis- és nagybetűkre érzékeny argumentum.
Az Azure Data API Builder $filter
lekérdezési paramétere emlékeztethet néhány felhasználót az OData-ra, és ennek az az oka, hogy közvetlenül az OData szűrési képességei inspirálták. A szintaxis majdnem azonos, így az OData-t már jól ismerő fejlesztők könnyen átvehetnek és használhatnak. Ez a hasonlóság szándékos volt, amelynek célja, hogy ismerős és hatékony módot biztosítson az adatok különböző API-k közötti szűrésére.
$orderby
A orderby
paraméter értéke az elemek rendezéséhez használt kifejezések vesszővel tagolt listája.
A orderby
paraméter értékének minden kifejezésében szerepelhet a desc
utótag, amely csökkenő sorrendet kér, egy vagy több szóköz választja el a kifejezéstől.
Például:
### 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
Jegyzet
$orderBy
egy kis- és nagybetűkre érzékeny argumentum.
A $orderby
lekérdezési paraméter hasznos az adatok közvetlenül a kiszolgálón történő rendezéséhez, és könnyen kezelhető az ügyféloldalon is. Azonban más lekérdezési paraméterekkel, például $filter
és $first
kombinálva hasznossá válik. A paraméter lehetővé teszi, hogy a lapozás stabil és kiszámítható adathalmazt tartson fenn, miközben nagy gyűjteményeken keresztül lapoz.
$first
és $after
A $first
lekérdezési paraméter korlátozza az egyetlen kérelemben visszaadott elemek számát. Például:
GET /api/book?$first=5
Ez a kérés az első öt könyvet adja vissza. Az Azure Data API Builder $first
lekérdezési paramétere hasonló az SQL TOP
záradékához. Mindkettő a lekérdezésből visszaadott rekordok számának korlátozására szolgál. Ahogyan az SQL TOP
lehetővé teszi a lekérendő sorok mennyiségének megadását, $first
az API által visszaadott elemek számát is szabályozhatja.
$first
akkor hasznos, ha a teljes adatkészlet beolvasása nélkül szeretne beolvasni egy kis adathalmazt, például az első 10 találatot. A fő előnye a hatékonyság, mivel csökkenti a továbbított és feldolgozott adatok mennyiségét.
Jegyzet
Az Azure Data API Builderben az alapértelmezés szerint visszaadott sorok számát a konfigurációs fájl egy beállítása korlátozza. A felhasználók felülbírálhatják ezt a korlátot a $first
paraméterrel, hogy további sorokat kérhessenek, de továbbra is konfigurált maximális számú sor adható vissza. Emellett az egyetlen válaszban visszaadható megabájtok teljes száma is korlátozott, ami szintén konfigurálható.
Ha több elem érhető el a megadott korláton túl, a válasz tartalmaz egy nextLink
tulajdonságot:
{
"value": [],
"nextLink": "dab-will-generate-this-continuation-url"
}
A nextLink
a $after
lekérdezési paraméterrel használható a következő elemkészlet lekéréséhez:
GET /api/book?$first={n}&$after={continuation-data}
Ez a folytatási megközelítés kurzoralapú lapozást használ. Az egyedi kurzor az adathalmaz egy adott elemére mutató hivatkozás, amely meghatározza, hogy hol folytathatja az adatok beolvasását a következő készletben. Az eltolásokat vagy indexeket használó indexlapozással ellentétben a kurzoralapú lapozás nem függ a rekordok kihagyásától. A kurzor folytatása megbízhatóbbá teszi nagy adathalmazokkal vagy gyakran változó adatokkal. Ehelyett zökkenőmentes és konzisztens adatlekérési folyamatot biztosít, mivel a kurzor alapján pontosan ott kezdődik, ahol az utolsó lekérdezés abbahagyta.
Például:
### 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}
POSTA
Hozzon létre egy új elemet a megadott entitáshoz. Például:
POST /api/book
Content-type: application/json
{
"id": 2000,
"title": "Do Androids Dream of Electric Sheep?"
}
A POST-kérelem létrehoz egy új könyvet. Minden olyan mezőt meg kell adni, amely nem lehet null értékű. Ha a rendszer sikeresen visszaadja a teljes entitásobjektumot, beleértve a null mezőket is:
{
"value": [
{
"id": 2000,
"title": "Do Androids Dream of Electric Sheep?",
"year": null,
"pages": null
}
]
}
HELYEZ
A PUT létrehozza vagy lecseréli a megadott entitás egy elemét. A lekérdezési minta a következő:
PUT /api/{entity}/{primary-key-column}/{primary-key-value}
Például:
PUT /api/book/id/2001
Content-type: application/json
{
"title": "Stranger in a Strange Land",
"pages": 525
}
Ha egy elem rendelkezik a megadott elsődleges kulccsal 2001
, a megadott adatok teljesen lecserélik az adott elem. Ha az elsődleges kulccsal rendelkező elem nem létezik, a rendszer új elemet hoz létre.
Az eredmény mindkét esetben a következőhöz hasonló:
{
"value": [
{
"id": 2001,
"title": "Stranger in a Strange Land",
"year": null,
"pages": 525
}
]
}
FOLT
A PATCH létrehozza vagy frissíti a megadott entitás elemét. A program csak a megadott mezőket érinti. A kérelem törzsében nem megadott mezőkre nincs hatással. Ha a megadott elsődleges kulccsal rendelkező elem nem létezik, létrejön egy új elem.
A lekérdezési minta a következő:
PATCH /api/{entity}/{primary-key-column}/{primary-key-value}
Például:
PATCH /api/book/id/2001
Content-type: application/json
{
"year": 1991
}
Az eredmény a következőhöz hasonló:
{
"value": [
{
"id": 2001,
"title": "Stranger in a Strange Land",
"year": 1991,
"pages": 525
}
]
}
TÖRÖL
A DELETE törli a megadott entitás elemét. A lekérdezési minta a következő:
DELETE /api/{entity}/{primary-key-column}/{primary-key-value}
Például:
DELETE /api/book/id/2001
Ha sikeres, az eredmény egy üres válasz, amely a 204-s állapotkóddal rendelkezik.
Adatbázistranzakciók REST API-kérésekhez
POST, PUT, PATCH és DELETE API-kérések feldolgozása; A Data API Builder egy tranzakcióban hozza létre és hajtja végre az adatbázis-lekérdezéseket.
Az alábbi táblázat felsorolja azokat az elkülönítési szinteket, amelyekkel az egyes adatbázistípusokhoz létrejönnek a tranzakciók.
Adatbázis típusa | Elkülönítési szint | További információ |
---|---|---|
Azure SQL (vagy) SQL Server | Lekötött olvasás | Azure SQL- |
MySQL | Ismételhető olvasás | MySQL- |
PostgreSQL | Lekötött olvasás | PostgreSQL |