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}

I componenti di una richiesta includono:

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à.

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"
    }
  ]
}

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 elementi n 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

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:

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

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.

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
}

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
}

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.

Contenuto correlato

• OpenAPI
• riferimento alla configurazione REST