參數存取控制 - API Gateway

參數存取控制外掛程式配置參考。

功能說明

param-access-control外掛程式實現了基於請求參數和上下文條件進行精確存取控制，可用於實現複雜的請求驗證和訪問管理情境。

運行屬性

外掛程式執行階段：鑒權階段。
外掛程式執行優先順序：310。

配置欄位

參數	資料類型	填寫要求	預設值	描述
parameters	object	必填	-	定義需要使用的參數，支援從Header、Query、Path中提取。
rules	array of rule	必填	-	定義判斷規則和處理邏輯。

`parameters`欄位配置說明

參數	格式	描述
Header	`Header:參數名`	從要求標頭提取參數。
Query	`Query:參數名`	從查詢參數提取參數。
Path	`Path:序號`	從路徑中提取第n段內容，序號從1開始。
Path	`Path`	擷取完整路徑。

`rules`欄位配置說明

參數	資料類型	填寫要求	預設值	描述
name	string	必填	-	規則名稱。
condition	string	必填	-	判斷條件。
ifTrue	string	選填	-	條件為真時的處理指示（ALLOW/DENY）。
ifFalse	string	選填	-	條件為假時的處理指示（ALLOW/DENY）。
statusCode	number	選填	403	DENY時返回的HTTP狀態代碼。
responseHeaders	object	選填	-	DENY時返回的回應標頭。
responseBody	string	選填	-	DENY時返回的響應體。

支援的運算子和函數

運算子/函數	描述	樣本
==	等於	`userType == 'admin'`
!=	不等於	`status != 'inactive'`
>	大於	`version > '2.0'`
>=	大於等於	`level >= '3'`
<	小於	`priority < '5'`
<=	小於等於	`quota <= '100'`
contains	包含子串	`path.contains('api')`
matches	正則匹配	`url.matches('*.jpg')`
startsWith	首碼匹配	`path.startsWith('/api')`
endsWith	尾碼匹配	`filename.endsWith('.jpg')`
&&	邏輯與	`userType == 'admin' && level >= '3'`
\|\|	邏輯或	`path.startsWith('/api') \\|\\| path.startsWith('/v2')`
!	邏輯非	`!(status == 'inactive')`

配置樣本

外掛程式通過配置規則（rules）來控制請求訪問，規則按照配置順序依次執行直到遇到ALLOW或DENY指令。每個規則必須至少配置ifTrue或ifFalse其中之一，建議為DENY操作設定明確的狀態代碼和響應資訊。以下樣本展示了常見的使用情境：

基於使用者身份的存取控制

parameters:
  userType: "Header:userType"
  userId: "Path:1"

rules:
  - name: admin-access
    condition: "userType == 'admin'"
    ifTrue: "ALLOW"
  - name: user-access
    condition: "userId == '123'"
    ifFalse: "DENY"
    statusCode: 403
    responseBody: "Access Denied"

根據該配置，滿足以下條件的請求將被允許：

# 管理員訪問任意路徑
curl http://example.com/any/path? -H "userType: admin"

# 使用者訪問自己的資源
curl http://example.com/123/profile

而以下請求將被拒絕：

# 使用者訪問他人資源
curl http://example.com/456/profile

基於API版本的存取控制

parameters:
  apiVersion: "Header:Api-Version"
  path: "Path"

rules:
  - name: version-check
    condition: "path.contains('/v2/') && apiVersion < '2.0'"
    ifTrue: "DENY"
    statusCode: 400
    responseHeaders:
      Content-Type: application/json
    responseBody: '{"error": "Please upgrade to API version 2.0 or above"}'