Héberger des points de terminaison REST dans le générateur d’API de données

Article
12/18/2024

Le générateur d’API de données fournit une API web RESTful qui vous permet d’accéder aux tables, vues et procédures stockées à partir d’une base de données connectée. Les entités représentent un objet de base de données dans la configuration du runtime du générateur d’API de données. Une entité doit être définie dans la configuration du runtime pour qu’elle soit disponible sur le point de terminaison de l’API REST.

Appeler une méthode d’API REST

Pour lire ou écrire dans une ressource (ou une entité), vous créez une requête à l’aide du modèle suivant :

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

Note

Tous les composants du chemin d’URL, y compris les entités et les paramètres de requête, respectent la casse.

Les composants d’une demande sont les suivants :

	Description
`{HTTP method}`	Méthode HTTP utilisée sur la demande adressée au générateur d’API de données
`{base_url}`	Domaine (ou serveur et port localhost) qui héberge une instance du générateur d’API de données
`{rest-path}`	Chemin d’accès de base du point de terminaison de l’API REST défini dans la configuration du runtime
`{entity}`	Nom de l’objet de base de données tel que défini dans la configuration du runtime

Voici un exemple de requête GET sur l’entité book résidant sous la base de point de terminaison REST /api dans un environnement de développement local localhost:

GET https:/localhost:5001/api/Book

Méthodes HTTP

Le générateur d’API de données utilise la méthode HTTP sur votre requête pour déterminer quelle action effectuer sur l’entité désignée de la demande. Les verbes HTTP suivants sont disponibles, en fonction des autorisations définies pour une entité particulière.

Méthode	Description
`GET`	Obtenir zéro, un ou plusieurs éléments
`POST`	Créer un élément
`PATCH`	Mettez à jour un élément avec de nouvelles valeurs s’il en existe un. Sinon, créez un élément
`PUT`	Remplacez un élément par un nouvel élément s’il en existe un. Sinon, créez un élément
`DELETE`	Supprimer un élément

Chemin d’accès rest

Le chemin d’accès rest désigne l’emplacement de l’API REST du générateur d’API de données. Le chemin d’accès est configurable dans la configuration du runtime et est défini par défaut sur /api. Pour plus d’informations, consultez configuration du chemin REST.

Entité

Entity est la terminologie utilisée pour référencer une ressource d’API REST dans le générateur d’API de données. Par défaut, la valeur d’itinéraire d’URL d’une entité est le nom d’entité défini dans la configuration du runtime. La valeur du chemin d’accès d’URL REST d’une entité est configurable dans les paramètres REST de l’entité. Pour plus d’informations, consultez configuration d’entité.

Format du jeu de résultats

Le résultat retourné est un objet JSON au format suivant :

{
    "value": []    
}

Les éléments liés à l’entité demandée sont disponibles dans le tableau value. Par exemple:

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

Note

Seuls les 100 premiers éléments sont retournés par défaut.

AVOIR

À l’aide de la méthode GET, vous pouvez récupérer un ou plusieurs éléments de l’entité souhaitée.

Paramètres d’URL

Les points de terminaison REST vous permettent de récupérer un élément par sa clé primaire à l’aide de paramètres d’URL. Pour les entités avec une seule clé primaire, le format est simple :

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

Pour récupérer un livre avec un ID de 1001, vous devez utiliser :

GET /api/book/id/1001

Pour les entités avec des clés primaires composées, où plusieurs colonnes sont utilisées pour identifier un enregistrement de manière unique, le format d’URL inclut toutes les colonnes clés dans la séquence :

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

Si une entité books a une clé composée de id1 et de id2, vous pouvez récupérer un livre spécifique comme suit :

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

Par exemple:

Voici comment un appel ressemblerait :

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

Paramètres de requête

Les points de terminaison REST prennent en charge les paramètres de requête suivants (respectant la casse) pour contrôler les éléments retournés :

$select: retourne uniquement les colonnes sélectionnées
$filter: filtre les éléments retournés
$orderby: définit la façon dont les données retournées sont triées
$first et $after: retourne uniquement les éléments n principaux

Les paramètres de requête peuvent être utilisés ensemble.

`$select`

Le paramètre de requête $select autorise de spécifier les champs qui doivent être retournés. Par exemple:

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

Note

Si l’un des champs demandés n’existe pas ou n’est pas accessible en raison d’autorisations configurées, une 400 - Bad Request est retournée.

Le paramètre de requête $select, également appelé « projection », est utilisé pour contrôler la taille des données retournées dans une réponse d’API. Avec uniquement les colonnes nécessaires, $select réduit la taille de la charge utile, ce qui peut améliorer les performances en réduisant le temps d’analyse, en réduisant l’utilisation de la bande passante et en accélérant le traitement des données. Cette optimisation s’étend à la base de données. Là, seules les colonnes demandées sont récupérées.

`$filter`

La valeur de l’option $filter est une expression de prédicat (expression qui retourne un résultat booléen) à l’aide des champs de l’entité. Seuls les éléments dans lesquels l’expression prend la valeur True sont inclus dans la réponse. Par exemple:

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

Les opérateurs pris en charge par l’option $filter sont les suivants :

Opérateur	Type	Description	Exemple
`eq`	Comparaison	Égal	`title eq 'Hyperion'`
`ne`	Comparaison	Non égal	`title ne 'Hyperion'`
`gt`	Comparaison	Plus grand que	`year gt 1990`
`ge`	Comparaison	Supérieur ou égal à	`year ge 1990`
`lt`	Comparaison	Moins de	`year lt 1990`
`le`	Comparaison	Inférieur ou égal à	`year le 1990`
`and`	Logique	Logique et	`year ge 1980 and year lt 1990`
`or`	Logique	Logique ou	`year le 1960 or title eq 'Hyperion'`
`not`	Logique	Négation logique	`not (year le 1960)`
`( )`	Groupement	Regroupement de précédences	`(year ge 1970 or title eq 'Foundation') and pages gt 400`

Note

$filter est un argument sensible à la casse.

Le paramètre de requête $filter dans Azure Data API Builder peut rappeler à certains utilisateurs d’OData, et c’est parce qu’il a été directement inspiré par les fonctionnalités de filtrage d’OData. La syntaxe est presque identique, ce qui facilite la prise et l’utilisation d’OData pour les développeurs déjà familiarisés avec OData. Cette similarité a été intentionnelle, visant à fournir un moyen familier et puissant de filtrer les données entre différentes API.

`$orderby`

La valeur du paramètre orderby est une liste séparée par des virgules d’expressions utilisées pour trier les éléments.

Chaque expression de la valeur du paramètre orderby peut inclure le suffixe desc demander un ordre décroissant, séparé de l’expression par un ou plusieurs espaces.

Par exemple:

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

Note

$orderBy est un argument sensible à la casse.

Le paramètre de requête $orderby est utile pour trier les données directement sur le serveur et est également facilement géré côté client. Toutefois, il devient utile lorsqu’il est combiné à d’autres paramètres de requête, tels que $filter et $first. Le paramètre permet à la pagination de conserver un jeu de données stable et prévisible lorsque vous paginez dans des collections volumineuses.

`$first` et `$after`

Le paramètre de requête $first limite le nombre d’éléments retournés dans une seule requête. Par exemple:

GET /api/book?$first=5

Cette demande retourne les cinq premiers livres. Le paramètre de requête $first dans azure Data API Builder est similaire à la clause TOP dans SQL. Les deux sont utilisés pour limiter le nombre d’enregistrements retournés à partir d’une requête. Tout comme TOP dans SQL vous permet de spécifier la quantité de lignes à récupérer, $first vous permet de contrôler le nombre d’éléments retournés par l’API. $first est utile lorsque vous souhaitez extraire un petit sous-ensemble de données, tel que les 10 premiers résultats, sans récupérer l’ensemble du jeu de données. L’avantage principal est l’efficacité, car elle réduit la quantité de données transmises et traitées.

Note

Dans le générateur d’API Azure Data, le nombre de lignes retournées par défaut est limité par un paramètre dans le fichier de configuration. Les utilisateurs peuvent remplacer cette limite à l’aide du paramètre $first pour demander plus de lignes, mais il existe toujours un nombre maximal configuré de lignes pouvant être retournées dans l’ensemble. En outre, il existe une limite sur le nombre total de mégaoctets qui peuvent être retournés dans une seule réponse, qui est également configurable.

Si d’autres éléments sont disponibles au-delà de la limite spécifiée, la réponse inclut une propriété nextLink :

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

Le nextLink peut être utilisé avec le paramètre de requête $after pour récupérer le jeu d’éléments suivant :

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

Cette approche de continuation utilise la pagination basée sur le curseur. Un curseur unique est une référence à un élément spécifique dans le jeu de données, déterminant où continuer à récupérer des données dans le jeu suivant. Contrairement à la pagination d’index qui utilise des décalages ou des index, la pagination basée sur le curseur ne repose pas sur l’ignorer des enregistrements. La continuation du curseur rend plus fiable avec des jeux de données volumineux ou des données fréquemment modifiées. Au lieu de cela, il garantit un flux fluide et cohérent de récupération de données en commençant exactement où la dernière requête s’est arrêtée, en fonction du curseur fourni.

Par exemple:

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

PUBLIER

Créez un élément pour l’entité spécifiée. Par exemple:

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

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

La requête POST crée un livre. Tous les champs qui ne peuvent pas être nullables doivent être fournis. En cas de réussite de l’objet d’entité complet, y compris les champs Null, est retourné :

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

METTRE

PUT crée ou remplace un élément de l’entité spécifiée. Le modèle de requête est :

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

Par exemple:

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

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

S’il existe un élément avec la clé primaire spécifiée 2001, les données fournies remplacent complètement cet élément. Si, au lieu de cela, un élément avec cette clé primaire n’existe pas, un nouvel élément est créé.

Dans les deux cas, le résultat est semblable à :

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

En-tête de requête HTTP `If-Match: *`

L’en-tête HTTP garantit qu’une opération de mise à jour est effectuée uniquement si la ressource existe. Si la ressource n’existe pas, l’opération échoue avec le code d’état HTTP : 404 Not Found. Si l’en-tête If-Match est omis, le comportement par défaut consiste à effectuer un upsert, ce qui crée la ressource s’il n’existe pas déjà.

Exemple :

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

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

Note

Si vous spécifiez une valeur autre que * dans l’en-tête If-Match, le générateur d’API de données retourne une erreur 400 Bad Request, car la correspondance basée sur ETag n’est pas prise en charge.

RAPIÉCER

PATCH crée ou met à jour l’élément de l’entité spécifiée. Seuls les champs spécifiés sont affectés. Tous les champs non spécifiés dans le corps de la requête ne sont pas affectés. Si aucun élément avec la clé primaire spécifiée n’existe, un nouvel élément est créé.

Le modèle de requête est :

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

Par exemple:

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

{    
  "year": 1991
}

Le résultat est similaire à :

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

En-tête de requête HTTP `If-Match: *`

L’en-tête HTTP If-Match: * garantit qu’une opération de mise à jour est effectuée uniquement si la ressource existe. Si la ressource n’existe pas, l’opération échoue avec le code d’état HTTP : 404 Not Found. Si l’en-tête If-Match est omis, le comportement par défaut consiste à effectuer un upsert, ce qui crée la ressource s’il n’existe pas déjà.

Exemple :

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

{
    "year": 1991
}

Note

SUPPRIMER

DELETE supprime l’élément de l’entité spécifiée. Le modèle de requête est :

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

Par exemple:

DELETE /api/book/id/2001

Si elle réussit, le résultat est une réponse vide avec le code d’état 204.

Transactions de base de données pour les demandes d’API REST

Pour traiter les demandes d’API POST, PUT, PATCH et DELETE ; Le générateur d’API de données construit et exécute les requêtes de base de données dans une transaction.

Le tableau suivant répertorie les niveaux d’isolation avec lesquels les transactions sont créées pour chaque type de base de données.

Type de base de données	Niveau d’isolation	Plus d’informations
Azure SQL (ou) SQL Server	Lecture validée	Azure SQL
MySQL	Lecture reproductible	MySQL
PostgreSQL	Lecture validée	PostgreSQL

OpenAPI
Référence de configuration REST

Partager via

Héberger des points de terminaison REST dans le générateur d’API de données

Appeler une méthode d’API REST

Méthodes HTTP

Chemin d’accès rest

Entité

Format du jeu de résultats

AVOIR

Paramètres d’URL

Par exemple:

Paramètres de requête

`$select`

`$filter`

`$orderby`

`$first` et `$after`

PUBLIER

METTRE

En-tête de requête HTTP `If-Match: *`

RAPIÉCER

En-tête de requête HTTP `If-Match: *`

SUPPRIMER

Transactions de base de données pour les demandes d’API REST

Commentaires

Ressources supplémentaires

Partager via

Héberger des points de terminaison REST dans le générateur d’API de données

Appeler une méthode d’API REST

Méthodes HTTP

Chemin d’accès rest

Entité

Format du jeu de résultats

AVOIR

Paramètres d’URL

Par exemple:

Paramètres de requête

$select

$filter

$orderby

$first et $after

PUBLIER

METTRE

En-tête de requête HTTP If-Match: *

RAPIÉCER

En-tête de requête HTTP If-Match: *

SUPPRIMER

Transactions de base de données pour les demandes d’API REST

Contenu connexe

Commentaires

Ressources supplémentaires

`$select`

`$filter`

`$orderby`

`$first` et `$after`

En-tête de requête HTTP `If-Match: *`

En-tête de requête HTTP `If-Match: *`