Shadow API Discovery 概览

概览

Apigee Shadow API Discovery 可在您现有的云基础架构中查找影子 API（即未记录的 API）。影子 API 会给您的系统带来安全风险，因为它们可能不安全、不受监控及不受维护。

使用 Shadow API Discovery 不会显著影响或减慢运行时流量。

本页面中有关设置和查看 API 观察结果的说明基于 Cloud 控制台中的 Apigee 界面。您还可以使用 Apigee Management (APIM) API 来管理 Shadow API Discovery。请参阅 Shadow API Discovery Management API。

启用 Shadow API Discovery

Shadow API Discovery 是 Apigee Advanced API Security 插件的一部分。对于 Shadow API Discovery，该插件的适用性特定于每个组织。订阅客户在 Apigee 组织中即可使用；而随用随付客户则必须为至少一个环境启用该插件。Shadow API Discovery 不可在 Apigee 评估环境中使用。

如需使用此功能，您必须启用该插件。如果您是订阅客户，则可以为组织启用该插件。如需了解详情，请参阅管理订阅组织的 Advanced API Security。如果您是随用随付客户，则可以在符合条件的环境中启用该插件。如需了解详情，请参阅管理 Advanced API Security 插件。

Shadow API Discovery 所需的角色和权限

下表显示了执行与 Shadow API Discovery 相关的任务所需的角色。

任务 所需的角色
启用或停用 Advanced API Security Apigee Organization Admin (roles/apigee.admin)
创建观察来源和作业 API Management Admin (roles/apim.admin)
查看观察结果 API Management Viewer (roles/apim.viewer)

为 P4SA 添加权限

为项目的产品和项目专属服务账号 (P4SA) 添加所需的角色，以便启用观察作业。将 APIM API Discovery Service Agent 角色添加到 service-PROJECT_NUMBER@gcp-sa-apim.iam.gserviceaccount.com： 

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apim.iam.gserviceaccount.com" \
--role="roles/apim.apiDiscoveryServiceAgent"

在 Apigee 控制台中访问 Shadow API Discovery

如需在 Apigee 控制台中访问 Shadow API Discovery，请执行以下操作：

  1. 登录 Cloud 控制台中的 Apigee 界面。
  2. 依次前往 API Observation > Shadow API。
  3. 主页面会显示已生成的所有 API 观察结果。选择 API 观察和观察作业标签页可分别查看结果和创建观察作业。

创建观察作业

观察作业提供指令来让 Shadow API Discovery 查找影子 API。请按照以下步骤创建观察作业。请注意创建观察作业期间的行为和限制。

  1. 选择观察作业标签页，然后点击创建观察作业。
  2. 选择一个或多个观察来源。
    或
  3. 如果需要，可点击观察来源列表底部的创建观察来源来创建新的来源位置。请注意，观察来源创建过程可能需要几分钟时间。

    来源名称：您指定的用于标识来源的名称。
    位置：要观察的位置。通过添加更多来源区域，您可以更全面地了解整个基础架构中的 API。查看最佳实践。一个位置只能创建一个观察来源。
    网络和子网：VPC 网络和子网。子网必须与观察来源位置位于同一区域。
  4. 创建观察作业。指定观察作业名称，该名称在每个位置必须是唯一的。选择一个位置，以指定要在哪个位置汇总和处理数据。在来源区域中收集的所有数据都会在此区域中进行处理和访问，同时遵循 Google 的数据驻留政策。新观察作业的创建过程可能需要几分钟时间才能完成。
  5. 启用观察作业（可选）。您可以在创建作业时启用该作业，在这种情况下，该作业会立即开始观察。如果您未立即启用作业，则可以稍后从观察作业列表中启用观察作业。

启用、停用和删除观察作业

如需指定现有观察作业是否处于启用（活跃）状态，可在观察作业页面中，从相应作业所在行中的操作菜单中选择启用或停用。

如需删除现有的观察作业，可从该作业的操作菜单中选择删除。删除作业也会移除与该作业关联的观察结果，因此，如果您只想停止作业运行，而想要保留结果，停用该作业即可，而不是将其删除。无法删除活跃作业；如果需要删除活跃作业，请先停用这些作业。

查看 API 观察结果

如需查看已启用的观察作业的 API 观察结果，请选择 API 观察标签页，然后从列表中选择所需的观察作业。

“API 观察”页面

观察列表会显示以下值：

  • 主机名：API 主机名。点击主机名可查看观察结果详情。
  • API 操作：观察到的 API 操作（例如 GET 或 PUT 请求）的数量。
  • 服务器 IP：托管被发现的 API 的服务器的 IP。
  • 来源位置：观察到流量的来源位置。
  • 最后一次检测到事件的时间 (UTC)：检测到最近向 API 发送的请求的日期和时间。

查看观察结果详情

在观察结果列表中点击所需的主机名后，您将看到相应的观察结果详情页面。

API 观察结果详情

本页面包含有关观察结果的以下信息。

  • 页面顶部的摘要框会显示以下信息：
    • API 观察 ID：这是一个 Apigee 特定的标识符。
    • API 操作：如需了解此字段的说明，请参阅查看 API 观察结果。
    • 创建时间 (UTC)：观察作业的创建日期和时间。
    • 最后一次检测到事件的时间：如需了解此字段的说明，请参阅查看 API 观察结果。
  • 检测到的此被发现的 API 执行的特定 API 操作的表。对于每个请求，该表都会显示以下信息：
    • 路径：请求路径。
    • 方法：请求方法（例如 GET、PUT 等）。
    • 计数：使用该方法发送到该路径的请求的数量。
    • 事务请求：来自流量数据的请求正文。包含此 API 操作的请求标头和相应的事务计数。
    • 事务响应标头：来自流量数据的响应标头。包含此 API 操作的响应标头和相应的事务计数。
    • 事务响应代码：此 API 操作的响应代码和包含该代码的响应计数。
    • 首次出现时间 (UTC)：首次观察到对此 API 操作的请求的日期和时间。
    • 上次出现时间 (UTC)：最近观察到对此 API 操作的请求的日期和时间。

最佳实践

我们建议您在使用 Shadow API Discovery 时遵循以下做法：

  • 遵循组织的数据驻留规则，确保符合任何适用法规和法律的要求。
  • 从尽可能多的来源区域汇总数据以实现最佳的跨区域相关性。在观察作业中添加更多来源区域以更全面地了解整个基础架构中的 API。

行为和限制

本部分列出了适用于 Shadow API Discovery 的行为和限制：

  • 使用 Shadow API Discovery 并不保证能够观察到 100% 的流量或发现所有影子 API。
  • Shadow API Discovery 仅可查找 Google Cloud 基础架构中的影子 API。
  • Shadow API Discovery 目前仅支持区域级应用负载均衡器。
  • Shadow API Discovery 会查找 HTTP 协议 API，而不是 gRPC。
  • 警告：Shadow API Discovery 在每个项目中仅支持一个网络上的负载均衡器。如果您在一个项目的多个网络中启用 Shadow API Discovery，则可能出现意外行为。
  • 警告：启用 Shadow API Discovery 可能会导致项目内所有网络中的负载均衡器调用的延迟时间增加。
  • 新启用的观察作业最多可能需要 60 分钟才会开始检测流量。
  • 必须有流量流经所观察项目中的负载均衡器，才能检测影子 API。Shadow API Discovery 至少需要几分钟到几小时的流量检测时间，具体取决于流量大小。稀疏的流量需要更长的观察时间，才能提供观察结果。
  • 每个区域只能有一个观察来源，最多有三个观察作业。如果您需要三个以上的观察作业，请与 Apigee 支持团队联系以讨论您的应用场景。
  • 可以创建、停用或删除观察作业，但不能对其进行修改。如果您需要更改观察作业，请将其删除并重新创建。
  • 目前，Shadow API Discovery 作业仅支持部分区域。