整合 Azure API 管理（APIM）與適用於 GraphQL 的網狀架構 API

將 Azure API 管理（APIM）整合至 Microsoft Fabric 的 GraphQL API 功能，能大幅提升 API 的功能，提供強大的擴展性與安全性功能。 APIM 作為企業級閘道器，新增了先進功能，包括身份管理、速率限制、回應快取、威脅防護及集中監控——且無需修改 Fabric API 設定。

透過 APIM 路由 GraphQL 請求，您可以擴展以處理增加的流量、實施複雜的安全政策，並掌握組織內的 API 使用模式。

本文將引導你如何將 APIM 與 GraphQL 的 Fabric API 整合、配置受管理身份驗證，以及實作快取與速率限制政策。

誰會使用 Azure API Management 搭配 GraphQL

APIM 整合的價值在於：

企業架構師 透過集中式且受管控的 API 閘道，公開 Fabric 資料，讓全組織存取
Fabric 管理員 實施速率限制、緩存和安全策略以保護 Fabric 容量和資料
IT 安全團隊需要先進的認證、授權及威脅防護以存取 Fabric 資料
由平台團隊管理與監督橫跨不同部門及事業單位的多個 Fabric GraphQL API

當您需要企業級 API 管理功能，例如速率限制、快取、安全策略及集中治理來管理您的 Fabric GraphQL APIs 時，請使用 APIM 整合。

先決條件

在開始之前，請確保您擁有：

已經為 GraphQL 建立了一個 Fabric API。如果沒有，請參考建立 GraphQL API 或在 GraphQL API 管理平台中使用 Start with sample SQL 資料庫
Azure API 管理執行個體。關於設定說明，請參閱建立 API 管理實例
建立受管理身份及設定 APIM 政策的權限

將 Fabric GraphQL API 新增至 Azure API 管理

將 APIM 與 Fabric 整合的第一步是將你的 GraphQL API 匯入 Azure API 管理。這個過程會建立一個代理，透過 APIM 路由請求，同時維持與 Fabric 資料來源的連線。透過匯入 API，你為加入企業級功能奠定基礎，如驗證政策、快取和速率限制。

匯入過程需要從 Fabric GraphQL API 取得兩項資訊：端點 URL（APIM 發送請求的地方）和結構檔案（定義 API 結構與可用操作）。

匯出你的 GraphQL API 細節

首先，從你的 Fabric GraphQL API 收集所需資訊：

在 Fabric 入口網站開啟你的 GraphQL API
在功能區中，選擇 複製端點 以取得你的 API URL
選擇 匯出結構 以下載GraphQL結構檔到你的本機裝置

將 API 匯入 APIM

當你的端點 URL 和結構檔案準備好後，你現在可以在 APIM 中註冊 GraphQL API。這會建立一個 API 定義，API 用來驗證請求、產生文件並套用政策。你上傳的結構定義了客戶端可以執行哪些查詢和變異。

在 Azure 入口中導覽至您的 API Management 實例
選擇 APIS>+ 新增 API
選擇 GraphQL 圖示
在 「從 GraphQL 建立結構 」畫面中，請提供：
- 顯示名稱：API 的友善名稱
- 名稱：API 識別碼
- GraphQL API 端點：你從 Fabric 複製的端點 URL
選擇 上傳 schema ，然後選擇你下載的 schema 檔案

設定管理身份驗證

現在你的 GraphQL API 已經在 APIM 註冊，你需要設定 APIM 如何與 Fabric 進行認證。受管理身份提供一種安全且無需密碼的認證方法，免除在 APIM 設定中儲存憑證的需求。 Azure 自動管理身份生命週期並處理憑證取得，使此方法比傳統認證方式更安全且易於維護。

認證設定包含三個主要步驟：在 Azure 中建立受管理身份、授權其存取 Fabric 工作空間和資料來源，以及設定 APIM 在向 Fabric 請求時使用此身份。

建立並指派一個受管理身份

首先，建立 APIM 用來驗證的受管理身份：

在 Azure 入口網站建立一個由使用者指派的管理身份。
請注意受管理身份的 客戶端 ID ——你需要客戶端 ID 來設定政策。

在 Fabric 中授予受管理身份權限

建立受管理身份後，你必須授權它存取你的 Fabric 資源。受管理身份需要同時存取 GraphQL API 項目本身及其連接的任何資料來源（如湖屋或倉庫）。將身份加入工作區成員是最簡單的方法，因為它能同時取得工作區中所有項目的存取權。

打開包含你 GraphQL API 的 Fabric 工作區
選擇 管理存取權
新增管理身份（例如 apim-id），至少要有 貢獻者 角色

小提示

若想更細緻地控制，你可以直接授予個別 Fabric 項目（API 及其資料來源）權限，而非工作區層級的存取權限。如果你的 API 使用單一登入（SSO）驗證，細緻的控制尤其重要。欲了解更多資訊，請參閱認證與權限摘要。

設定 APIM 以使用受管理身份

在 Fabric 中獲得權限後，你需要告訴 APIM 要使用哪個受管理身份。這種關聯讓 APIM 在向你的 Fabric GraphQL API 提出請求時，能以該身份進行認證。

在 Azure 入口網站中，導覽到你的 APIM 實例
前往安全>管理身份
新增你之前建立的使用者指派管理身份

新增認證政策

最後一個認證步驟是新增一個 APIM 政策，利用受管理身份取得存取權杖，並將其納入對 Fabric 的請求中。此政策在每次請求時自動執行，負責處理代幣的取得與續約。政策會利用該 authentication-managed-identity 元素取得 Fabric API 資源的權杖，然後將其加入授權標頭。

在你的 APIM 中的 GraphQL API 中，選擇 API 政策 標籤
編輯入站處理策略

在下方 <inbound><base/>新增以下 XML 檔：

<authentication-managed-identity 
    resource="https://analysis.windows.net/powerbi/api" 
    client-id="YOUR-MANAGED-IDENTITY-CLIENT-ID" 
    output-token-variable-name="token-variable" 
    ignore-error="false" />
<set-header name="Authorization" exists-action="override">
    <value>@("Bearer " + (string)context.Variables["token-variable"])</value>
</set-header>

將 YOUR-MANAGED-IDENTITY-CLIENT-ID 替換為您管理身份的客戶端 ID
儲存政策

測試連線

在加入快取和速率限制之前，先確認認證設定是否正確。現在的測試確保你之後遇到的問題不是因為認證設定。

在 APIM 中，導航到你的 GraphQL API
前往測試分頁
執行範例查詢或變異以確認連線是否正常

配置回應快取

回應快取大幅降低 API 呼叫者的延遲，並降低 Fabric 資料來源的後端負擔。 APIM 支援內建快取或外部 Redis 實例。對於 GraphQL API，快取使用請求主體（GraphQL 查詢）作為快取鍵，確保相同的查詢回傳快取回應。

快取 GraphQL 回應的好處：

延遲降低：快取回應可立即返回，無需查詢 Fabric
降低容量消耗：對 Fabric 的請求減少，因而降低了 CU（容量單元）用量。
更好的可擴展性：能同時處理更多同時使用者，同時不增加後端負載

新增快取政策

要實作快取，你要修改現有的認證政策，加入快取查找和儲存邏輯。該政策會在將請求轉發至 Fabric 前檢查快取回應，並儲存成功的回應以供未來使用。以下完整政策範例展示了驗證與快取如何協同運作：

<policies>
    <inbound>
        <base />
        <!-- Authenticate with managed identity -->
        <authentication-managed-identity 
            resource="https://analysis.windows.net/powerbi/api" 
            client-id="YOUR-MANAGED-IDENTITY-CLIENT-ID" 
            output-token-variable-name="token-variable" 
            ignore-error="false" />
        <set-header name="Authorization" exists-action="override">
            <value>@("Bearer " + (string)context.Variables["token-variable"])</value>
        </set-header>
        <!-- Check if response is cached -->
        <cache-lookup-value 
            key="@(context.Request.Body.As<String>(preserveContent: true))" 
            variable-name="cachedResponse" 
            default-value="not_exists" />
    </inbound>
    <backend>
        <!-- Only forward request if not cached -->
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<string>("cachedResponse") == "not_exists")">
                <forward-request />
            </when>
        </choose>
    </backend>
    <outbound>
        <base />
        <choose>
            <!-- Return cached response if it exists -->
            <when condition="@(context.Variables.GetValueOrDefault<string>("cachedResponse") != "not_exists")">
                <set-body>@(context.Variables.GetValueOrDefault<string>("cachedResponse"))</set-body>
            </when>
            <!-- Cache successful responses for 60 seconds -->
            <when condition="@((context.Response.StatusCode == 200) && (context.Variables.GetValueOrDefault<string>("cachedResponse") == "not_exists"))">
                <cache-store-value 
                    key="@(context.Request.Body.As<String>(preserveContent: true))" 
                    value="@(context.Response.Body.As<string>(preserveContent: true))" 
                    duration="60" />
            </when>
        </choose>
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

此政策運作方式：

入站：先透過管理身份進行驗證，然後根據 GraphQL 查詢檢查回應是否被快取
後端：若已有快取回應，則跳過將請求轉發至 Fabric
輸出：回傳快取的回應或在 60 秒鐘內快取新的成功回應。

確認快取是否有效

為了確認請求是否被快取：

在 APIM 中，執行同一個 GraphQL 查詢兩次
追蹤 API 呼叫以查看快取命中率

優化快取持續時間

範例使用了 60 秒的快取持續時間。根據你的資料新鮮度要求調整時間：

高頻更新：對於頻繁變動的資料，請使用較短的時長（10-30 秒）
靜態或參考資料：對於變動不頻繁的資料，請使用較長的時長（5-60 分鐘）
即時需求：不要快取必須總是回傳最新資料的查詢

關於進階快取情境，包括快取失效化及外部 Redis 設定，請參見 APIM 快取政策。

速率限制

您可以限制用戶端在特定時段內可以進行的 API 呼叫數目。這裡有一個限制速率的政策範例，你可以在下方 <inbound><base/> 補充，該條目規定每位使用者每 60 秒最多只能通話兩次：

<rate-limit-by-key 
    calls="2" 
    renewal-period="60" 
    counter-key="@(context.Request.Headers.GetValueOrDefault("Authorization"))" 
    increment-condition="@(context.Response.StatusCode == 200)" 
    remaining-calls-variable-name="remainingCallsPerUser" />

在一分鐘內發送超過兩次 API 呼叫後，您將收到錯誤訊息：

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in 58 seconds."
}

欲了解更多如何在 APIM 中設定速率限制政策的資訊，請參閱文件。

最佳做法

在將 APIM 與 Fabric API for GraphQL 整合時，請遵循以下建議：

安全性

使用受管理身份：優先使用受管理身份，而非 API 金鑰或連線字串來進行認證
實作最小權限：只授予受管理身份所需的最低權限
僅啟用 HTTPS：設定 APIM 拒絕 HTTP 請求並強制執行 HTTPS。
驗證輸入：使用 APIM 政策驗證 GraphQL 查詢，然後再轉發給 Fabric

Performance

快取頻繁存取的資料：識別常見查詢並設定適當的快取時長
監控快取命中率：利用 APIM 分析追蹤快取效能
優化速率限制：平衡使用者體驗與容量保護
使用區域部署：在與 Fabric 容量相同的區域部署 APIM

監控和治理

啟用診斷：設定 APIM 診斷日誌以追蹤 API 使用情況
設定警示：建立速率限制違規與錯誤警示
為 API 提供版本：使用 APIM 版本管理來管理任何破壞性的變更
記錄你的 API：使用 APIM 的開發者入口網站提供 API 文件

成本優化

適當規模的費率限制：設定與你的容量等級相符的限制
監控容量消耗：追蹤 APIM 與 Fabric 容量使用情況
策略性地使用快取：平衡資料更新需求與容量的節省
檢視使用模式：定期分析哪些查詢消耗最多資源

總結

將 Microsoft Fabric API for GraphQL 與 Azure API 管理整合，結合 Fabric 強大的資料能力與 APIM 的企業級 API 閘道功能。此組合可獲得：

強化安全性：管理式身份驗證、威脅防護及基於政策的存取控制
提升可擴展性：響應快取、速率限制，以及跨多後端的負載分配
更佳的效能：透過快取降低延遲並優化請求路由
集中式治理：跨多個 API 進行統一監控、版本管理
成本控制：速率限制與快取可降低架構容量消耗

透過遵循本文中的配置步驟與最佳實務，您可以建立一個穩健、安全且可擴展的 API 層，支援整個組織的生產工作負載。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-20