遮蓋及隱藏資料

本頁適用於 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"
     ]
   }'

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

遮蓋命名空間範圍的 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 name='SC-1'>
  <Request variable='rbacRequest'>
    <Set>
      <Payload contentType='application/json'>{ ... }</Payload>
       ...

    接著，您應在 variables 元素中加入 rbacRequest.content，以便進行 debugmask 設定。

    {
  ...
  "variables": [
    "request.content",
    "response.content",
    "rbacRequest.content"
  ]
}

隱藏機密資料

除了遮罩之外，您還可以為自訂變數選擇開頭為 private. 的名稱，這樣一來，即使在追蹤工具和偵錯工作階段中，也不會顯示敏感資料。

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

<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. 前置字串，在追蹤和偵錯工作階段中仍會以明文顯示。如要遮蓋這些值，請使用遮罩功能。