在數據 API 產生器中裝載 REST 端點

發行項
12/20/2024

數據 API 產生器提供 RESTful Web API，可讓您從連接的數據庫存取數據表、檢視和預存程式。實體代表數據 API 產生器運行時間組態中的資料庫物件。實體必須在運行時間組態中設定，才能在 REST API 端點上使用。

呼叫 REST API 方法

若要讀取或寫入資源（或實體），您可以使用下列模式來建構要求：

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

注意

URL 路徑的所有元件，包括實體和查詢參數，都會區分大小寫。

要求的元件包括：

	描述
`{HTTP method}`	對數據 API 產生器的要求所使用的 HTTP 方法
`{base_url}`	載入資料 API 產生器實例的網域（或 localhost 伺服器和埠）
`{rest-path}`	運行時間組態中設定的 REST API 端點基底路徑
`{entity}`	運行時間組態中所定義的資料庫物件名稱

以下是本機開發環境 localhost中 REST 端點基底 /api 下實體 book 的 GET 要求範例：

GET https:/localhost:5001/api/Book

HTTP 方法

數據 API 產生器會在您的要求上使用 HTTP 方法，以判斷要對要求指定的實體採取哪些動作。下列 HTTP 動詞可供使用，視特定實體的許可權集而定。

方法	描述
`GET`	取得零、一或多個專案
`POST`	建立新專案
`PATCH`	如果專案存在，請使用新的值來更新專案。否則，請建立新專案
`PUT`	如果專案存在，請將專案取代為新的專案。否則，請建立新專案
`DELETE`	刪除專案

Rest 路徑

其餘路徑會指定數據 API 產生器 REST API 的位置。路徑可在執行時間組態中設定，預設為 /api。如需詳細資訊，請參閱REST 路徑組態。

實體

Entity 是用來在數據 API 產生器中參考 REST API 資源的術語。根據預設，實體的 URL 路由值是運行時間組態中定義的實體名稱。實體的 REST URL 路徑值可在實體的 REST 設定內設定。如需詳細資訊，請參閱實體組態。

結果集格式

傳回的結果是 JSON 物件，其格式如下：

{
    "value": []    
}

所要求的實體相關項目在 value 陣列中可用。例如：

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

注意

預設只會傳回前100個專案。

獲取

使用 GET 方法，您可以擷取所需實體的一或多個專案。

URL 參數

REST 端點可讓您使用 URL 參數，依其主鍵擷取專案。對於具有單一主鍵的實體，格式很簡單：

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

若要擷取標識符為 1001的書籍，您可以使用：

GET /api/book/id/1001

對於具有複合主鍵的實體，其中多個數據行用來唯一識別記錄，URL 格式會依序包含所有索引鍵數據行：

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

如果 books 實體的複合鍵是由 id1 和 id2所組成，您可以這樣擷取特定的書籍：

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

例如：

以下是呼叫的外觀：

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

查詢參數

REST 端點支援下列查詢參數（區分大小寫）來控制傳回的專案：

$select：只傳回選取的數據行
$filter：篩選傳回的項目
$orderby：定義傳回的數據排序方式
$first 和 $after：只傳回頂端 n 項目

查詢參數可以一起使用。

`$select`

查詢參數 $select 允許指定必須傳回哪些欄位。例如：

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

注意

如果任何要求欄位不存在或因為設定的許可權而無法存取，則會傳回 400 - Bad Request。

$select 查詢參數也稱為「投影」，可用來控制 API 回應中傳回的數據大小。僅使用所需的數據行時，$select 可減少承載大小，藉由將剖析時間降至最低、降低頻寬使用量及加快數據處理速度，以改善效能。此優化延伸至資料庫。在那裡，只會擷取要求的數據行。

`$filter`

$filter 選項的值是使用實體欄位的述詞表達式（即一個傳回布爾結果的表達式）。只有表達式評估為 True 的專案才會包含在回應中。例如：

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

$filter 選項支援的運算符如下：

算子	類型	描述	例
`eq`	比較	平等	`title eq 'Hyperion'`
`ne`	比較	不相等	`title ne 'Hyperion'`
`gt`	比較	大於	`year gt 1990`
`ge`	比較	大於或等於	`year ge 1990`
`lt`	比較	小於	`year lt 1990`
`le`	比較	小於或等於	`year le 1990`
`and`	邏輯	邏輯和	`year ge 1980 and year lt 1990`
`or`	邏輯	邏輯或	`year le 1960 or title eq 'Hyperion'`
`not`	邏輯	邏輯否定	`not (year le 1960)`
`( )`	分組	優先順序群組	`(year ge 1970 or title eq 'Foundation') and pages gt 400`

注意

$filter 是區分大小寫的參數。

Azure 數據 API 產生器中的 $filter 查詢參數可能會提醒一些 OData 使用者，這是因為它直接受到 OData 篩選功能的啟發。語法幾乎完全相同，讓熟悉 OData 的開發人員輕鬆挑選和使用。這種相似性是刻意的，目的是提供熟悉且強大的方法來篩選不同 API 的數據。

`$orderby`

orderby 參數的值是以逗號分隔的表達式清單，用來排序項目。

orderby 參數值中的每個運算式可能包含後置詞 desc，這用於指定遞減順序，並以一個或多個空格與運算式分隔。

例如：

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

注意

$orderBy 是區分大小寫的參數。

$orderby 查詢參數對於直接在伺服器上排序數據非常有價值，也可以輕鬆地在用戶端上處理。不過，當與其他查詢參數結合時，它會變得很有用，例如 $filter 和 $first。參數可讓您在分頁大型集合時維護穩定且可預測的數據集。

`$first` 和 `$after`

$first 查詢參數會限制單一要求中傳回的項目數。例如：

GET /api/book?$first=5

此要求會傳回前五本書。 Azure Data API Builder 中的 $first 查詢參數類似於 SQL 中的 TOP 子句。這兩者都用來限制從查詢傳回的記錄數目。就像 SQL 中的 TOP 可讓您指定要擷取的數據列數量一樣，$first 可讓您控制 API 所傳回的項目數。當您想要擷取小型數據子集，例如前10個結果，而不擷取整個數據集時，$first 很有用。主要優點是效率，因為它可減少傳輸和處理的數據量。

注意

在 Azure 資料 API 產生器中，預設傳回的數據列數目會受限於組態檔中的設定。使用者可以使用 $first 參數來覆寫此限制，以要求更多數據列，但仍有可整體傳回的數據列數目上限。此外，單一回應中可以傳回的總 MB 數有一個限制，也可以進行設定。

如果有更多項目超出指定的限制，回應會包含 nextLink 屬性：

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

nextLink 可以與 $after 查詢參數搭配使用，以擷取下一組項目：

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

這個接續方法會使用數據指標型分頁。唯一的數據指標是數據集中特定項目的參考，可判斷下一個數據集中要繼續擷取數據的位置。不同於使用位移或索引的索引分頁，數據指標型分頁並不依賴略過記錄。數據指標接續可讓大型數據集或經常變更的數據更可靠。相反地，它會根據所提供的數據指標，開始最後一個查詢的離開位置，以確保數據擷取順暢且一致。

例如：

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

發佈

為指定的實體建立新專案。例如：

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

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

POST 要求會建立新書籍。必須提供無法為 Null 的所有欄位。如果成功，則會傳回完整的實體物件，包括任何 Null 欄位：

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

放

PUT 會建立或取代指定實體的專案。查詢模式為：

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

例如：

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

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

如果有具有指定主鍵的專案 2001，則所提供的數據 會完全取代該專案。如果具有該主鍵的專案不存在，則會建立新的專案。

不論是哪一種情況，結果都類似：

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

`If-Match: *` HTTP 要求標頭

HTTP 標頭確保更新作業只有在資源存在的情況下才會執行。如果資源不存在，作業將會失敗，並出現 HTTP 狀態代碼：404 Not Found。如果 If-Match 標頭省略，則預設行為是執行 upsert，如果資源不存在，則會建立資源。

範例：

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

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

注意

如果您在 If-Match 標頭中指定 * 以外的值，Data API 產生器會傳回 400 Bad Request 錯誤，因為不支援以 ETag 為基礎的比對。

補丁

PATCH 會建立或更新指定實體的專案。只會影響指定的欄位。要求本文中未指定的所有欄位都不會受到影響。如果具有指定主鍵的專案不存在，則會建立新的專案。

查詢模式為：

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

例如：

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

{    
  "year": 1991
}

結果如下：

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

`If-Match: *` HTTP 要求標頭

只有在資源存在的情況下，HTTP 標頭可確保執行更新作業。如果資源不存在，作業將會失敗，並出現 HTTP 狀態代碼：404 Not Found。如果 If-Match 標頭省略，則預設行為是執行 upsert，如果資源不存在，則會建立資源。

範例：

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

{
    "year": 1991
}

注意

如果您在 If-Match 標頭中指定 * 以外的值，Data API 產生器會傳回 400 Bad Request 錯誤，因為不支援以 ETag 為基礎的比對。

刪除

DELETE 會刪除指定實體的專案。查詢模式為：

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

例如：

DELETE /api/book/id/2001

如果成功，結果會是狀態代碼為 204 的空白回應。

REST API 要求的資料庫交易

處理 POST、PUT、PATCH 和 DELETE API 要求;數據 API 產生器會建構和執行交易中的資料庫查詢。

下表列出針對每個資料庫類型建立交易的隔離等級。

資料庫類型	隔離等級	詳細資訊
Azure SQL （或） SQL Server	讀取認可	Azure SQL
MySQL	可重複讀取	MySQL
PostgreSQL	讀取認可	PostgreSQL

共用方式為

在數據 API 產生器中裝載 REST 端點

呼叫 REST API 方法

HTTP 方法

Rest 路徑

實體

結果集格式

獲取

URL 參數

例如：

查詢參數

`$select`

`$filter`

`$orderby`

`$first` 和 `$after`

發佈

放

`If-Match: *` HTTP 要求標頭

補丁

`If-Match: *` HTTP 要求標頭

刪除

REST API 要求的資料庫交易

意見反應

其他資源

共用方式為

在數據 API 產生器中裝載 REST 端點

呼叫 REST API 方法

HTTP 方法

Rest 路徑

實體

結果集格式

獲取

URL 參數

例如：

查詢參數

$select

$filter

$orderby

$first 和 $after

發佈

放

If-Match: * HTTP 要求標頭

補丁

If-Match: * HTTP 要求標頭

刪除

REST API 要求的資料庫交易

相關內容

意見反應

其他資源

`$select`

`$filter`

`$orderby`

`$first` 和 `$after`

`If-Match: *` HTTP 要求標頭

`If-Match: *` HTTP 要求標頭