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

設定為可透過 GraphQL 取得的實體位於預設路徑：https://{base_url}//graphql。 數據 API 產生器會自動產生 GraphQL 架構，其中包含所有已設定實體的查詢和突變字段。 您可以使用包含自動完成等功能的新式 GraphQL 用戶端來探索 GraphQL 架構。

如果您遵循 用戶入門 範例，其中 books 和針對 GraphQL 存取設定的 authors 實體，您可以看到使用 GraphQL 是多麼容易。

結果集格式

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

{
    "data": {}    
}

注意

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

支援的根類型

資料 API 產生器支援下列 GraphQL 根類型：

查詢突變

查詢

每個實體都支援下列動作：

• 分頁
• 依主鍵 查詢
• 一般查詢

除非另有指定，否則數據 API 產生器會使用實體的 單一 名稱，每當查詢預期傳回單一專案時。 相反地，每當預期查詢傳回專案清單時，數據 API 產生器就會使用實體 複數 名稱。 例如，book 實體具有：

• book_by_pk()：傳回零或一個實體
• books()：傳回零個或多個實體的清單

分頁

傳回零個或多個專案的所有查詢類型都支援分頁：

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}

• item 物件允許存取實體欄位
• 如果傳回更多專案，hasNextPage 會設定為 true
• endCursor 會傳回不透明的數據指標字串，可用於 first 和 after 查詢參數，以取得下一組專案（或頁面）。

依主鍵查詢

每個實體都支援使用下列查詢格式，透過其主鍵擷取特定專案：

<entity>_by_pk(<pk_colum>:<pk_value>)
{
    <fields>
}

例如：

{
  book_by_pk(id:1010) {
    title
  }
}

一般查詢

每個實體也支援一般查詢模式，因此您可以使用下列參數，只要求您想要的專案：

• filter：篩選傳回的專案
• orderBy：定義傳回的數據排序方式
• first 和 after：只傳回頂端 n 專案

例如：

{
  authors(
    filter: {
        or: [
          { first_name: { eq: "Isaac" } }
          { last_name: { eq: "Asimov" } }
        ]
    }
  ) {
    items {
      first_name
      last_name
      books(orderBy: { year: ASC }) {
        items {
          title
          year
        }
      }
    }
  }
}

filter

filter 參數的值是使用實體欄位的述詞表達式（傳回布爾值的表達式）。 只有表達式評估為 『True』 的專案才會包含在回應中。 例如：

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

此查詢會傳回標題中含有 Foundation 字的所有書籍。

filter 參數支持的運算符如下：

算子	類型	描述	例
eq	比較	平等	books(filter: { title: { eq: "Foundation" } })
neq	比較	不相等	books(filter: { title: { neq: "Foundation" } })
gt	比較	大於	books(filter: { year: { gt: 1990 } })
gte	比較	大於或等於	books(filter: { year: { gte: 1990 } })
lt	比較	小於	books(filter: { year: { lt: 1990 } })
lte	比較	小於或等於	books(filter: { year: { lte: 1990 } })
isNull	比較	為 null	books(filter: { year: { isNull: true} })
contains	字串	包含	books(filter: { title: { contains: "Foundation" } })
notContains	字串	不包含	books(filter: { title: { notContains: "Foundation" } })
startsWith	字串	開頭為	books(filter: { title: { startsWith: "Foundation" } })
endsWith	字串	結尾為	books(filter: { title: { endsWith: "Empire" } })
and	邏輯	邏輯和	authors(filter: { and: [ { first_name: { eq: "Robert" } } { last_name: { eq: "Heinlein" } } ] })
or	邏輯	邏輯或	authors(filter: { or: [ { first_name: { eq: "Isaac" } } { first_name: { eq: "Dan" } } ] })

orderBy

orderby 的值會設定傳回結果集中項目的順序。 例如：

{
  books(orderBy: {title: ASC} )
  {
    items {
      id
      title
    }
  }
}

此查詢會傳回依 title排序的書籍。

first 和 after

參數 first 限制傳回的項目數。 例如：

query {
  books(first: 5)
  {
    items {
      id
      title
    }
    hasNextPage
    endCursor
  }
}

此查詢會傳回前五本書。 未指定 orderBy 時，會根據基礎主鍵來排序專案。 提供給 orderBy 的值必須是正整數。

如果 book 實體中的專案比透過 first所要求的實體多，則 hasNextPage 欄位會評估為 true，而 endCursor 會傳回字串，該字串可與 after 參數搭配使用，以存取下一個專案。 例如：

query {
  books(first: 5, after: "W3siVmFsdWUiOjEwMDQsIkRpcmVjdGlvbiI6MCwiVGFibGVTY2hlbWEiOiIiLCJUYWJsZU5hbWUiOiIiLCJDb2x1bW5OYW1lIjoiaWQifV0=")
  {
    items {
      id
      title
    }
    hasNextPage
    endCursor
  }
}

突變

針對每個實體，系統會自動建立支援建立、更新和刪除作業的突變。 突變數作業是使用下列名稱模式建立：<operation><entity>。 例如，針對 book 實體，突變會是：

• createbook：建立新書
• updatebook：更新現有的書籍
• deletebook：刪除指定的書籍

創造

若要建立所需實體的新元素，則會提供 create<entity> 突變。 建立的突變需要 item 參數，其中會指定建立新專案時，實體必要字段的值。

create<entity>(item: <entity_fields>)
{
    <fields>
}

例如：

mutation {
  createbook(item: {
    id: 2000,
    title: "Leviathan Wakes"    
  }) {
    id
    title
  }  
}

更新

若要更新所需實體的元素，則會提供 update<entity> 突變。 更新突變需要兩個參數：

• <primary_key>，主鍵數據行的索引鍵/值清單和相關值，用來識別要更新的專案
• item：參數，具有實體的必要欄位值，在更新指定的專案時使用

update<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,] item: <entity_fields>)
{
    <fields>
}

例如：

mutation {
  updatebook(id: 2000, item: {
    year: 2011,
    pages: 577    
  }) {
    id
    title
    year
    pages
  }
}

刪除

若要刪除所需實體的元素，則會提供 delete<entity> 突變。 要刪除之專案的主鍵是必要參數。

delete<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,])
{
    <fields>
}

例如：

mutation {
  deletebook(id: 1234)
  {
    id
    title
  }  
}

突變的資料庫交易

為了處理典型的 GraphQL 突變要求，數據 API 產生器會建構兩個資料庫查詢。 其中一個資料庫查詢會執行與突變相關聯的更新 （或） 插入 （或） 刪除動作。 另一個資料庫查詢會擷取選取集中要求的數據。

數據 API 產生器會在交易中執行這兩個資料庫查詢。 交易只會針對 SQL 資料庫類型建立。

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

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

相關內容

• GraphQL 組態參考
• OpenAPI