Värd-REST-slutpunkter i Data API Builder

Artikel
08/14/2024

Data API Builder tillhandahåller ett RESTful-webb-API som gör att du kan komma åt tabeller, vyer och lagrade procedurer från en ansluten databas. Entiteter representerar ett databasobjekt i Data API Builder-körningskonfigurationen. En entitet måste anges i körningskonfigurationen för att den ska vara tillgänglig på REST API-slutpunkten.

Anropa en REST API-metod

Om du vill läsa från eller skriva till en resurs (eller en entitet) skapar du en begäran med hjälp av följande mönster:

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

Not

Alla komponenter i URL-sökvägen, inklusive entiteter och frågeparametrar, är skiftlägeskänsliga.

Komponenterna i en begäran är:

	Beskrivning
`{HTTP method}`	HTTP-metoden som används för begäran till Data API Builder
`{base_url}`	Domänen (eller localhost-servern och porten) som är värd för en instans av Data API Builder
`{rest-path}`	Bassökvägen för REST API-slutpunkten som angetts i körningskonfigurationen
`{entity}`	Namnet på databasobjektet enligt definitionen i körningskonfigurationen

Här är ett exempel på EN GET-begäran på den book entitet som finns under REST-slutpunktsbasen /api i en lokal utvecklingsmiljö localhost:

GET https:/localhost:5001/api/Book

HTTP-metoder

Data API Builder använder HTTP-metoden på din begäran för att avgöra vilken åtgärd som ska vidtas på den avsedda entiteten för begäran. Följande HTTP-verb är tillgängliga, beroende på vilka behörigheter som angetts för en viss entitet.

Metod	Beskrivning
`GET`	Hämta noll, ett eller flera objekt
`POST`	Skapa ett nytt objekt
`PATCH`	Uppdatera ett objekt med nya värden om det finns något. Annars skapar du ett nytt objekt
`PUT`	Ersätt ett objekt med ett nytt om det finns ett. Annars skapar du ett nytt objekt
`DELETE`	Ta bort ett objekt

Viloväg

Restsökvägen anger platsen för Data API Builder REST API. Sökvägen kan konfigureras i körningskonfigurationen och standardinställningen är /api. Mer information finns i KONFIGURATION av REST-sökväg.

Enhet

Entity är den terminologi som används för att referera till en REST API-resurs i Data API Builder. Som standard är URL-vägvärdet för en entitet det entitetsnamn som definierats i körningskonfigurationen. En entitets rest-URL-sökvägsvärde kan konfigureras i entitetens REST-inställningar. Mer information finns i entitetskonfiguration.

Format för resultatuppsättning

Det returnerade resultatet är ett JSON-objekt med det här formatet:

{
    "value": []    
}

Objekten som är relaterade till den begärda entiteten är tillgängliga i matrisen value. Till exempel:

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

Not

Endast de första 100 objekten returneras som standard.

FÅ

Med metoden GET kan du hämta ett eller flera objekt i den önskade entiteten.

URL-parametrar

MED REST-slutpunkter kan du hämta ett objekt med dess primära nyckel med hjälp av URL-parametrar. För entiteter med en enda primärnyckel är formatet enkelt:

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

Om du vill hämta en bok med ett ID för 1001använder du:

GET /api/book/id/1001

För entiteter med sammansatta primära nycklar, där mer än en kolumn används för att unikt identifiera en post, innehåller URL-formatet alla nyckelkolumner i följd:

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

Om en books entitet har en sammansatt nyckel som består av id1 och id2hämtar du en viss bok som den här:

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

Till exempel:

Så här skulle ett samtal se ut:

### 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

Frågeparametrar

REST-slutpunkter stöder följande frågeparametrar (skiftlägeskänsliga) för att styra de returnerade objekten:

$select: returnerar endast de markerade kolumnerna
$filter: filtrerar de returnerade objekten
$orderby: definierar hur returnerade data sorteras
$first och $after: returnerar endast de översta n objekten

Frågeparametrar kan användas tillsammans.

`$select`

Frågeparametern $select tillåta att ange vilka fält som måste returneras. Till exempel:

### 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

Not

Om något av de begärda fälten inte finns eller inte är tillgängligt på grund av konfigurerade behörigheter returneras en 400 - Bad Request.

Frågeparametern $select, även kallad "projektion", används för att styra storleken på de data som returneras i ett API-svar. Med endast nödvändiga kolumner minskar $select nyttolaststorleken, vilket kan förbättra prestandan genom att minimera parsningstiden, minska bandbreddsanvändningen och påskynda databearbetningen. Den här optimeringen sträcker sig till databasen. Där hämtas endast de begärda kolumnerna.

`$filter`

Värdet för alternativet $filter är ett predikatuttryck (ett uttryck som returnerar ett booleskt resultat) med hjälp av entitetens fält. Endast objekt där uttrycket utvärderas till Sant ingår i svaret. Till exempel:

### 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

Operatorerna som stöds av alternativet $filter är:

Operatör	Typ	Beskrivning	Exempel
`eq`	Jämförelse	Lika	`title eq 'Hyperion'`
`ne`	Jämförelse	Inte lika med	`title ne 'Hyperion'`
`gt`	Jämförelse	Större än	`year gt 1990`
`ge`	Jämförelse	Större än eller lika med	`year ge 1990`
`lt`	Jämförelse	Mindre än	`year lt 1990`
`le`	Jämförelse	Mindre än eller lika med	`year le 1990`
`and`	Logisk	Logiskt och	`year ge 1980 and year lt 1990`
`or`	Logisk	Logiskt eller	`year le 1960 or title eq 'Hyperion'`
`not`	Logisk	Logisk negation	`not (year le 1960)`
`( )`	Gruppering	Prioritetsgruppering	`(year ge 1970 or title eq 'Foundation') and pages gt 400`

Not

$filter är ett skiftlägeskänsligt argument.

Den $filter frågeparametern i Azure Data API Builder kan påminna vissa användare om OData, och det beror på att den inspirerades direkt av ODatas filtreringsfunktioner. Syntaxen är nästan identisk, vilket gör det enkelt för utvecklare som redan är bekanta med OData att hämta och använda. Den här likheten var avsiktlig och syftade till att ge ett välbekant och kraftfullt sätt att filtrera data mellan olika API:er.

`$orderby`

Värdet för parametern orderby är en kommaavgränsad lista med uttryck som används för att sortera objekten.

Varje uttryck i parametervärdet orderby kan innehålla suffixet desc för att be om en fallande ordning, avgränsad från uttrycket med ett eller flera blanksteg.

Till exempel:

### 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

Not

$orderBy är ett skiftlägeskänsligt argument.

Frågeparametern $orderby är värdefull för att sortera data direkt på servern, som också enkelt hanteras på klientsidan. Det blir dock användbart när det kombineras med andra frågeparametrar, till exempel $filter och $first. Med parametern kan sidnumrering upprätthålla en stabil och förutsägbar datamängd när du sidnumrerar genom stora samlingar.

`$first` och `$after`

Frågeparametern $first begränsar antalet objekt som returneras i en enda begäran. Till exempel:

GET /api/book?$first=5

Den här begäran returnerar de fem första böckerna. Frågeparametern $first i Azure Data API Builder liknar TOP-satsen i SQL. Båda används för att begränsa antalet poster som returneras från en fråga. Precis som TOP i SQL kan du ange antalet rader som ska hämtas, $first låter dig styra antalet objekt som returneras av API:et. $first är användbart när du vill hämta en liten delmängd data, till exempel de första 10 resultaten, utan att hämta hela datamängden. Den största fördelen är effektiviteten eftersom den minskar mängden data som överförs och bearbetas.

Not

I Azure Data API Builder begränsas antalet rader som returneras som standard av en inställning i konfigurationsfilen. Användare kan åsidosätta den här gränsen med parametern $first för att begära fler rader, men det finns fortfarande ett konfigurerat maximalt antal rader som kan returneras totalt sett. Dessutom finns det en gräns för det totala antalet megabyte som kan returneras i ett enda svar, vilket också kan konfigureras.

Om fler objekt är tillgängliga utöver den angivna gränsen innehåller svaret en nextLink egenskap:

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

nextLink kan användas med frågeparametern $after för att hämta nästa uppsättning objekt:

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

Den här fortsättningsmetoden använder markörbaserad sidnumrering. En unik markör är en referens till ett specifikt objekt i datauppsättningen, som avgör var data ska fortsätta att hämtas i nästa uppsättning. Till skillnad från index-sidnumrering som använder förskjutningar eller index förlitar sig markörbaserad sidnumrering inte på att hoppa över poster. Markörens fortsättning gör den mer tillförlitlig med stora datamängder eller ofta föränderliga data. I stället säkerställer det ett smidigt och konsekvent flöde av datahämtning genom att börja exakt där den sista frågan slutade, baserat på markören som angetts.

Till exempel:

### 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

Skapa ett nytt objekt för den angivna entiteten. Till exempel:

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

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

POST-begäran skapar en ny bok. Alla fält som inte kan vara nullbara måste anges. Om det fullständiga entitetsobjektet, inklusive null-fält, lyckas returneras:

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

STÄLLA

PUT skapar eller ersätter ett objekt i den angivna entiteten. Frågemönstret är:

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

Till exempel:

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

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

Om det finns ett objekt med den angivna primärnyckeln 2001ersätter de angivna data helt objektet. Om det i stället finns ett objekt med den primära nyckeln skapas ett nytt objekt.

I båda fallen är resultatet ungefär så här:

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

LAPP

PATCH skapar eller uppdaterar objektet för den angivna entiteten. Endast de angivna fälten påverkas. Alla fält som inte anges i begärandetexten påverkas inte. Om ett objekt med den angivna primärnyckeln inte finns skapas ett nytt objekt.

Frågemönstret är:

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

Till exempel:

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

{    
  "year": 1991
}

Resultatet är ungefär så här:

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

TA BORT

DELETE tar bort objektet för den angivna entiteten. Frågemönstret är:

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

Till exempel:

DELETE /api/book/id/2001

Om det lyckas är resultatet ett tomt svar med statuskod 204.

Databastransaktioner för REST API-begäranden

För att bearbeta POST-, PUT-, PATCH- och DELETE-API-begäranden; Data API Builder konstruerar och kör databasfrågorna i en transaktion.

I följande tabell visas de isoleringsnivåer som transaktionerna skapas med för varje databastyp.

Databastyp	Isoleringsnivå	Mer information
Azure SQL (eller) SQL Server	Läs bekräftad	Azure SQL
MySQL	Repeterbar läsning	MySQL
PostgreSQL	Läs bekräftad	PostgreSQL

Dela via

Värd-REST-slutpunkter i Data API Builder

Anropa en REST API-metod

HTTP-metoder

Viloväg

Enhet

Format för resultatuppsättning

FÅ

URL-parametrar

Till exempel:

Frågeparametrar

`$select`

`$filter`

`$orderby`

`$first` och `$after`

POST

STÄLLA

LAPP

TA BORT

Databastransaktioner för REST API-begäranden

Feedback

Ytterligare resurser

Dela via

Värd-REST-slutpunkter i Data API Builder

Anropa en REST API-metod

HTTP-metoder

Viloväg

Enhet

Format för resultatuppsättning

FÅ

URL-parametrar

Till exempel:

Frågeparametrar

$select

$filter

$orderby

$first och $after

POST

STÄLLA

LAPP

TA BORT

Databastransaktioner för REST API-begäranden

Relaterat innehåll

Feedback

Ytterligare resurser

`$select`

`$filter`

`$orderby`

`$first` och `$after`