本頁面由 Cloud Translation API 翻譯而成。

遮蓋及隱藏資料

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

在 Apigee 中偵錯 API 呼叫時，內容有時可能包含機密資料，例如信用卡或個人識別健康資訊 (PHI)，必須遮蓋。

Apigee 提供多種方法，可從偵錯工作階段遮蓋或隱藏機密資料。如果您在偵錯工作階段中收集資料時使用遮蓋功能，Apigee 會在閘道節點中執行遮蓋作業，然後再將偵錯工作階段資料傳輸至控制平面。

遮蓋機密資料

Apigee 可讓您定義遮蓋設定，遮蓋追蹤和偵錯工作階段中的特定資料。資料經過遮蓋後，追蹤輸出內容會以星號取代資料。您可以遮蓋機密資料，並保留非機密資料。例如：

<ServiceRequest>
  <request-id>B540A938-F551</request-id>
  <customer-name>**********</customer-name>
</ServiceRequest>

遮罩設定是您在環境層級定義的單例資源。根據預設，系統不會遮蓋任何資料。

資料遮蓋僅適用於 API 代理項的偵錯工作階段中擷取的資料。資料遮罩不會影響傳送至目標或用戶端應用程式的資料。變更資料遮蓋設定後，您必須啟動新的偵錯工作階段，才能查看變更效果。

遮罩設定的結構

遮蓋設定是 JSON 格式的檔案，可協助您識別下列來源中的私密資料：

XML 酬載：使用 XPath 識別要從要求或回應訊息酬載中篩除的 XML 元素。
JSON 酬載：使用 JSONPath 從要求或回應訊息酬載中識別要篩除的 JSON 屬性。
流程變數：您可以指定要在偵錯輸出內容中遮蓋的變數清單。指定 request.content、response.content 或 message.content 流程變數時，要求/回應主體也會遭到遮蓋。

以下提供 JSON 格式的遮罩設定基本結構範例。如要進一步瞭解範例中顯示的遮罩設定欄位，請參閱「DebugMask」。

{
  "namespaces": {
    "myco": "http://example.com"
  },
  "requestXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "responseXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "faultXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "requestJSONPaths": [
    "$.store.book[*].author"
  ],
  "responseJSONPaths": [
    "$.store.book[*].author"
  ],
  "faultJSONPaths": [
    "$.store.book[*].author"
  ],
  "variables": [
    "request.header.user-name",
    "request.formparam.password",
    "myCustomVariable"
  ]
}

使用 API 查看環境中的遮蓋設定

如要在環境中查看遮蓋設定，請對下列資源發出 GET 要求：

/organizations/{org}/environments/{env}/debugmask

例如：

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/debugmask" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一文所述。如要瞭解本範例使用的 curl 選項，請參閱「使用 curl」。如要瞭解可使用的環境變數，請參閱為 Apigee API 要求設定環境變數。

以下是回應範例：

{
  "name": "organizations/myorg/environments/test/debugmask"
  "namespaces": {
    "myco": "http://example.com"
  },
  "requestXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "responseXPaths": [
    "/myco:Greeting/myco:User"
  ]
}

使用 API 更新環境中的遮罩設定

如要在環境中更新遮罩設定單例項資源，請對下列資源發出 PATCH：

/organizations/{org}/environments/{env}/debugmask

您也可以傳遞下列查詢參數：

設定 updateMask 查詢參數，指定包含以半形逗號分隔的完整欄位名稱清單的欄位遮罩。例如："requestJSONPaths"
設定 replaceRepeatedFields 查詢參數，指定更新時是否要取代偵錯遮罩中的現有值。根據預設，系統會附加值 (false)

例如：

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/debugmask" \
  -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: application/json" \
  -d \
  '{
     "namespaces": {
       "ns1": "http://example.com"
     },
     "requestXPaths": [
       "/ns1:employee/ns1:name"
     ]
   }'

遮蓋命名空間範圍內的 XML

如要遮蓋 XML 資料，且該資料使用 XML 命名空間，遮蓋設定必須使用 namespaces 元素參照這些命名空間。無論 XML 酬載使用預設命名空間或命名空間前置字元，都是如此。

舉例來說，假設您想遮蓋要求酬載中的員工姓名，且 XML 未使用 XML 命名空間：

<employee>
  <name>Shanmu Tharman</name>
  <age>50</age>
</employee>

因此，debugmask 設定不需要 namespaces 元素：

{
  "requestXPaths": [
    "/employee/name"
  ]
}

如果 XML 酬載使用帶有前置字元的命名空間：

<cym:employee xmlns:cym="http://cymbalgroup.com" xmlns:id="http://cymbalgroup.com/identity">
  <id:name>Shanmu Tharman</id:name>
  <id:age>50</id:age>
</cym:employee>

遮罩設定應包含 namespaces 元素。您可以在 debugmask 設定中選擇任何有效的命名空間前置字元；debugmask 設定中的命名空間前置字元可以與 XML 中使用的命名空間前置字元相同，但並非必要。

{
  "namespaces": {
    "cym": "http://cymbalgroup.com",
    "idns": "http://cymbalgroup.com/identity"
  },
  "requestXPaths": [
    "/cym:employee/idns:name"
  ]
}

如果 XML 酬載使用沒有前置字元的命名空間 (即預設命名空間)：

<employee xmlns="http://cymbalgroup.com" xmlns:id="http://cymbalgroup.com/identity">
  <id:name>Shanmu Tharman</id:name>
  <id:age>50</id:age>
</employee>

那麼 debugmask 設定仍須在對應預設命名空間的 namespaces 元素中定義前置字元。你可以使用任何不重複的前置字元。

{
  "namespaces": {
    "p1": "http://cymbalgroup.com",
    "id": "http://cymbalgroup.com/identity"
  },
  "requestXPaths": [
    "/p1:employee/id:name"
  ]
}

其他設定注意事項

您可以使用 *XPaths 和 *JSONPaths 設定元素，遮蓋 request、response 或 fault 訊息中顯示的資料。但偵錯工作階段也可能會擷取完整訊息內容。您也可以在 variables 區段中設定 request.content 或 response.content，避免顯示私密/機密資料。
如果您使用 ServiceCallout 政策提出要求，該呼叫的要求和回應中的資訊不會使用 requestXPaths 或 responseJSONPaths 等設定元素遮蓋。如要遮蓋該資料，請在 ServiceCallout 政策中為要求和回應訊息指定變數名稱，然後在 debugmask 的 variables 區段中指定這些變數。舉例來說，如果您的 ServiceCallout 政策使用：
```
<ServiceCallout name='SC-1'>
  <Request variable='rbacRequest'>
    <Set>
      <Payload contentType='application/json'>{ ... }</Payload>
       ...
```
然後，您應在 debugmask 設定的 variables 元素中加入 rbacRequest.content。
```
{
  ...
  "variables": [
    "request.content",
    "response.content",
    "rbacRequest.content"
  ]
}
```

隱藏機密資料

除了遮蓋之外，您也可以為自訂變數選擇以 private. 開頭的名稱，防止敏感資料顯示在追蹤工具和偵錯工作階段中。

舉例來說，使用「鍵」值對應作業政策從鍵值對應擷取值時，您可以選擇下列變數名稱，確保值不會顯示在追蹤或偵錯工作階段中：

<KeyValueMapOperations name='KVM-Get-1'>
    <Scope>environment</Scope>
    <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
    <MapName>settings</MapName>
    <Get assignTo='private.privatekey'>
      <Key>
        <Parameter>rsa_private_key</Parameter>
      </Key>
    </Get>
  </KeyValueMapOperations>

即使資料來自加密資料儲存庫 (例如鍵值對應)，沒有 private. 前置字元的變數也會在追蹤和偵錯工作階段中以明文顯示。如要遮蓋這些值，請使用遮蓋功能。

遮蓋及隱藏資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。