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}

A kérés összetevői a következők:

Í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.

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

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 1001azonosí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

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:

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

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 $firstkombiná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.

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.

Kapcsolódó tartalom

• OpenAPI-
• REST konfigurációs referencia