數據 API 產生器中的資料庫物件

數據 API 產生器包含檢視和預存程式的支援，作為對應至資料庫數據表或容器的替代方案。 這些不同的資料庫物件需要自定義組態，才能順暢地對應至 REST 或 GraphQL 端點。 需要一些自定義設定，才能搭配檢視和預存程式使用數據 API 產生器。

本文包含如何搭配數據 API 產生器使用檢視和預存程式的詳細數據。

視圖

檢視可以類似於數據 API 產生器中的數據表使用方式。 檢視使用方式必須藉由將實體的來源類型指定為 view來定義。 此外，還必須提供 key-fields 屬性，以便 Data API 產生器知道如何視需要識別及傳回單一專案。

如果您有檢視，例如，dbo.vw_books_details 可以使用下列 dab 命令來公開：

dab add BookDetail --source dbo.vw_books_details --source.type View --source.key-fields "id" --permissions "anonymous:read"

dab-config.json 檔案會像下列範例所示：

"BookDetail": {
  "source": {
    "type": "view",
    "object": "dbo.vw_books_details",
    "key-fields": [ "id" ]
  },
  "permissions": [{
    "role": "anonymous",
    "actions": [ "read" ]
  }]
}

檢視的 REST 支援

從 REST 觀點來看，檢視的行為就像數據表一樣。 支援所有 REST 作業。

檢視的 GraphQL 支援

從 GraphQL 的觀點來看，檢視的行為就像數據表一樣。 支援所有 GraphQL 作業。

預存程式

預存程式可作為與 Data API 產生器所公開之實體相關的物件。 必須定義預存程式使用方式，以指定實體的來源類型 stored-procedure。

如果您有預存程式，例如，dbo.stp_get_all_cowritten_books_by_author 可以使用下列 dab 命令來公開它：

dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" --source.params "searchType:s" --permissions "anonymous:execute" --rest.methods "get" --graphql.operation "query"

dab-config.json 檔案會像下列範例所示：

"GetCowrittenBooksByAuthor": {
  "source": {
    "type": "stored-procedure",
    "object": "dbo.stp_get_all_cowritten_books_by_author",
    "parameters": {
      "searchType": "s"
    }
  },
  "rest": {
    "methods": [ "GET" ]
  },
  "graphql": {
    "operation": "query"
  },
  "permissions": [{
   "role": "anonymous",
    "actions": [ "execute" ]
  }]
}

parameters 會定義應該公開哪些參數，並在 HTTP 要求中未提供這些參數時，提供要傳遞至預存程序參數的預設值。

限制

• Data API 產生器只會使用預存程式傳回的第一個結果集。
• 僅支援 sys.dm_exec_describe_first_result_set 所描述之第一個結果集元數據的預存程式。
• 針對 REST 和 GraphQL 端點：當組態檔和 URL 查詢字串中同時指定預存程式參數時，URL 查詢字串中的參數優先。
• 預存程式支援的實體沒有針對數據表、集合或檢視所支援的實體自動提供的所有功能。
  • 預存程式支援的實體不支援分頁、排序或篩選。 這類實體也不支援傳回主鍵值所指定的專案。
  • 不支援欄位/參數層級授權規則。

預存程式的 REST 支援

預存程式支持的實體的 REST 端點行為可以設定為支援一或多個 HTTP 動詞命令（GET、POST、PUT、PATCH、DELETE）。 實體的 REST 區段會像下列範例所示：

"rest": {
  "methods": [ "GET", "POST" ]
}

使用組態中未列出的 HTTP 方法時，實體的任何 REST 要求都失敗，HTTP 405 方法不允許。 例如，執行 PUT 要求失敗，錯誤碼為 405。 如果 區段已從實體的 REST 組態中排除，則會推斷 POST 的預設方法 。 若要停用此實體的 REST 端點，請設定 "rest": false，且預存程式實體上的任何 REST 要求都失敗，HTTP 404 找不到。

如果預存程式接受參數，則可以在呼叫具有 GET HTTP 動詞命令的 REST 端點時，在 URL 查詢字串中傳遞參數。 例如：

GET http://<dab-server>/api/GetCowrittenBooksByAuthor?author=isaac%20asimov

使用 POST、PUT、PATCH、DELETE 等其他 HTTP 動詞來執行的預存程式，需要在要求本文中以 JSON 形式傳遞參數。 例如：

POST http://<dab-server>/api/GetCowrittenBooksByAuthor

{
  "author": "isaac asimov"
}

預存程式的 GraphQL 支援

您可以使用預存程式支援實體的 graphql 選項，在 GraphQL 中設定預存程式執行。 明確設定實體的作業可讓您以符合預存程序行為的方式，在 GraphQL 架構中代表預存程式。

未設定作業的任何值會導致建立 mutation 作業。

例如，使用 operation 選項的值 query，會導致預存程式解析為 GraphQL 架構中的查詢欄位。

CLI 使用方式：

dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" --source.params "searchType:s" --permissions "anonymous:execute" --rest.methods "GET" --graphql.operation "query"

執行時間群組態：

"graphql": {
  "operation": "query"
}

GraphQL 架構元件：類型和查詢欄位：

type GetCowrittenBooksByAuthor {
  id: Int!
  title: String
}

在架構中，預存程序的查詢和突變作業 execute 為前置詞。 針對先前的預存程式，產生的確切查詢名稱欄位會 executeGetCowrittenBooksByAuthor。 產生的 GraphQL 型態為：

type Query {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

或者，operation 可以設定為 mutation，使突變欄位代表 GraphQL 架構中的預存程式。 dab update 命令可用來變更 operation：

dab update GetCowrittenBooksByAuthor --graphql.operation "mutation"

執行時間群組態：

"graphql": {
  "operation": "mutation"
}

產生的 GraphQL 架構為：

type Mutation {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

如果預存程式接受參數，則可以將這些參數當做查詢的參數或突變傳遞。 例如：

query {
  executeGetCowrittenBooksByAuthor(author:"asimov")
   {
    id
    title
    pages
    year
  }
}

相關內容

• 組態參考
• 安裝 CLI