GraphQL 編輯器的 Fabric API

適用於 GraphQL 的 Fabric API 提供圖形化的瀏覽器內 GraphQL 開發環境，這是一個互動式平台，讓您撰寫、測試及查看 GraphQL 查詢和變動的即時結果。

使用 GraphQL 編輯器的人

GraphQL 編輯器對於以下功能至關重要：

• 應用程式開發者 在將查詢實作至應用程式前，會先在 Fabric 資料上進行查詢的原型設計及測試。
• 資料工程師 探索湖屋與倉庫資料結構，並驗證 GraphQL 架構設計
• Fabric 工作區貢獻者 正在測試資料存取權限並排除查詢問題
• BI 開發者學習 API 結構並為自訂應用程式建立資料存取模式
• 開發團隊 合作查詢開發，並排解 Fabric 工作空間內的資料存取問題

每當你需要針對 Fabric 資料來源進行互動式開發、測試或除錯 GraphQL 查詢時，都可以使用這個編輯器。

開始使用 GraphQL 編輯器

請依照以下步驟開始使用 GraphQL 編輯器：

1. 開啟 GraphQL API 項目 - 在 Fabric 中導航到你的工作區，並開啟 GraphQL 項目的 API。

2. 進入編輯器 - 在入口網站畫面左下角選擇 查詢 。

   

3. 撰寫你的查詢 —— 直接在查詢 標籤上輸入你的 GraphQL 查詢。使用 Intellisense 搭配鍵盤快捷鍵：

   • 視窗：CTRL + 空白
   • macOS：指令 + 空格

   

4. 執行查詢 - 選擇 執行 以執行查詢並從資料來源取得資料。

產生程式碼

API 編輯器會自動產生反映你目前在編輯器中測試的 GraphQL 查詢或變異的樣板 Python 或 Node.js 程式碼。 當你做原型並精煉查詢時，產生的程式碼會相應更新。 當你對結果感到滿意後，可以查看並複製產生的程式碼，在本地執行用於測試，或在應用程式開發過程中重複使用。

重要

產生的程式代碼會使用互動式瀏覽器認證，而且應該僅用於測試目的。 在生產過程中，請一律在 Microsoft Entra 中註冊應用程式，並使用適當的 client_id 和權限範圍。 您可以在連線應用程式找到具有範例程式碼的端對端範例。

開始之前：

1. 撰寫查詢 - 在查詢編輯器中輸入以下範例查詢（或您自己的查詢）：

   query {
     addresses(first: 5) {
        items {
           AddressID
           City
           StateProvince
           CountryRegion
        }  
     }
   }
   

2. 執行查詢 - 選擇 執行 以執行查詢並在編輯器中確認其運作正常後再繼續。

3. 生成程式碼 - 點選 生成程式碼 按鈕，然後選擇你偏好的程式語言（Python 或 JavaScript/Node.JS）：

   

4. 然後，您可以複製產生的程式代碼，並將其儲存為本機資料夾中的檔案。 根據所選語言，請依照以下快速步驟在當地進行測試：

Python

1. 建立一個名為 editor.py 檔案的檔案，然後貼上上面範例查詢產生的程式碼。

2. 執行命令 python -m venv .venv來建立虛擬環境。

3. venv通過運行.venv\Scripts\activate或source .venv/bin/activate激活 。

4. 執行 來 pip install azure-identity安裝所需的相依性。

5. 使用 python editor.py執行程式碼。

6. 系統會提示你透過瀏覽器視窗登入以驗證請求。

7. API 的回應會印在主控台上。

   {
   	"data": {
   		"addresses": {
   			"items": [
   				{
   					"AddressID": 9,
   					"City": "Bothell",
   					"StateProvince": "Washington",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 11,
   					"City": "Bothell",
   					"StateProvince": "Washington",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 25,
   					"City": "Dallas",
   					"StateProvince": "Texas",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 28,
   					"City": "Phoenix",
   					"StateProvince": "Arizona",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 32,
   					"City": "Montreal",
   					"StateProvince": "Quebec",
   					"CountryRegion": "Canada"
   				}
   			]
   		}
   	}
   }
   

Node.JS

1. 建立一個名為 editor.js 檔案的檔案，然後貼上上面範例查詢產生的程式碼。

2. 在與 editor.js相同的資料夾中，建立 package.json 一個包含以下內容的檔案：

   {
     "type": "module",
     "dependencies": {}
   }
   

3. 在你的開發機器上安裝 Node.js （包含 npm）。

4. 在您選擇的套件管理員中執行 npm install @azure/identity 或類似的命令，以安裝最新版本的身分識別程式庫。

5. 執行 node editor.js 程式碼。

6. 系統會提示你透過瀏覽器視窗登入以驗證請求。

7. API 的回應會印在主控台上。

   {
   	"data": {
   		"addresses": {
   			"items": [
   				{
   					"AddressID": 9,
   					"City": "Bothell",
   					"StateProvince": "Washington",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 11,
   					"City": "Bothell",
   					"StateProvince": "Washington",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 25,
   					"City": "Dallas",
   					"StateProvince": "Texas",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 28,
   					"City": "Phoenix",
   					"StateProvince": "Arizona",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 32,
   					"City": "Montreal",
   					"StateProvince": "Quebec",
   					"CountryRegion": "Canada"
   				}
   			]
   		}
   	}
   }
   

查詢和變動的開發

以下範例利用 AdventureWorks 範例資料示範 GraphQL 查詢與突變語法。 這些例子假設你使用的是支援寫入操作（變異）的 Fabric 資料倉儲。 透過 SQL Analytics 端點（如 Lakehouses 和鏡像資料庫）存取的資料來源是唯讀的，且只支援查詢，不支援變異。

請回顧這段來自 AdventureWorks 的 GraphQL 架構簡短摘錄。 它定義了 Product 一種型別，查詢用來讀取單一產品或列出所有產品，並有變異用來建立、更新或刪除產品，支援所有 CRUDL（建立、閱讀、更新、刪除、列出）的使用情境。

{
  type Product {
    ProductID: Int!
    Name: String!
    ProductNumber: String!
    Color: String
    ListPrice: Float!
    SellStartDate: DateTime!
  }

  type Query {
    products(first: Int, filter: ProductFilterInput): ProductConnection
    products_by_pk(ProductID: Int!): Product
  }

  type Mutation {
    createProduct(Name: String!, ProductNumber: String!, ListPrice: Float!, SellStartDate: DateTime!): Product
    updateProduct(ProductID: Int!, Name: String, Color: String, ListPrice: Float): Product
    deleteProduct(ProductID: Int!): Boolean
  }
}

使用結構描述中定義的任何查詢，讀取透過GraphQL公開的資料。 查詢會依其主鍵products_by_pk 取得單一產品。

query MyQuery {
  products_by_pk(ProductID: 680) {
    ProductID
    Name
    ProductNumber
    Color
    ListPrice
  }
}

回應：

{
  "data": {
    "products_by_pk": {
      "ProductID": 680,
      "Name": "HL Road Frame - Black, 58",
      "ProductNumber": "FR-R92B-58",
      "Color": "Black",
      "ListPrice": 1431.50
    }
  }
}

利用突變 createProduct 來寫入資料，並創造帶有所需參數的新產品。

mutation MyMutation {
  createProduct(
    Name: "Mountain Bike Helmet - Blue", 
    ProductNumber: "HE-M897-B", 
    ListPrice: 89.99,
    SellStartDate: "2025-01-01T00:00:00Z"
  ) {
    ProductID
    Name
    ProductNumber
    ListPrice
  }
}

回應：

{
  "data": {
    "createProduct": {
      "ProductID": 1001,
      "Name": "Mountain Bike Helmet - Blue",
      "ProductNumber": "HE-M897-B",
      "ListPrice": 89.99
    }
  }
}

查詢變數

使用 [查詢] 索引標籤右側的 [查詢變數] 窗格，將參數作為變數傳遞至查詢或變動。 變數的工作方式類似於其他程式語言中的變數。 每個變數都宣告了一個名稱，用於存取其中儲存的值。 用前面的突變範例，你稍微修改它以使用查詢變數。

mutation MyMutation ($name: String!, $productNumber: String!, $listPrice: Float!, $sellStartDate: DateTime!){
  createProduct(
    Name: $name, 
    ProductNumber: $productNumber, 
    ListPrice: $listPrice,
    SellStartDate: $sellStartDate
  ) {
    ProductID
    Name
    ProductNumber
    ListPrice
  }
}

請使用以下範例在 查詢變數 窗格中定義變數。

{
  "name": "Mountain Bike Helmet - Blue",
  "productNumber": "HE-M897-B",
  "listPrice": 89.99,
  "sellStartDate": "2025-01-01T00:00:00Z"
}

變數使突變程式碼更乾淨、更易於閱讀、測試和修改。 他們也讓只要改變變數就能簡單地重複使用同一突變但值不同的設定。

相關內容

• 更多查詢和變動範例
• 適用於 GraphQL 結構描述檢視和結構描述總管的 Fabric API