Host-REST-Endpunkte im Daten-API-Generator

Artikel
12/20/2024

Der Daten-API-Generator bietet eine RESTful-Web-API, mit der Sie auf Tabellen, Ansichten und gespeicherte Prozeduren aus einer verbundenen Datenbank zugreifen können. Entitäten stellen ein Datenbankobjekt in der Laufzeitkonfiguration des Daten-API-Generators dar. Eine Entität muss in der Laufzeitkonfiguration festgelegt werden, damit sie auf dem REST-API-Endpunkt verfügbar ist.

Aufrufen einer REST-API-Methode

Um aus einer Ressource (oder Entität) zu lesen oder in eine Entität zu schreiben, erstellen Sie eine Anforderung mit dem folgenden Muster:

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

Anmerkung

Bei allen Komponenten des URL-Pfads, einschließlich Entitäten und Abfrageparametern, wird die Groß-/Kleinschreibung beachtet.

Zu den Komponenten einer Anforderung gehören:

	Beschreibung
`{HTTP method}`	Die HTTP-Methode, die für die Anforderung an den Daten-API-Generator verwendet wird
`{base_url}`	Die Domäne (oder localhost-Server und -Port), die eine Instanz des Daten-API-Generators hosten
`{rest-path}`	Der Basispfad des REST-API-Endpunktsatzes in der Laufzeitkonfiguration
`{entity}`	Der Name des Datenbankobjekts gemäß definition in der Laufzeitkonfiguration

Hier ist eine Beispiel-GET-Anforderung für die book Entität, die sich unter der REST-Endpunktbasis befindet, /api in einer lokalen Entwicklungsumgebung localhost:

GET https:/localhost:5001/api/Book

HTTP-Methoden

Der Daten-API-Generator verwendet die HTTP-Methode für Ihre Anforderung, um zu bestimmen, welche Aktion für die angegebene Entität der Anforderung ausgeführt werden soll. Die folgenden HTTP-Verben sind verfügbar, abhängig von den Berechtigungen, die für eine bestimmte Entität festgelegt sind.

Methode	Beschreibung
`GET`	Abrufen von Null, mindestens einem Element
`POST`	Erstellen eines neuen Elements
`PATCH`	Aktualisieren Sie ein Element mit neuen Werten, falls vorhanden. Andernfalls erstellen Sie ein neues Element
`PUT`	Ersetzen Sie ein Element durch ein neues Element, falls vorhanden. Andernfalls erstellen Sie ein neues Element
`DELETE`	Löschen eines Elements

Restpfad

Der Restpfad bestimmt den Speicherort der REST-API des Daten-API-Generators. Der Pfad ist in der Laufzeitkonfiguration konfigurierbar und standardmäßig auf /apifestgelegt. Weitere Informationen finden Sie unter REST-Pfadkonfiguration.

Entität

Entity ist die Terminologie, die verwendet wird, um auf eine REST-API-Ressource im Data-API-Builder zu verweisen. Standardmäßig ist der URL-Routenwert für eine Entität der in der Laufzeitkonfiguration definierte Entitätsname. Der REST-URL-Pfadwert einer Entität kann innerhalb der REST-Einstellungen der Entität konfiguriert werden. Weitere Informationen finden Sie unter Entitätskonfiguration.

Resultsetformat

Das zurückgegebene Ergebnis ist ein JSON-Objekt mit diesem Format:

{
    "value": []    
}

Die Elemente im Zusammenhang mit der angeforderten Entität sind im value Array verfügbar. Zum Beispiel:

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

Anmerkung

Standardmäßig werden nur die ersten 100 Elemente zurückgegeben.

ERHALTEN

Mit der GET-Methode können Sie ein oder mehrere Elemente der gewünschten Entität abrufen.

URL-Parameter

REST-Endpunkte ermöglichen es Ihnen, ein Element anhand von URL-Parametern anhand seines Primärschlüssels abzurufen. Für Entitäten mit einem einzelnen Primärschlüssel ist das Format einfach:

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

Um ein Buch mit einer ID von 1001abzurufen, verwenden Sie Folgendes:

GET /api/book/id/1001

Bei Entitäten mit zusammengesetzten Primärschlüsseln, bei denen mehrere Spalten verwendet werden, um einen Datensatz eindeutig zu identifizieren, enthält das URL-Format alle Schlüsselspalten in Sequenz:

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

Wenn eine books Entität einen zusammengesetzten Schlüssel aufweist, der aus id1 und id2besteht, würden Sie ein bestimmtes Buch wie folgt abrufen:

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

Zum Beispiel:

So sieht ein Anruf aus:

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

Abfrageparameter

REST-Endpunkte unterstützen die folgenden Abfrageparameter (Groß-/Kleinschreibung beachten), um die zurückgegebenen Elemente zu steuern:

$select: Gibt nur die ausgewählten Spalten zurück.
$filter: filtert die zurückgegebenen Elemente.
$orderby: definiert, wie die zurückgegebenen Daten sortiert werden
$first und $after: Gibt nur die obersten n Elemente zurück.

Abfrageparameter können zusammen verwendet werden.

`$select`

Der Abfrageparameter $select ermöglicht es, die Felder zu spezifizieren, die zurückgegeben werden müssen. Zum Beispiel:

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

Anmerkung

Wenn eines der angeforderten Felder nicht vorhanden ist oder aufgrund von konfigurierten Berechtigungen nicht darauf zugegriffen werden kann, wird eine 400 - Bad Request zurückgegeben.

Der $select Abfrageparameter, auch als "Projektion" bezeichnet, wird verwendet, um die Größe der in einer API-Antwort zurückgegebenen Daten zu steuern. Mit nur benötigten Spalten reduziert $select die Nutzlastgröße, wodurch die Leistung verbessert werden kann, indem die Analysezeit minimiert, die Bandbreitennutzung reduziert und die Datenverarbeitung beschleunigt wird. Diese Optimierung erstreckt sich auf die Datenbank. Dort werden nur die angeforderten Spalten abgerufen.

`$filter`

Der Wert der Option $filter ist ein Prädikatausdruck (ein Ausdruck, der ein boolesches Ergebnis zurückgibt) mithilfe der Felder der Entität. Nur Elemente, bei denen der Ausdruck als "True" ausgewertet wird, werden in der Antwort enthalten. Zum Beispiel:

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

Die von der Option "$filter" unterstützten Operatoren sind:

Operator	Art	Beschreibung	Beispiel
`eq`	Vergleich	Gleich	`title eq 'Hyperion'`
`ne`	Vergleich	Ungleich	`title ne 'Hyperion'`
`gt`	Vergleich	Größer als	`year gt 1990`
`ge`	Vergleich	Größer oder gleich	`year ge 1990`
`lt`	Vergleich	Weniger als	`year lt 1990`
`le`	Vergleich	Kleiner oder gleich	`year le 1990`
`and`	Logisch	Logisch und	`year ge 1980 and year lt 1990`
`or`	Logisch	Logisch oder	`year le 1960 or title eq 'Hyperion'`
`not`	Logisch	Logische Negation	`not (year le 1960)`
`( )`	Gruppierung	Rangfolgegruppierung	`(year ge 1970 or title eq 'Foundation') and pages gt 400`

Anmerkung

$filter ist ein groß- und kleinschreibungssensitives Argument.

Der $filter Abfrageparameter im Azure Data API Builder erinnert möglicherweise einige Benutzer an OData, und das liegt daran, dass er direkt von den Filterfunktionen von OData inspiriert wurde. Die Syntax ist nahezu identisch, sodass Entwickler, die bereits mit OData vertraut sind, die Verwendung erleichtern. Diese Ähnlichkeit war beabsichtigt, um eine vertraute und leistungsstarke Möglichkeit zum Filtern von Daten über verschiedene APIs zu bieten.

`$orderby`

Der Wert des orderby-Parameters ist eine durch Trennzeichen getrennte Liste von Ausdrücken, die zum Sortieren der Elemente verwendet werden.

Jeder Ausdruck im Wert des orderby-Parameters kann, um eine absteigende Reihenfolge anzufordern, das Suffix desc enthalten, mit einem oder mehreren Leerzeichen vom Ausdruck getrennt.

Zum Beispiel:

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

Anmerkung

$orderBy ist ein schreibungsabhängiges Argument.

Der $orderby Abfrageparameter ist nützlich, um Daten direkt auf dem Server zu sortieren, die auch auf clientseitiger Seite problemlos verarbeitet werden können. Es wird jedoch nützlich, wenn es mit anderen Abfrageparametern kombiniert wird, z. B. $filter und $first. Mit dem Parameter kann die Paginierung ein stabiles und vorhersagbares Dataset beibehalten, während Sie durch große Auflistungen paginieren.

`$first` und `$after`

Der $first Abfrageparameter beschränkt die Anzahl der in einer einzelnen Anforderung zurückgegebenen Elemente. Zum Beispiel:

GET /api/book?$first=5

Diese Anforderung gibt die ersten fünf Bücher zurück. Der $first Abfrageparameter im Azure Data API Builder ähnelt der TOP-Klausel in SQL. Beide werden verwendet, um die Anzahl der von einer Abfrage zurückgegebenen Datensätze einzuschränken. Genau wie TOP in SQL es Ihnen ermöglicht, die Anzahl der abzurufenden Zeilen anzugeben, können Sie mit $first die Anzahl der von der API zurückgegebenen Elemente steuern. $first ist nützlich, wenn Sie eine kleine Teilmenge von Daten abrufen möchten, z. B. die ersten 10 Ergebnisse, ohne das gesamte Dataset abzurufen. Der Hauptvorteil ist die Effizienz, da sie die Menge der übertragenen und verarbeiteten Daten reduziert.

Anmerkung

Im Azure Data API Builder ist die Anzahl der standardmäßig zurückgegebenen Zeilen durch eine Einstellung in der Konfigurationsdatei beschränkt. Benutzer können diesen Grenzwert mithilfe des $first Parameters außer Kraft setzen, um weitere Zeilen anzufordern, aber es gibt weiterhin eine konfigurierte maximale Anzahl von Zeilen, die insgesamt zurückgegeben werden können. Darüber hinaus gibt es ein Limit für die Gesamten Megabytes, die in einer einzigen Antwort zurückgegeben werden können, die auch konfigurierbar ist.

Wenn mehr Elemente über den angegebenen Grenzwert hinaus verfügbar sind, enthält die Antwort eine nextLink Eigenschaft:

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

Die nextLink kann mit dem $after-Abfrageparameter verwendet werden, um die nächste Gruppe von Elementen abzurufen.

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

Bei diesem Fortsetzungsansatz wird die cursorbasierte Paginierung verwendet. Ein eindeutiger Cursor ist ein Verweis auf ein bestimmtes Element im Dataset, das bestimmt, wo die Daten im nächsten Satz weiterhin abgerufen werden sollen. Im Gegensatz zur Index-Paginierung, die Offsets oder Indizes verwendet, basiert die Cursor-basierte Paginierung nicht auf dem Überspringen von Datensätzen. Die Cursorfortsetzung macht sie mit großen Datasets oder häufig geänderten Daten zuverlässiger. Stattdessen wird ein reibungsloser und konsistenter Datenabruf sichergestellt, indem die letzte Abfrage basierend auf dem bereitgestellten Cursor genau dort gestartet wird, wo die letzte Abfrage unterbrochen wurde.

Zum Beispiel:

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

BEREITSTELLEN

Erstellen Sie ein neues Element für die angegebene Entität. Zum Beispiel:

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

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

Die POST-Anforderung erstellt ein neues Buch. Alle Felder, die nicht nullfähig sein können, müssen angegeben werden. Bei erfolgreicher Ausführung des vollständigen Entitätsobjekts, einschließlich aller NULL-Felder, wird Folgendes zurückgegeben:

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

STELLEN

PUT erstellt oder ersetzt ein Element der angegebenen Entität. Das Abfragemuster lautet:

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

Zum Beispiel:

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

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

Wenn ein Element mit dem angegebenen Primärschlüssel 2001vorhanden ist, werden die bereitgestellten Daten dieses Element vollständig ersetzt. Wenn stattdessen ein Element mit diesem Primärschlüssel nicht vorhanden ist, wird ein neues Element erstellt.

In beiden Fällen ist das Ergebnis etwa wie folgt:

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

Der `If-Match: *` HTTP-Anforderungsheader

Der HTTP-Header If-Match: * stellt sicher, dass ein Aktualisierungsvorgang ausgeführt wird,nur ausgeführt wird, wenn die Ressourcevorhanden ist. Wenn die Ressource nicht vorhanden ist, schlägt der Vorgang mit HTTP-Statuscode fehl: 404 Not Found. Wenn der If-Match-Header weggelassen wird, besteht das Standardverhalten darin, einen Upsertauszuführen, der die Ressource erstellt, wenn sie noch nicht vorhanden ist.

Beispiel:

PUT /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json

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

Anmerkung

Wenn Sie einen anderen Wert als * im If-Match-Header angeben, gibt der Daten-API-Generator einen 400 Bad Request Fehler zurück, da der ETag-basierte Abgleich nicht unterstützt wird.

FLICKEN

PATCH erstellt oder aktualisiert das Element der angegebenen Entität. Nur die angegebenen Felder sind betroffen. Alle im Anforderungstext nicht angegebenen Felder sind nicht betroffen. Wenn ein Element mit dem angegebenen Primärschlüssel nicht vorhanden ist, wird ein neues Element erstellt.

Das Abfragemuster lautet:

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

Zum Beispiel:

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

{    
  "year": 1991
}

Das Ergebnis sieht ungefähr so aus:

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

Der `If-Match: *` HTTP-Anforderungsheader

Beispiel:

PATCH /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json

{
    "year": 1991
}

Anmerkung

Wenn Sie einen anderen Wert als * im If-Match-Header angeben, gibt der Daten-API-Generator einen 400 Bad Request Fehler zurück, da der ETag-basierte Abgleich nicht unterstützt wird.

LÖSCHEN

DELETE löscht das Element der angegebenen Entität. Das Abfragemuster lautet:

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

Zum Beispiel:

DELETE /api/book/id/2001

Bei erfolgreicher Ausführung ist das Ergebnis eine leere Antwort mit Statuscode 204.

Datenbanktransaktionen für REST-API-Anforderungen

Um POST-, PUT-, PATCH- und DELETE-API-Anforderungen zu verarbeiten; Der Daten-API-Generator erstellt und führt die Datenbankabfragen in einer Transaktion aus.

In der folgenden Tabelle sind die Isolationsebenen aufgeführt, mit denen die Transaktionen für jeden Datenbanktyp erstellt werden.

Datenbanktyp	Isolationsstufe	Weitere Informationen
Azure SQL (oder) SQL Server	Zugesichert lesen	Azure SQL
MySQL	Wiederholbares Lesen	MySQL
PostgreSQL	Zugesichert lesen	PostgreSQL

Freigeben über

Host-REST-Endpunkte im Daten-API-Generator

Aufrufen einer REST-API-Methode

HTTP-Methoden

Restpfad

Entität

Resultsetformat

ERHALTEN

URL-Parameter

Zum Beispiel:

Abfrageparameter

`$select`

`$filter`

`$orderby`

`$first` und `$after`

BEREITSTELLEN

STELLEN

Der `If-Match: *` HTTP-Anforderungsheader

FLICKEN

Der `If-Match: *` HTTP-Anforderungsheader

LÖSCHEN

Datenbanktransaktionen für REST-API-Anforderungen

Feedback

Zusätzliche Ressourcen

Freigeben über

Host-REST-Endpunkte im Daten-API-Generator

Aufrufen einer REST-API-Methode

HTTP-Methoden

Restpfad

Entität

Resultsetformat

ERHALTEN

URL-Parameter

Zum Beispiel:

Abfrageparameter

$select

$filter

$orderby

$first und $after

BEREITSTELLEN

STELLEN

Der If-Match: * HTTP-Anforderungsheader

FLICKEN

Der If-Match: * HTTP-Anforderungsheader

LÖSCHEN

Datenbanktransaktionen für REST-API-Anforderungen

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen

`$select`

`$filter`

`$orderby`

`$first` und `$after`

Der `If-Match: *` HTTP-Anforderungsheader

Der `If-Match: *` HTTP-Anforderungsheader