注意:此产品的某些方面处于 Beta 版阶段。Hybrid 安装选项是 GA。要加入 Beta 版计划,请与您的 Apigee 代表联系。

遮盖和隐藏数据

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

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

遮盖敏感数据

通过 Apigee,您可以定义遮盖配置,以在跟踪和调试会话中遮盖特定数据。遮盖数据后,这些数据会在跟踪记录输出中被替换为星号。例如:

<description>**********</description>

遮盖配置是您在环境级别定义的单例资源。默认情况下不使用数据遮盖。

遮盖配置的结构

遮盖配置是 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-agent",
    "request.formparam.password"
  ]
}

使用 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/{debugmask}

您可以选择传递以下查询参数:

  • 设置 updateMask 查询参数以指定一个字段掩码,其中包含调试掩码中字段的完全限定名称的逗号分隔列表。例如:"requestJSONPaths"
  • 设置 replaceRepeatedFields 查询参数以指定在更新时是否替换调试掩码中的现有值。默认情况下,系统会附加值 (false)

例如:

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

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

遮盖 XML 命名空间

遮盖配置在 XPATH 定义中不需要 <Namespace> 元素,除非在 XML 载荷中定义了命名空间。如果 XML 载荷使用了默认命名空间也是如此。

例如,XML 载荷不定义命名空间:

<employee>
    <name>abc</name>
    <age>50</age>
</employee>

因此,遮盖配置不需要 <Namespace> 元素:

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

如果 XML 载荷包含命名空间和前缀:

<employee xmlns:myco="http://example.com">
    <myco:name>xyz</myco:name>
    <myco:age>50</myco:age>
</myco:employee>

则遮盖配置定义应包含 <Namespace> 元素:

{
  "namespaces": {
    "myco": "http://example.com"
  },
  "requestXPaths": [
    "/myco:employee/myco:name"
  ]
}

如果 XML 载荷具有命名空间,但没有前缀,即使用默认命名空间:

<employee xmlns="http://example.com">
    <name>xyz</name>
    <age>50</age>
</employee>

则遮盖配置仍应包含 <Namespace> 元素:

{
  "namespaces": {
    "myco": "http://example.com"
  },
  "requestXPaths": [
    "/myco:employee/myco:name"
  ]
}

隐藏敏感数据

您可以创建前缀为“private.”的自定义变量,以防止敏感数据显示在 Trace 工具和调试会话中。

例如,在使用键值映射操作政策从已加密的键值映射中检索值时,请将变量名称设置为如下格式,以确保这些值不显示在跟踪或调试会话中:

<Get assignTo="private.hiddenData">

隐藏敏感变量是数据遮盖的一个替代方法,详见下文。隐藏和遮盖之间的区别在于,在跟踪和调试会话中,被隐藏的变量完全不显示,而被遮盖的值将替换为星号。

在跟踪和调试会话中,没有“private.”前缀的变量会以明文形式显示,即使数据来自加密的数据存储区(例如加密的键值映射)也是如此。如果您想遮盖这些值,请使用遮盖(下文)。