如何呼叫 GraphQL 端點

資料 API 產生器 （DAB） 中的 GraphQL 端點可讓您精確查詢和修改資料。 每個查詢都會準確宣告您需要的欄位，並支援篩選、排序和分頁結果的引數。

根據預設，DAB 會將其 GraphQL 端點託管在：

https://{base_url}/graphql

透過設定公開的實體會自動包含在GraphQL結構描述中。 例如，如果您有 books 和 authors 實體，則兩者都會在結構描述中顯示為根欄位。

備註

要探索結構與自動補全欄位，請使用任何現代 GraphQL 用戶端或 IDE（例如 Apollo、Insomnia 或 Visual Studio Code GraphQL 擴充套件）。

Data API 產生器支援的關鍵字

概念 GraphQL Purpose
投影 項目 選擇要傳回的欄位
篩選 篩選 依條件限制資料列
排序 orderBy 定義排序順序
頁面大小 第一 限制每頁的項目
繼續 後 從最後一頁繼續

基本結構

每個 GraphQL 查詢都以代表實體的根欄位開頭。 所有 GraphQL 請求都會傳送 POST 到 /graphql 端點，JSON 主體中包含查詢。

{
  books {
    items {
      id
      title
      year
      pages
    }
  }
}

回應是一個與你的選擇集形狀相同的 JSON 物件。 頁碼與錯誤細節僅在適用時顯示。

備註

根據預設，除非另有設定，否則每個查詢 DAB 最多會傳回 100 個項目 （runtime.pagination.default-page-size）。

POST https://localhost:5001/graphql
Content-Type: application/json

{
  "query": "{ books { items { id title year pages } } }"
}

成功：

{
  "data": {
    "books": {
      "items": [
        { "id": 1, "title": "Dune", "year": 1965, "pages": 412 },
        { "id": 2, "title": "Foundation", "year": 1951, "pages": 255 }
      ]
    }
  }
}

成功的分頁：

{
  "data": {
    "books": {
      "items": [
        { "id": 1, "title": "Dune", "year": 1965, "pages": 412 },
        { "id": 2, "title": "Foundation", "year": 1951, "pages": 255 }
      ],
      "hasNextPage": true,
      "endCursor": "eyJpZCI6Mn0="
    }
  }
}

錯誤：

{
  "errors": [
    {
      "message": "Could not find item with the given key.",
      "locations": [{ "line": 1, "column": 3 }],
      "path": ["book_by_pk"]
    }
  ]
}

查詢類型

每個實體都支援兩個標準根查詢：

查詢 說明
entity_by_pk 根據主鍵傳回一筆記錄
entities 傳回符合篩選條件的記錄清單

傳回一筆記錄的範例：

{
  book_by_pk(id: 1010) {
    title
    year
  }
}

範例回傳多個結果

{
  books {
    items {
      id
      title
    }
  }
}

篩選結果

使用 filter 引數來限制傳回哪些記錄。

{
  books(filter: { title: { contains: "Foundation" } }) {
    items { id title }
  }
}

此查詢會傳回標題包含「基礎」的所有書籍。

篩選器可以將比較與邏輯運算子結合：

{
  authors(filter: {
    or: [
      { first_name: { eq: "Isaac" } }
      { last_name: { eq: "Asimov" } }
    ]
  }) {
    items { first_name last_name }
  }
}

請參閱 filter 引數參考，以取得支援的運算子，例如 eq、 neq、 ltlte、 和 isNull。

排序結果

orderBy引數定義記錄的排序方式。

{
  books(orderBy: { year: DESC, title: ASC }) {
    items { id title year }
  }
}

這會傳回依year遞減排序的書籍，然後再依title排序。

欲了解更多資訊，請參閱 orderBy 參數參考。

限制結果

引 first 數會限制單一要求中傳回的記錄數目。

{
  books(first: 5) {
    items { id title }
  }
}

這會傳回前五本書，依預設依主索引鍵排序。 您也可以使用 first: -1 來要求設定的頁面大小上限限制。

在 第一個引數參考中了解更多信息。

持續的結果

若要擷取下一頁，使用者應使用 after 引數與先前查詢的游標。

{
  books(first: 5, after: "eyJpZCI6NX0=") {
    items { id title }
  }
}

after 標記表示前一頁的結尾位置。 欲了解更多資訊，請參閱 論證後的參考資料。

欄位選擇（投影）

在 GraphQL 中，您可以準確選擇回應中顯示的欄位。 沒有像 SELECT * 這樣的萬用字元。 只請求您需要的內容。

{
  books {
    items { id title price }
  }
}

您也可以使用別名來重新命名回應中的欄位：

{
  books {
    items {
      bookTitle: title
      cost: price
    }
  }
}

如需詳細資訊，請參閱 欄位投影參考 。

修改資料

GraphQL 變異允許你根據實體權限建立、更新和刪除紀錄。

突變 Action
createEntity 建立新專案
updateEntity 更新現有項目
deleteEntity 移除項目

備註

這個 _by_pk 字尾僅適用於 查詢 （例如， book_by_pk）。 突變名稱中不包含這個後綴——使用 updateBook 和 deleteBook，而非 updateBook_by_pk 或 deleteBook_by_pk。

這很重要

GraphQL 變異需要一個主動的資料庫連線池。 若連接字串設定為 Pooling=False 或 MultipleActiveResultSets=False，突變將以錯誤 Implicit distributed transactions have not been enabled失敗。 設定 Pooling=True 和 MultipleActiveResultSets=True（SQL Server）或相應的資料庫提供者。

小提示

對於透過 GraphQL 暴露的儲存程序，DAB 會在實體名稱前加上 execute。 例如，一個名為 GetBookById 的儲存程序實體會成為 executeGetBookById 結構中的實體。 欲了解更多資訊，請參閱儲存程序。

建立新的記錄

用 create 突變來新增物品。

POST https://localhost:5001/graphql
Content-Type: application/json

{
  "query": "mutation { createBook(item: { id: 2000, title: \"Leviathan Wakes\", year: 2011, pages: 577 }) { id title year pages } }"
}

更新現有記錄

使用 update 突變來修改現有物品上的特定欄位。

POST https://localhost:5001/graphql
Content-Type: application/json

{
  "query": "mutation { updateBook(id: 2000, item: { title: \"Leviathan Wakes\", year: 2011, pages: 577 }) { id title year pages } }"
}

刪除記錄

用 delete 突變移除根據主鍵的項目。

POST https://localhost:5001/graphql
Content-Type: application/json

{
  "query": "mutation { deleteBook(id: 2000) { id title } }"
}
  • Last updated on