遮盖和隐藏数据

本页面适用于 ApigeeApigee 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.contentresponse.contentmessage.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 配置元素,您可以遮盖 requestresponsefault 消息中显示的数据。但是,完整的消息内容也可以通过调试会话捕获。您可能还需要在 variables 部分中配置 request.contentresponse.content,以防止显示敏感数据。

  • 如果您使用 ServiceCallout 政策发出请求,则系统不会使用 requestXPathsresponseJSONPaths 等配置元素遮盖该标注的请求和响应中的信息。如果您要遮盖该数据,则应在 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. 前缀的变量会以明文形式显示在跟踪和调试会话中,即使数据来自加密的数据存储区(例如键值对映射)也是如此。如果您想遮盖这些值,请使用遮盖。