資料遮蓋及隱藏

您正在查看 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.contentresponse.contentmessage.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 語法。您可以使用其他類型的驗證方式,例如 Oauth2SAML

如要查看針對特定 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 語法。您可以使用其他類型的驗證方式,例如 Oauth2SAML

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>