Shadow API Discovery 概览

概览

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

本页面中有关设置和查看 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)

在 Apigee 控制台中访问 Shadow API Discovery

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

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

创建观察作业

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

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

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

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

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

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

查看 API 观察结果

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

观察列表会显示以下值：

主机名：API 主机名。点击主机名可查看观察结果详情。
API 操作：观察到的 API 操作（例如 GET 或 PUT 请求）的数量。
服务器 IP：托管被发现的 API 的服务器的 IP。
来源位置：观察到流量的来源位置。
最后一次检测到事件的时间 (UTC)：检测到最近向 API 发送的请求的日期和时间。
标记：您或其他人创建的用来给此观察结果加标签的标记列表。如需了解详情，请参阅使用标记。
操作：可针对每个观察结果执行的其他操作。

查看观察结果详情

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

Shadow API Discovery 观察作业详情

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

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

使用标记

借助标记，您可以对观察结果进行分类。标记是元数据，仅用于跟踪；标记不会更改观察结果中的任何内容，也不会触发任何操作。例如，添加“需要注意”标记不会创建任何通知或提醒。新观察结果没有标记。

标记具有以下特征：

您可以为多个观察结果添加相同的标记。
标记名称可以包含大小写字母、数字和特殊字符（包括空格）。
标记创建后，其名称便无法更改；如需重命名，请移除并重新创建该标记。
从所有观察结果中移除标记会将其从系统中删除。

您可以通过观察列表或观察详情页面管理标记。

如需在 API 观察结果列表中管理标记，请执行以下操作：

在观察结果列表的标记列中查看现有标记。
如需管理某个结果的标记，请从该结果对应行中的操作菜单中选择管理标记。
如需同时管理一个或多个结果的标记，请从列表中选择多个结果，然后点击列表顶部的管理标记。

如需通过 API 观察详情管理标记，请执行以下操作：

请参阅标记部分中的现有标记。
如需添加或管理标记，请选择页面顶部的管理标记。

在管理标记边栏中，要添加标记，请选择现有标记或添加新标记。如需移除标记，请取消选择相应标记。点击保存，保存新标记。

最佳做法

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

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

行为和限制

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

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

目前，Shadow API Discovery 作业仅支持部分区域。请参阅提出此请求的受支持区域列表：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)"
https://apim.googleapis.com/v1alpha/projects/{PROJECT}/locations