共用方式為

驗證 GraphQL 要求

  • 發行項

適用於：所有 APIM 層

validate-graphql-request 原則會驗證 GraphQL 要求，並授權 GraphQL API 中特定查詢路徑的存取權。 不正確查詢是「要求錯誤」。 授權只針對有效要求。

注意

請依照原則陳述式中提供的順序，來設定原則的元素和子元素。 深入了解如何設定或編輯 APIM 原則。

原則陳述式

<validate-graphql-request error-variable-name="variable name" max-size="size in bytes" max-depth="query depth">
    <authorize>
        <rule path="query path, for example: '/listUsers' or '/__*'" action="string or policy expression that evaluates to 'allow | remove | reject | ignore'" />
    </authorize>
</validate-graphql-request>

屬性

屬性 描述 是必要欄位 預設
error-variable-name 要記錄驗證錯誤的 context.Variables 中變數名稱。 允許使用原則運算式。 No N/A
max-size 要求承載的大小上限，以位元組為單位。 允許上限值：102,400 個位元組 (100 KB)。 (如果您需要提高此限制，請連絡支援服務。)允許使用原則運算式。 Yes N/A
max-depth 整數。 查詢深度上限。 允許使用原則運算式。 No 6

元素

名稱 描述 必要
授權 新增此元素以設定一或多個路徑的適當授權規則。 No
rule 新增一或多個這些元素，以授權特定的查詢路徑。 每個規則都可以選擇性地指定不同的動作。 可以使用原則運算式有條件地指定。 No

規則屬性

屬性 描述 是必要欄位 預設
path 要在其上方執行授權驗證的路徑。 其必須遵循模式：/type/field。 Yes N/A
action 規則適用時要執行的動作。 可以使用原則運算式有條件地指定。 No allow

自我檢查系統

path=/__* 的原則是 自我檢查系統。 您可以用來拒絕自我檢查要求 (__schema、__type 等)。

要求動作

下表說明可用動作。

動作 描述
reject 發生要求錯誤，且要求未傳送至後端。 未套用設定下的其他規則。
remove 發生欄位錯誤，且欄位已從要求中移除。
allow 欄位會傳遞至後端。
略過 規則不適用於此案例，且會套用下一個規則。

使用方式

使用注意事項

  • 針對已匯入至 API 管理之 pass-through 或 synthetic GraphQL API 設定原則。

  • 此原則只能在原則區段中使用一次。

  • 因為 GraphQL 查詢使用扁平化結構描述，因此權限可能會套用至輸出類型的任何分葉節點：

    • 變動、查詢或訂閱
    • 類型宣告中的個別欄位

    權限可能無法套用於：

    • 輸入類型
    • 片段
    • 等位
    • 介面
    • 結構描述元素

  • 此原則可以驗證 GraphQL 要求，並跨所有層級最多 250 個查詢欄位。

錯誤處理

無法根據 GraphQL 結構描述驗證，或要求的大小或深度失敗，為要求錯誤，這會導致要求失敗，且出現錯誤區塊 (但沒有資料區塊)。

與 Context.LastError 屬性類似，所有 GraphQL 驗證錯誤都會在 GraphQLErrors 變數中自動傳播。 如果需要個別傳播錯誤，您可以指定錯誤變數名稱。 錯誤會推送至 error 變數和 GraphQLErrors 變數。

範例

查詢驗證

此範例會將下列驗證和授權規則套用至 GraphQL 查詢：

  • 系統會拒絕大於 100 kb 或查詢深度大於 4 的要求。
  • 系統會拒絕針對自我檢查系統的要求。
  • 系統會從包含兩個以上標頭的要求中移除 /Missions/name 欄位。
<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4"> 
    <authorize>
        <rule path="/__*" action="reject" /> 
        <rule path="/Missions/name" action="@(context.Request.Headers.Count > 2 ? "remove" : "allow")" />
    </authorize>
</validate-graphql-request>

變動驗證

此範例會將下列驗證和授權規則套用至 GraphQL 變動：

  • 系統會拒絕大於 100 kb 或查詢深度大於 4 的要求。
  • 除非要求來自 IP 位址 198.51.100.1，否則會拒絕變動 deleteUser 欄位的要求。
<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4"> 
    <authorize>
        <rule path="/Mutation/deleteUser" action="@(context.Request.IpAddress <> "198.51.100.1" ? "deny" : "allow")" />
    </authorize>
</validate-graphql-request>

相關內容

如需使用原則的詳細資訊，請參閱：