您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
在 Edge 中對 API 呼叫進行偵錯時,這些內容有時可能包含機密資料,例如需要遮蓋的信用卡或個人識別資訊 (PHI)。
Edge 提供以不同方式隱藏或遮蓋 Trace 和偵錯工作階段中的機密資料。
隱藏機密資料
您可以建立前置字串為「private.
」的自訂變數,防止機密資料出現在追蹤記錄工具和偵錯工作階段中。
舉例來說,使用鍵/值對應作業政策從已加密的鍵/值對應擷取值時,請按照下列格式設定變數名稱,確保這些值不會顯示在 Trace 或偵錯工作階段中:
<Get assignTo="private.hiddenData">
隱藏敏感變數是使用資料遮蓋的替代方案,如下所述。隱藏與遮蓋的差異在於,隱藏變數完全不會顯示,因此遮蓋的值會在 Trace 和偵錯工作階段中以星號取代。
即使變數沒有「private.
」前置字串,追蹤記錄和偵錯工作階段仍會以明文形式顯示,即使資料來自經過加密的資料儲存庫 (例如加密鍵/值對應關係)。如要遮蓋這些值,請使用下方的遮罩。
遮蓋機密資料
Edge 可讓您定義「遮罩設定」,以遮蓋追蹤及偵錯工作階段中的特定資料。遮蓋設定可在全域 (機構層級) 或本機 (API Proxy 層級) 進行。
資料遮蓋時,追蹤記錄輸出內容中的星號會取代資料。例如:
<description>**********</description>
使用遮罩設定
遮蓋設定可讓您識別下列來源中的機密資料:- XML 酬載:透過 XPath,您可以指定要從要求或回應訊息酬載中篩除的 XML 元素。
- JSON 酬載:使用 JSONPath 可讓您識別要從要求或回應訊息酬載中篩選的 JSON 屬性。
- 流程變數:您可以指定應在偵錯輸出中遮蓋的變數清單。指定
request.content
、response.content
或message.content
流程變數時,系統也會遮蓋要求/回應主體。
遮罩設定的基本結構以下列 XML 表示法顯示:
<MaskDataConfiguration name="default"> <Namespaces> <Namespace prefix="myco">http://example.com</Namespace> </Namespaces> <XPathsRequest> <XPathRequest>/myco:Greeting/myco:User</XPathRequest> </XPathsRequest> <XPathsResponse> <XPathResponse>/myco:Greeting/myco:User</XPathResponse> </XPathsResponse> <JSONPathsRequest> <JSONPathRequest>$.store.book[*].author</JSONPathRequest> </JSONPathsRequest> <JSONPathsResponse> <JSONPathResponse>$.store.book[*].author</JSONPathResponse> </JSONPathsResponse> <XPathsFault> <XPathFault>/myco:Greeting/myco:User</XPathFault> </XPathsFault> <JSONPathsFault> <JSONPathFault>$.store.book[*].author</JSONPathFault> </JSONPathsFault> <Variables> <Variable>request.header.user-agent</Variable> <Variable>request.formparam.password</Variable> </Variables> </MaskDataConfiguration>
設定遮罩設定資源
使用下列元素定義遮罩設定。
欄位名稱 | 說明 | 預設 | 必填與否 |
---|---|---|---|
XPathsRequest | 將在要求路徑中的 XML 酬載 (如果有的話) 評估的 XPath 運算式清單。成功解析的 XPath 都會導致 XML 元素的值遭到遮蓋。 | 不適用 | 否 |
XPathsResponse | 系統會根據回應路徑中的 XML 酬載 (如有) 評估 XPath 運算式。成功解析的 XPath 都會導致 XML 元素的值遭到遮蓋。 | 不適用 | 否 |
JSONPathsRequest | 系統會根據要求路徑中的 JSON 酬載 (如有) 評估 JSONPath 運算式清單。成功解析的 JSONPath 都會導致遮蓋 JSON 屬性的值。 | 不適用 | 否 |
JSONPathsResponse | 系統會根據回應路徑中的 JSON 酬載 (如有) 評估 JSONPath 運算式清單。成功解析的 JSONPath 都會導致遮蓋 JSON 屬性的值。 | 不適用 | 否 |
XPathsFault | 這個 XPath 運算式清單會在錯誤流程中的 XML 酬載 (如果有的話) 中評估,並在流程中的任何時間點擲回錯誤時執行此清單。成功解析的 XPath 都會導致 XML 元素的值遭到遮蓋。 | 不適用 | 否 |
JSONPathsFault | JSON 運算式清單。這個清單會在錯誤流程中的 JSON 酬載 (如果有的話) 中評估,會在流程中的任何時間點擲回錯誤時執行此清單。成功解析的 JSONPath 都會導致遮蓋 JSON 屬性的值。 | 不適用 | 否 |
Variables |
系統會遮蔽內含值的變數 (預先定義或自訂) 清單。如需預設變數的清單,請參閱變數參考資料。 |
不適用 | 否 |
Mask 設定 API
遮蓋設定會定義為使用符合 REST 樣式的管理 API 上傳及下載的 XML 或 JSON 格式檔案。如需資料遮蓋 API 的完整清單,請參閱資料遮罩。
如要查看現有的遮罩設定,您可以只呼叫機構中的 API 資源 /maskconfigs
:
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/maskconfigs \ -u email
這個範例顯示的是驗證的 Basic 語法。您可以使用其他類型的驗證方式,例如 Oauth2 或 SAML。
如要查看針對特定 API Proxy 定義的遮罩設定,您可以呼叫 /maskconfigs
API:
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/maskconfigs \ -u email
如要查看特定遮罩設定,請指定遮罩名稱:
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/maskconfigs/default \ -u email
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/maskconfigs/default \ -u email
如要建立遮罩設定,請使用 POST 動詞提交定義遮罩設定的酬載:
$ curl -H "Content-type:text/xml" -X POST -d \ '<MaskDataConfiguration name="default"> <Namespaces> <Namespace prefix="myco">http://example.com</Namespace> </Namespaces> <XPathsRequest> <XPathRequest>/myco:Greeting/myco:User</XPathRequest> </XPathsRequest> <XPathsResponse> <XPathResponse>/myco:Greeting/myco:User</XPathResponse> </XPathsResponse> <JSONPathsRequest> <JSONPathRequest>$.store.book[*].author</JSONPathRequest> </JSONPathsRequest> <JSONPathsResponse> <JSONPathResponse>$.store.book[*].author</JSONPathResponse> </JSONPathsResponse> <XPathsFault> <XPathFault>/myco:Greeting/myco:User</XPathFault> </XPathsFault> <JSONPathsFault> <JSONPathFault>$.store.book[*].author</JSONPathFault> </JSONPathsFault> <Variables> <Variable>request.header.user-agent</Variable> <Variable>request.formparam.password</Variable> </Variables> </MaskDataConfiguration>' \ https://api.enterprise.apigee.com/v1/o/{org_name}/maskconfigs \ -u email如何建立範圍限定於特定 API Proxy 的遮罩設定:
$ curl -H "Content-type:text/xml" -X POST -d \ '<MaskDataConfiguration name="default"> <Namespaces> <Namespace prefix="myco">http://example.com</Namespace> </Namespaces> <XPathsRequest> <XPathRequest>/myco:Greeting/myco:User</XPathRequest> </XPathsRequest> <XPathsResponse> <XPathResponse>/myco:Greeting/myco:User</XPathResponse> </XPathsResponse> <JSONPathsRequest> <JSONPathRequest>$.store.book[*].author</JSONPathRequest> </JSONPathsRequest> <JSONPathsResponse> <JSONPathResponse>$.store.book[*].author</JSONPathResponse> </JSONPathsResponse> <XPathsFault> <XPathFault>/myco:Greeting/myco:User</XPathFault> </XPathsFault> <JSONPathsFault> <JSONPathFault>$.store.book[*].author</JSONPathFault> </JSONPathsFault> <Variables> <Variable>request.header.user-agent</Variable> <Variable>request.formparam.password</Variable> </Variables> </MaskDataConfiguration>' \ https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/maskconfigs \ -u email
您可以使用 DELETE 動詞刪除遮罩設定:
$ curl -X DELETE \ https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/maskconfigs/{maskconfig_name} \ -u email
這個範例顯示的是驗證的 Basic 語法。您可以使用其他類型的驗證方式,例如 Oauth2 或 SAML。
DELETE 作業的回應是不含訊息內容的 HTTP 代碼 204
。
XML 命名空間的遮蓋功能
除非 XML 酬載中已定義命名空間,否則遮罩設定不需要 XPATH 定義中的 <Namespace>
元素。如果 XML 酬載使用預設命名空間,也會發生上述情況。
例如,XML 酬載並未定義命名空間:
<employee> <name>abc</name> <age>50</age> </employee>
因此,遮罩設定不需要 <Namespace>
元素:
<MaskDataConfiguration> <XPathsRequest> <XPathRequest>/employee/name</XPathRequest> <XPathsRequest> </MaskDataConfiguration>
如果 XML 酬載包含命名空間和前置字串:
<myco:employee xmlns:myco="http://example.com"> <myco:name>xyz</myco:name> <myco:age>50</myco:age> </myco:employee>
遮蓋設定定義應包含 <Namespace>
元素:
<MaskDataConfiguration> <Namespaces> <Namespace prefix="myco">http://example.com</Namespace> </Namespaces> <XPathsRequest> <XPathRequest>/myco:employee/myco:name</XPathRequest> <XPathsRequest> </MaskDataConfiguration>
如果 XML 酬載有命名空間但沒有前置字元,表示預設命名空間:
<employee xmlns="http://example.com"> <name>xyz</name> <age>50</age> </employee>
則遮罩設定仍應包含 <Namespace>
元素:
<MaskDataConfiguration> <Namespaces> <Namespace prefix="myco">http://example.com</Namespace> </Namespaces> <XPathsRequest> <XPathRequest>/myco:employee/myco:name</XPathRequest> <XPathsRequest> </MaskDataConfiguration>