你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Dev Proxy 发现影子 API

项目
07/19/2024

使用 Azure API 中心，可以编录组织中使用的 API。这样就可以知道使用了哪些 API、API 在其生命周期中的所处位置，以及出现问题时应与谁联系。简言之，拥有最新的 API 目录可帮助你改进治理、合规性和安全状况。

生成应用时，尤其是在集成新方案时，你可能使用的是未在 Azure API 中心注册的 API。这些 API 称为影子 API。影子 API 是组织中未注册的 API。它们可能是尚未来得及注册的 API，也可能是组织中未打算使用的 API。

检查影子 API 的一种方法是使用 Dev Proxy。 Dev Proxy 是一种 API 模拟器，用于截获和分析来自应用程序的 API 请求。 Dev Proxy 的一项功能是检查截获的 API 请求是否属于在 API 中心注册的 API。

开始之前

若要检测影子 API，需要有一个 Azure API 中心实例，其中包含组织中使用的 API 的相关信息。如果尚未创建 API 中心，请参阅快速入门：创建 API 中心。此外，还需要安装 Dev Proxy。

复制 API 中心信息

在 Azure API 中心实例概述页中，复制 API 中心实例名称、资源组名称以及订阅 ID。需要此信息来配置 Dev Proxy ApiCenterOnboardingPlugin，以便它可以连接到 Azure API 中心实例。

配置 Dev Proxy

若要检查应用是否使用了影子 API，需要在 Dev Proxy 配置文件中启用 ApiCenterOnboardingPlugin。若要创建应用使用的 API 报告，请添加报告器。

启用 `ApiCenterOnboardingPlugin`

在 devproxyrc.json 文件中，添加以下配置：

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": false
  }
}

在 subscriptionId、resourceGroupName 和 serviceName 属性中，提供有关 Azure API 中心实例的信息。

在 urlsToWatch 属性中，指定应用使用的 URL。

提示

使用 Dev Proxy 工具包 Visual Studio Code 扩展轻松管理 Dev Proxy 配置。

添加报告器

ApiCenterOnboardingPlugin 可生成应用所使用的 API 的报告。若要查看此报告，请将报告器添加到 Dev Proxy 配置文件。 Dev Proxy 提供了多个报告器。在此示例中，你使用的是纯文本报告器。

通过对纯文本报告器的引用更新 devproxyrc.json 文件：

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": false
  }
}

检查应用是否使用影子 API

若要检查应用是否使用了影子 API，请连接到 Azure 订阅，运行 Dev Proxy，并允许其截获来自应用的 API 请求。然后，Dev Proxy 会将 API 请求的相关信息与 Azure API 中心的信息进行比较，并报告任何未在 API 中心注册的 API。

连接到 Azure 订阅

Dev Proxy 使用 Azure API 中心的信息来确定应用是否正在使用影子 API。若要获取此信息，需要连接到 Azure 订阅。可以通过多种方式连接到 Azure 订阅。

运行 Dev Proxy

连接到 Azure 订阅后，启动 Dev Proxy。如果从 devproxyrc.json 文件所在的同一文件夹中启动 Dev Proxy，则会自动加载配置。否则，请使用 --config-file 选项指定配置文件的路径。

Dev Proxy 启动后，它会检查是否可以连接到 Azure 订阅。一旦连接成功，将会收到一条消息，内容如下：

 info    Plugin ApiCenterOnboardingPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

按“r”开始记录来自应用的 API 请求。

使用应用

像平时一样使用应用。 Dev Proxy 截获 API 请求，并将有关这些请求的信息存储在内存中。在运行 Dev Proxy 的命令行中，应会看到有关应用发出的 API 请求的信息。

 info    Plugin ApiCenterOnboardingPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

◉ Recording... 

 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 api   ╰ Passed through

 req   ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
 api   ╰ Passed through

检查阴影 API

按“s”停止记录。 Dev Proxy 连接到 API 中心实例，并将请求相关信息与 API 中心的信息进行比较。

 info    Plugin ApiCenterOnboardingPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

◉ Recording... 

 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 api   ╰ Passed through

 req   ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
 api   ╰ Passed through
○ Stopped recording
 info    Checking if recorded API requests belong to APIs in API Center...
 info    Loading APIs from API Center...
 info    Loading API definitions from API Center...

在 Dev Proxy 完成分析后，它会在名为 ApiCenterOnboardingPlugin_PlainTextReporter.txt 的文件中创建一个包含以下内容的报告：

New APIs that aren't registered in Azure API Center:

https://jsonplaceholder.typicode.com:
  DELETE https://jsonplaceholder.typicode.com/posts/1

APIs that are already registered in Azure API Center:

GET https://jsonplaceholder.typicode.com/posts

自动载入影子 API

ApiCenterOnboardingPlugin 不仅可以检测影子 API，还可以自动将它们载入 API 中心。若要自动载入影子 API，请在 Dev Proxy 配置文件中，将 createApicEntryForNewApis 更新为 true。

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": true
  }
}

运行 createApicEntryForNewApis 设置为 true 的 Dev Proxy 时，它会自动在 Azure API 中心为检测到的影子 API 创建新的 API 条目。

利用 OpenAPI 规范自动载入影子 API

当你选择将影子 API 自动载入到 API 中心时，你可以通过 Dev Proxy 为 API 生成 OpenAPI 规范。利用 OpenAPI 规范载入 API 可加快缺失的终结点的载入速度，并提供有关 API 的必要信息。当 ApiCenterOnboardingPlugin 检测到该 Dev Proxy 创建了一个新的 OpenAPI 规范时，它会将其与 API 中心中的相应载入 API 相关联。

若要为载入 API 自动生成 OpenAPI 规范，请更新 Dev Proxy 配置以包括 OpenApiSpecGeneratorPlugin。

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "OpenApiSpecGeneratorPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    },
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": true
  }
}

重要

Dev Proxy 按照在配置中注册的顺序执行插件操作。首先需要注册 OpenApiSpecGeneratorPlugin，以便在 ApiCenterOnboardingPlugin 载入新 API 之前创建 OpenAPI 规范。

在此配置下运行 Dev Proxy 时，它会自动在 Azure API 中心为检测到的影子 API 创建新的 API 条目。对于每个新的 API，Dev Proxy 会生成 OpenAPI 规范，并将其与 API 中心中的相应载入 API 相关联。

 info    Plugin ApiCenterOnboardingPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

◉ Recording... 

 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 api   ╰ Passed through

 req   ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
 api   ╰ Passed through
○ Stopped recording
 info    Creating OpenAPI spec from recorded requests...
 info    Created OpenAPI spec file jsonplaceholder.typicode.com-20240614104931.json
 info    Checking if recorded API requests belong to APIs in API Center...
 info    Loading APIs from API Center...
 info    Loading API definitions from API Center...
 info    New APIs that aren't registered in Azure API Center:

https://jsonplaceholder.typicode.com:
  DELETE https://jsonplaceholder.typicode.com/posts/1
 info    Creating new API entries in API Center...
 info      Creating API new-jsonplaceholder-typicode-com-1718354977 for https://jsonplaceholder.typicode.com...
 info    DONE

总结

使用 Dev Proxy 及其 ApiCenterOnboardingPlugin，可以检查应用是否正在使用影子 API。该插件可分析来自应用的 API 请求，并报告任何未在 Azure API 中心注册的 API 请求。使用该插件，可以轻松地将缺失的 API 载入 API 中心。通过将 ApiCenterOnboardingPlugin 插件与 OpenApiSpecGeneratorPlugin 相结合，可以为新载入的 API 自动生成 OpenAPI 规范。可以手动运行此检查或与 CI/CD 管道集成，以确保在将应用发布到生产环境之前它使用的是已注册的 API。

通过

使用 Dev Proxy 发现影子 API

开始之前

复制 API 中心信息

配置 Dev Proxy

启用 `ApiCenterOnboardingPlugin`

添加报告器

检查应用是否使用影子 API

连接到 Azure 订阅

运行 Dev Proxy

使用应用

检查阴影 API

自动载入影子 API

利用 OpenAPI 规范自动载入影子 API

总结

详细信息

反馈

其他资源

通过

使用 Dev Proxy 发现影子 API

开始之前

复制 API 中心信息

配置 Dev Proxy

启用 ApiCenterOnboardingPlugin

添加报告器

检查应用是否使用影子 API

连接到 Azure 订阅

运行 Dev Proxy

使用应用

检查阴影 API

自动载入影子 API

利用 OpenAPI 规范自动载入影子 API

总结

详细信息

反馈

其他资源

启用 `ApiCenterOnboardingPlugin`