REST-eindpunten hosten in Data API Builder

Artikel
08/14/2024

Data API Builder biedt een RESTful-web-API waarmee u toegang hebt tot tabellen, weergaven en opgeslagen procedures vanuit een verbonden database. Entiteiten vertegenwoordigen een databaseobject in de runtimeconfiguratie van Data API Builder. Een entiteit moet worden ingesteld in de runtimeconfiguratie om deze beschikbaar te kunnen maken op het REST API-eindpunt.

Een REST API-methode aanroepen

Als u wilt lezen van of schrijven naar een resource (of entiteit), maakt u een aanvraag met behulp van het volgende patroon:

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

Notitie

Alle onderdelen van het URL-pad, inclusief entiteiten en queryparameters, zijn hoofdlettergevoelig.

De onderdelen van een aanvraag zijn:

	Beschrijving
`{HTTP method}`	De HTTP-methode die wordt gebruikt voor de aanvraag voor Data API Builder
`{base_url}`	Het domein (of de localhost-server en -poort) die als host fungeert voor een exemplaar van Data API Builder
`{rest-path}`	Het basispad van het REST API-eindpunt dat is ingesteld in de runtimeconfiguratie
`{entity}`	De naam van het databaseobject zoals gedefinieerd in de runtimeconfiguratie

Hier volgt een voorbeeld van een GET-aanvraag voor de book-entiteit die zich onder de REST-eindpuntbasis bevindt /api in een lokale ontwikkelomgeving localhost:

GET https:/localhost:5001/api/Book

HTTP-methoden

Data API Builder maakt gebruik van de HTTP-methode in uw aanvraag om te bepalen welke actie moet worden ondernomen voor de toegewezen aanvraagentiteit. De volgende HTTP-woorden zijn beschikbaar, afhankelijk van de machtigingen die zijn ingesteld voor een bepaalde entiteit.

Methode	Beschrijving
`GET`	Nul ophalen, een of meer items
`POST`	Een nieuw item maken
`PATCH`	Werk een item bij met nieuwe waarden als deze bestaat. Anders maakt u een nieuw item
`PUT`	Vervang een item door een nieuw item als deze bestaat. Anders maakt u een nieuw item
`DELETE`	Een item verwijderen

Rest-pad

Het restpad wijst de locatie van de REST API-API van Data API builder aan. Het pad kan worden geconfigureerd in de runtimeconfiguratie en wordt standaard ingesteld op /api-. Zie CONFIGURATIE van REST-padvoor meer informatie.

Entiteit

Entity is de terminologie die wordt gebruikt om te verwijzen naar een REST API-resource in Data API Builder. De URL-routewaarde voor een entiteit is standaard de naam van de entiteit die is gedefinieerd in de runtimeconfiguratie. De WAARDE van het REST URL-pad van een entiteit kan worden geconfigureerd binnen de REST-instellingen van de entiteit. Zie entiteitsconfiguratievoor meer informatie.

Indeling van resultatenset

Het geretourneerde resultaat is een JSON-object met deze indeling:

{
    "value": []    
}

De items met betrekking tot de aangevraagde entiteit zijn beschikbaar in de value matrix. Bijvoorbeeld:

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

Notitie

Alleen de eerste 100 items worden standaard geretourneerd.

TOEVOEGEN

Met behulp van de GET-methode kunt u een of meer items van de gewenste entiteit ophalen.

URL-parameters

MET REST-eindpunten kunt u een item ophalen op basis van de primaire sleutel met behulp van URL-parameters. Voor entiteiten met één primaire sleutel is de indeling eenvoudig:

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

Als u een boek met een id van 1001wilt ophalen, gebruikt u:

GET /api/book/id/1001

Voor entiteiten met samengestelde primaire sleutels, waarbij meer dan één kolom wordt gebruikt om een record uniek te identificeren, bevat de URL-indeling alle sleutelkolommen in volgorde:

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

Als een books-entiteit een samengestelde sleutel heeft die bestaat uit id1 en id2, zou u een specifiek boek als volgt ophalen:

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

Bijvoorbeeld:

U ziet er als volgt uit:

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

Queryparameters

REST-eindpunten ondersteunen de volgende queryparameters (hoofdlettergevoelig) om de geretourneerde items te beheren:

$select: retourneert alleen de geselecteerde kolommen
$filter: filtert de geretourneerde items
$orderby: definieert hoe de geretourneerde gegevens worden gesorteerd
$first en $after: retourneert alleen de bovenste n items

Queryparameters kunnen samen worden gebruikt.

`$select`

Met de queryparameter $select kunt u opgeven welke velden moeten worden geretourneerd. Bijvoorbeeld:

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

Notitie

Als een van de aangevraagde velden niet bestaat of niet toegankelijk is vanwege geconfigureerde machtigingen, wordt een 400 - Bad Request geretourneerd.

De $select queryparameter, ook wel projectie genoemd, wordt gebruikt om de grootte te bepalen van de gegevens die worden geretourneerd in een API-antwoord. Met alleen benodigde kolommen vermindert $select de nettoladinggrootte, waardoor de prestaties kunnen worden verbeterd door de parseertijd te minimaliseren, het bandbreedtegebruik te verminderen en gegevensverwerking te versnellen. Deze optimalisatie breidt zich uit naar de database. Daar worden alleen de aangevraagde kolommen opgehaald.

`$filter`

De waarde van de optie $filter is een predicaatexpressie (een expressie die een booleaans resultaat retourneert) met behulp van de velden van de entiteit. Alleen items waarin de expressie waar wordt geëvalueerd, worden opgenomen in het antwoord. Bijvoorbeeld:

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

De operators die worden ondersteund door de optie $filter zijn:

Bediener	Type	Beschrijving	Voorbeeld
`eq`	Vergelijking	Gelijk	`title eq 'Hyperion'`
`ne`	Vergelijking	Niet gelijk aan	`title ne 'Hyperion'`
`gt`	Vergelijking	Groter dan	`year gt 1990`
`ge`	Vergelijking	Groter dan of gelijk aan	`year ge 1990`
`lt`	Vergelijking	Kleiner dan	`year lt 1990`
`le`	Vergelijking	Kleiner dan of gelijk aan	`year le 1990`
`and`	Logisch	Logisch en	`year ge 1980 and year lt 1990`
`or`	Logisch	Logisch of	`year le 1960 or title eq 'Hyperion'`
`not`	Logisch	Logische negatie	`not (year le 1960)`
`( )`	Groepering	Prioriteitsgroepering	`(year ge 1970 or title eq 'Foundation') and pages gt 400`

Notitie

$filter is een hoofdlettergevoelig argument.

De $filter queryparameter in Azure Data API Builder herinnert sommige gebruikers mogelijk aan OData en dat komt doordat deze rechtstreeks is geïnspireerd op de filtermogelijkheden van OData. De syntaxis is bijna identiek, waardoor ontwikkelaars die al bekend zijn met OData, gemakkelijk kunnen worden opgehaald en gebruikt. Deze overeenkomst was opzettelijk, gericht op het bieden van een vertrouwde en krachtige manier om gegevens te filteren op verschillende API's.

`$orderby`

De waarde van de parameter orderby is een door komma's gescheiden lijst met expressies die worden gebruikt om de items te sorteren.

Elke expressie in de parameterwaarde orderby kan het achtervoegsel bevatten desc om een aflopende volgorde te vragen, gescheiden van de expressie door een of meer spaties.

Bijvoorbeeld:

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

Notitie

$orderBy is een hoofdlettergevoelig argument.

De $orderby queryparameter is waardevol voor het rechtstreeks sorteren van gegevens op de server, eenvoudig te verwerken aan de clientzijde. Het wordt echter handig wanneer deze wordt gecombineerd met andere queryparameters, zoals $filter en $first. Met de parameter kan paginering een stabiele en voorspelbare gegevensset behouden terwijl u door grote verzamelingen bladert.

`$first` en `$after`

De $first queryparameter beperkt het aantal items dat in één aanvraag wordt geretourneerd. Bijvoorbeeld:

GET /api/book?$first=5

Deze aanvraag retourneert de eerste vijf boeken. De $first queryparameter in Azure Data API Builder is vergelijkbaar met de TOP-component in SQL. Beide worden gebruikt om het aantal records te beperken dat wordt geretourneerd door een query. Net zoals TOP in SQL kunt u de hoeveelheid rijen opgeven die moeten worden opgehaald, $first kunt u het aantal items bepalen dat door de API wordt geretourneerd. $first is handig als u een kleine subset met gegevens, zoals de eerste 10 resultaten, wilt ophalen zonder de hele gegevensset op te halen. Het belangrijkste voordeel is efficiëntie, omdat het de hoeveelheid verzonden en verwerkte gegevens vermindert.

Notitie

In azure Data API Builder wordt het aantal rijen dat standaard wordt geretourneerd, beperkt door een instelling in het configuratiebestand. Gebruikers kunnen deze limiet overschrijven met behulp van de parameter $first om meer rijen aan te vragen, maar er is nog steeds een geconfigureerd maximum aantal rijen dat over het algemeen kan worden geretourneerd. Daarnaast is er een limiet voor het totale aantal megabytes dat kan worden geretourneerd in één antwoord, dat ook kan worden geconfigureerd.

Als er meer items beschikbaar zijn dan de opgegeven limiet, bevat het antwoord een nextLink eigenschap:

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

De nextLink kan worden gebruikt met de $after queryparameter om de volgende set items op te halen:

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

Deze vervolgbenadering maakt gebruik van op cursor gebaseerde paginering. Een unieke cursor is een verwijzing naar een specifiek item in de gegevensset, waarbij wordt bepaald waar gegevens in de volgende set moeten worden opgehaald. In tegenstelling tot indexpaginering die offsets of indexen gebruikt, is paginering op basis van cursor niet afhankelijk van het overslaan van records. Cursorvervolging maakt het betrouwbaarder met grote gegevenssets of vaak veranderende gegevens. In plaats daarvan zorgt het voor een soepele en consistente stroom van het ophalen van gegevens door precies te beginnen waar de laatste query is gebleven, op basis van de opgegeven cursor.

Bijvoorbeeld:

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

VERZENDEN

Maak een nieuw item voor de opgegeven entiteit. Bijvoorbeeld:

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

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

Met de POST-aanvraag wordt een nieuw boek gemaakt. Alle velden die niet nullable kunnen zijn, moeten worden opgegeven. Als het volledige entiteitsobject, inclusief eventuele null-velden, is geslaagd, wordt het volgende geretourneerd:

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

ZETTEN

PUT maakt of vervangt een item van de opgegeven entiteit. Het querypatroon is:

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

Bijvoorbeeld:

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

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

Als er een item is met de opgegeven primaire sleutel 2001, worden de opgegeven gegevens volledig vervangen dat item. Als er geen item met die primaire sleutel bestaat, wordt er een nieuw item gemaakt.

In beide gevallen ziet het resultaat er ongeveer als volgt uit:

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

LAP

PATCH maakt of werkt het item van de opgegeven entiteit bij. Alleen de opgegeven velden worden beïnvloed. Alle velden die niet zijn opgegeven in de aanvraagbody, worden niet beïnvloed. Als er geen item met de opgegeven primaire sleutel bestaat, wordt er een nieuw item gemaakt.

Het querypatroon is:

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

Bijvoorbeeld:

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

{    
  "year": 1991
}

Het resultaat ziet er ongeveer als volgt uit:

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

VERWIJDEREN

Met DELETE wordt het item van de opgegeven entiteit verwijderd. Het querypatroon is:

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

Bijvoorbeeld:

DELETE /api/book/id/2001

Als dit lukt, is het resultaat een leeg antwoord met statuscode 204.

Databasetransacties voor REST API-aanvragen

POST-, PUT-, PATCH- en DELETE-API-aanvragen verwerken; Data API Builder bouwt en voert de databasequery's uit in een transactie.

De volgende tabel bevat de isolatieniveaus waarmee de transacties worden gemaakt voor elk databasetype.

Databasetype	Isolatieniveau	Meer informatie
Azure SQL (of) SQL Server	Vastgelegd lezen	Azure SQL-
MySQL	Herhaalbare leesbewerking	MySQL-
PostgreSQL	Vastgelegd lezen	PostgreSQL-

Delen via

REST-eindpunten hosten in Data API Builder

Een REST API-methode aanroepen

HTTP-methoden

Rest-pad

Entiteit

Indeling van resultatenset

TOEVOEGEN

URL-parameters

Bijvoorbeeld:

Queryparameters

`$select`

`$filter`

`$orderby`

`$first` en `$after`

VERZENDEN

ZETTEN

LAP

VERWIJDEREN

Databasetransacties voor REST API-aanvragen

Feedback

Aanvullende resources

Delen via

REST-eindpunten hosten in Data API Builder

Een REST API-methode aanroepen

HTTP-methoden

Rest-pad

Entiteit

Indeling van resultatenset

TOEVOEGEN

URL-parameters

Bijvoorbeeld:

Queryparameters

$select

$filter

$orderby

$first en $after

VERZENDEN

ZETTEN

LAP

VERWIJDEREN

Databasetransacties voor REST API-aanvragen

Verwante inhoud

Feedback

Aanvullende resources

`$select`

`$filter`

`$orderby`

`$first` en `$after`