Host REST endpoints in Data API Builder (Host REST endpoints in Data API Builder)
Il generatore di API dati fornisce un'API Web RESTful che consente di accedere a tabelle, viste e stored procedure da un database connesso. Le entità rappresentano un oggetto di database nella configurazione di runtime del generatore di API dati. Per renderla disponibile nell'endpoint dell'API REST, è necessario impostare un'entità nella configurazione di runtime.
Chiamare un metodo API REST
Per leggere o scrivere in una risorsa (o un'entità), creare una richiesta usando il modello seguente:
{HTTP method} https://{base_url}/{rest-path}/{entity}
Nota
Tutti i componenti del percorso URL, incluse le entità e i parametri di query, fanno distinzione tra maiuscole e minuscole.
I componenti di una richiesta includono:
Descrizione | |
---|---|
{HTTP method} |
Metodo HTTP usato nella richiesta a Generatore API dati |
{base_url} |
Dominio (o server localhost e porta) che ospita un'istanza di Generatore API dati |
{rest-path} |
Percorso di base dell'endpoint DELL'API REST impostato nella configurazione di runtime |
{entity} |
Nome dell'oggetto di database come definito nella configurazione di runtime |
Di seguito è riportato un esempio di richiesta GET nell'entità book
che si trova nella base dell'endpoint REST /api
in un ambiente di sviluppo locale localhost
:
GET https:/localhost:5001/api/Book
Metodi HTTP
Il generatore di API dati usa il metodo HTTP nella richiesta per determinare quale azione eseguire sull'entità designata della richiesta. I verbi HTTP seguenti sono disponibili, a seconda delle autorizzazioni impostate per una determinata entità.
Metodo | Descrizione |
---|---|
GET |
Ottenere zero, uno o più elementi |
POST |
Creare un nuovo elemento |
PATCH |
Aggiornare un elemento con nuovi valori, se presente. In caso contrario, creare un nuovo elemento |
PUT |
Sostituire un elemento con un nuovo elemento, se presente. In caso contrario, creare un nuovo elemento |
DELETE |
Eliminare un elemento |
Percorso rest
Il percorso rimanente definisce la posizione dell'API REST del generatore di API dati. Il percorso è configurabile nella configurazione di runtime e per impostazione predefinita è /api. Per altre informazioni, vedere configurazione del percorso REST.
Entità
Entity è la terminologia usata per fare riferimento a una risorsa API REST in Data API builder. Per impostazione predefinita, il valore della route URL per un'entità è il nome dell'entità definito nella configurazione di runtime. Il valore del percorso DELL'URL REST di un'entità è configurabile nelle impostazioni REST dell'entità. Per ulteriori informazioni, consultare la configurazione dell'entità .
Formato set di risultati
Il risultato restituito è un oggetto JSON con questo formato:
{
"value": []
}
Gli elementi correlati all'entità richiesta sono disponibili nella matrice value
. Per esempio:
{
"value": [
{
"id": 1000,
"title": "Foundation"
},
{
"id": 1001,
"title": "Foundation and Empire"
}
]
}
Nota
Per impostazione predefinita, vengono restituiti solo i primi 100 elementi.
OTTIENI
Usando il metodo GET è possibile recuperare uno o più elementi dell'entità desiderata.
Parametri URL
Gli endpoint REST consentono di recuperare un elemento in base alla relativa chiave primaria usando i parametri URL. Per le entità con una singola chiave primaria, il formato è semplice:
GET /api/{entity}/{primary-key-column}/{primary-key-value}
Per recuperare un libro con ID di 1001
, usare:
GET /api/book/id/1001
Per le entità con chiavi primarie composte, in cui vengono usate più colonne per identificare in modo univoco un record, il formato URL include tutte le colonne chiave in sequenza:
GET /api/{entity}/{primary-key-column1}/{primary-key-value1}/{primary-key-column2}/{primary-key-value2}
Se un'entità books
ha una chiave composta costituita da id1
e id2
, puoi recuperare un libro specifico in questo modo:
GET /api/books/id1/123/id2/abc
Per esempio:
Ecco come dovrebbe apparire una chiamata:
### 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
Parametri di query
Gli endpoint REST supportano i parametri di query seguenti (con distinzione tra maiuscole e minuscole) per controllare gli elementi restituiti:
-
$select
: restituisce solo le colonne selezionate -
$filter
: filtra gli elementi restituiti -
$orderby
: definisce la modalità di ordinamento dei dati restituiti -
$first
e$after
: restituisce solo gli elementin
principali
I parametri di query possono essere usati insieme.
$select
Il parametro di query $select
consentire di specificare quali campi devono essere restituiti. Per esempio:
### 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
Nota
Se uno dei campi richiesti non esiste o non è accessibile a causa delle autorizzazioni configurate, viene restituito un 400 - Bad Request
.
Il parametro di query $select
, noto anche come "proiezione", viene usato per controllare le dimensioni dei dati restituiti in una risposta API. Con solo le colonne necessarie, $select
riduce le dimensioni del payload, che possono migliorare le prestazioni riducendo al minimo il tempo di analisi, riducendo l'utilizzo della larghezza di banda e accelerando l'elaborazione dei dati. Questa ottimizzazione si estende al database. Vengono recuperate solo le colonne richieste.
$filter
Il valore dell'opzione $filter
è un'espressione di predicato (un'espressione che restituisce un risultato booleano) usando i campi dell'entità. Nella risposta vengono inclusi solo gli elementi in cui l'espressione restituisce True. Per esempio:
### 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
Gli operatori supportati dall'opzione $filter
sono:
Operatore | Digitare | Descrizione | Esempio |
---|---|---|---|
eq |
Paragone | Uguale | title eq 'Hyperion' |
ne |
Paragone | Diverso da | title ne 'Hyperion' |
gt |
Paragone | Maggiore | year gt 1990 |
ge |
Paragone | Maggiore o uguale a | year ge 1990 |
lt |
Paragone | Meno di | year lt 1990 |
le |
Paragone | Minore o uguale a | year le 1990 |
and |
Logico | Logico e | year ge 1980 and year lt 1990 |
or |
Logico | Logico o | year le 1960 or title eq 'Hyperion' |
not |
Logico | Negazione logica | not (year le 1960) |
( ) |
Raggruppamento | Raggruppamento delle precedenze | (year ge 1970 or title eq 'Foundation') and pages gt 400 |
Nota
$filter
è un argomento con distinzione tra maiuscole e minuscole.
Il parametro di query $filter
in Generatore API dati di Azure potrebbe ricordare alcuni utenti di OData e questo perché è stato ispirato direttamente dalle funzionalità di filtro di OData. La sintassi è quasi identica, rendendo più semplice per gli sviluppatori che hanno già familiarità con OData scegliere e usare. Questa somiglianza è stata intenzionale, finalizzata a fornire un modo familiare e potente per filtrare i dati tra API diverse.
$orderby
Il valore del parametro orderby
è un elenco delimitato da virgole di espressioni utilizzate per ordinare gli elementi.
Ogni espressione nel valore del parametro orderby
può includere il suffisso desc
per richiedere un ordine decrescente, separato dall'espressione da uno o più spazi.
Per esempio:
### 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
Nota
$orderBy
è un argomento sensibile alle maiuscole e minuscole.
Il parametro di query $orderby
è utile per ordinare i dati direttamente sul server, facilmente gestito anche dal lato client. Tuttavia, diventa utile in combinazione con altri parametri di query, ad esempio $filter
e $first
. Il parametro consente alla paginazione di mantenere un set di dati stabile e prevedibile durante l'impaginazione tramite raccolte di grandi dimensioni.
$first
e $after
Il parametro di query $first
limita il numero di elementi restituiti in una singola richiesta. Per esempio:
GET /api/book?$first=5
Questa richiesta restituisce i primi cinque libri. Il parametro di query $first
in Generatore API dati di Azure è simile alla clausola TOP
in SQL. Entrambi vengono usati per limitare il numero di record restituiti da una query. Proprio come TOP
in SQL consente di specificare la quantità di righe da recuperare, $first
consente di controllare il numero di elementi restituiti dall'API.
$first
è utile quando si desidera recuperare un piccolo subset di dati, ad esempio i primi 10 risultati, senza recuperare l'intero set di dati. Il vantaggio principale è l'efficienza, in quanto riduce la quantità di dati trasmessi ed elaborati.
Nota
In Generatore API dati di Azure il numero di righe restituite per impostazione predefinita è limitato da un'impostazione nel file di configurazione. Gli utenti possono eseguire l'override di questo limite usando il parametro $first
per richiedere più righe, ma esiste ancora un numero massimo di righe configurato che può essere restituito complessivamente. Inoltre, esiste un limite per i megabyte totali che possono essere restituiti in una singola risposta, che è configurabile anche.
Se sono disponibili più elementi oltre il limite specificato, la risposta include una proprietà nextLink
:
{
"value": [],
"nextLink": "dab-will-generate-this-continuation-url"
}
Il nextLink
può essere usato con il parametro di query $after
per recuperare il set successivo di elementi:
GET /api/book?$first={n}&$after={continuation-data}
Questo approccio di continuazione usa l'impaginazione basata su cursore. Un cursore univoco è un riferimento a un elemento specifico nel set di dati, determinando dove continuare a recuperare i dati nel set successivo. A differenza dell'impaginazione dell'indice che usa offset o indici, la paginazione basata su cursore non si basa sull'ignorare i record. La continuazione del cursore rende più affidabile con set di dati di grandi dimensioni o con modifiche frequenti. Garantisce invece un flusso uniforme e coerente di recupero dei dati iniziando esattamente dove è stata interrotta l'ultima query, in base al cursore fornito.
Per esempio:
### 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}
INSERISCI
Creare un nuovo elemento per l'entità specificata. Per esempio:
POST /api/book
Content-type: application/json
{
"id": 2000,
"title": "Do Androids Dream of Electric Sheep?"
}
La richiesta POST crea un nuovo libro. Tutti i campi che non possono essere nullable devono essere forniti. Se l'operazione ha esito positivo, viene restituito l'oggetto entità completo, inclusi i campi Null:
{
"value": [
{
"id": 2000,
"title": "Do Androids Dream of Electric Sheep?",
"year": null,
"pages": null
}
]
}
METTERE
PUT crea o sostituisce un elemento dell'entità specificata. Il modello di query è:
PUT /api/{entity}/{primary-key-column}/{primary-key-value}
Per esempio:
PUT /api/book/id/2001
Content-type: application/json
{
"title": "Stranger in a Strange Land",
"pages": 525
}
Se è presente un elemento con la chiave primaria specificata 2001
, i dati forniti sostituiscono completamente tale elemento. Se invece non esiste un elemento con tale chiave primaria, viene creato un nuovo elemento.
In entrambi i casi, il risultato è simile al seguente:
{
"value": [
{
"id": 2001,
"title": "Stranger in a Strange Land",
"year": null,
"pages": 525
}
]
}
Intestazione della richiesta HTTP If-Match: *
L'intestazione HTTP If-Match: *
assicura che un'operazione di aggiornamento sia eseguitasolo se la risorsa esiste. Se la risorsa non esiste, l'operazione avrà esito negativo con codice di stato HTTP: 404 Not Found
. Se l'intestazione If-Match
viene omessa, il comportamento predefinito consiste nell'eseguire un upsert, che crea la risorsa se non esiste già.
Esempio di :
PUT /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json
{
"title": "Stranger in a Strange Land",
"pages": 525
}
Nota
Se si specifica un valore diverso da *
nell'intestazione If-Match
, il generatore di API dati restituirà un errore 400 Bad Request
, perché la corrispondenza basata su ETag non è supportata.
BENDA
PATCH crea o aggiorna l'elemento dell'entità specificata. Sono interessati solo i campi specificati. Tutti i campi non specificati nel corpo della richiesta non sono interessati. Se non esiste un elemento con la chiave primaria specificata, viene creato un nuovo elemento.
Il modello di query è:
PATCH /api/{entity}/{primary-key-column}/{primary-key-value}
Per esempio:
PATCH /api/book/id/2001
Content-type: application/json
{
"year": 1991
}
Il risultato è simile al seguente:
{
"value": [
{
"id": 2001,
"title": "Stranger in a Strange Land",
"year": 1991,
"pages": 525
}
]
}
Intestazione della richiesta HTTP If-Match: *
L'intestazione HTTP If-Match: *
assicura che un'operazione di aggiornamento venga eseguitasolo se la risorsa esiste. Se la risorsa non esiste, l'operazione avrà esito negativo con codice di stato HTTP: 404 Not Found
. Se l'intestazione If-Match
viene omessa, il comportamento predefinito consiste nell'eseguire un upsert, che crea la risorsa se non esiste già.
Esempio di :
PATCH /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json
{
"year": 1991
}
Nota
Se si specifica un valore diverso da *
nell'intestazione If-Match
, il generatore di API dati restituirà un errore 400 Bad Request
, perché la corrispondenza basata su ETag non è supportata.
CANCELLARE
DELETE elimina l'elemento dell'entità specificata. Il modello di query è:
DELETE /api/{entity}/{primary-key-column}/{primary-key-value}
Per esempio:
DELETE /api/book/id/2001
In caso di esito positivo, il risultato è una risposta vuota con codice di stato 204.
Transazioni di database per le richieste dell'API REST
Per elaborare le richieste API POST, PUT, PATCH e DELETE; Generatore API dati costruisce ed esegue le query di database in una transazione.
Nella tabella seguente sono elencati i livelli di isolamento con cui vengono create le transazioni per ogni tipo di database.
Tipo di database | Livello di isolamento | Altre informazioni |
---|---|---|
SQL di Azure (o) SQL Server | Read Committed | SQL di Azure |
MySQL | Lettura ripetibile | mySQL |
PostgreSQL | Read Committed | PostgreSQL |