遮盖和隐藏数据

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

当您在 Apigee 中调试 API 调用时，相关内容有时可能包含必须遮盖的敏感数据，例如信用卡或个人健康信息 (PHI)。

Apigee 提供了遮盖或隐藏 Trace 和调试会话中的敏感数据的不同方式。

遮盖敏感数据

通过 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"

按照获取 OAuth 2.0 访问令牌中的说明，将 $TOKEN 设置为您的 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"
     ]
   }'

按照获取 OAuth 2.0 访问令牌中的说明，将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项，请参阅使用 curl。如需了解所使用的环境变量，请参阅为 Apigee API 请求设置环境变量。

遮盖命名空间范围的 XML

如果您要遮盖 XML 数据并且该数据使用 XML 命名空间，则遮盖配置必须使用 namespaces 元素引用这些命名空间。无论 XML 载荷使用的是默认命名空间还是命名空间前缀，情况都是如此。

例如，假设您要在请求载荷中遮盖员工姓名，并且 XML 不使用 XML 命名空间：

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

因此，调试遮盖配置不需要 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 元素。您可以选择调试遮盖配置中任何有效的命名空间前缀；调试遮盖配置中的命名空间前缀可能与 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>

则调试遮盖配置仍必须在与该默认命名空间对应的 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 政策中为请求和响应消息指定变量名称，然后在调试遮盖的 variables 部分中指定这些变量。例如，如果 ServiceCallout 政策使用：

  <ServiceCallout name='SC-1'>
    <Request variable='rbacRequest'>
      <Set>
        <Payload contentType='application/json'>{ ... }</Payload>
         ...
  

  则您应在调试遮盖配置的 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. 前缀的变量会以明文形式显示在跟踪和调试会话中，即使数据来自加密的数据存储区（例如键值对映射）也是如此。如果您想遮盖这些值，请使用遮盖。