使用 Dev Proxy 探索影子 API

使用 Azure API 中心，您可以編錄組織中所使用的 API。這可讓您判別所使用的 API、API 在其生命週期中的位置，以及有問題時可聯絡的人員。簡言之，擁有最新狀態的 API 目錄可協助您改善治理、合規性和安全性態勢。

建置應用程式時，特別是當您整合新的案例時，您可能會使用未在 Azure API 中心註冊的 API。這些 API 稱為陰影 API。影子 API 是指未在貴組織中註冊的 API。這些 API 可能是尚未註冊的 API，或是不適合在貴組織中使用的 API。

檢查陰影 API 的其中一種方式是使用開發者代理。開發 Proxy 是一種 API 模擬器，可攔截和分析來自應用程式的 API 要求。開發 Proxy 的其中一項功能是檢查攔截的 API 要求是否屬於 API 中心註冊的 API。

開始之前

若要偵測影子 API，您需要有 Azure API 中心實例，其中包含您在組織中所使用的 API 相關信息。如果您尚未建立，請參閱快速入門：建立您的 API 中心。此外，您必須安裝 Dev Proxy。

複製 API 中心資訊

從 Azure API 中心執行個體 [概觀] 頁面，複製 API 中心執行個體的 [名稱]、[資源群組] 的名稱和 [訂用帳戶識別碼]。您需要此資訊來設定開發 Proxy ApiCenterOnboardingPlugin ，使其可以連線到您的 Azure API 中心實例。

設定開發代理伺服器

若要檢查您的應用程式是否使用陰影 API，您需要在開發 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 Toolkit Visual Studio Code 擴充套件輕鬆管理 Dev Proxy 設定。

新增回報器

ApiCenterOnboardingPlugin 會產生應用程式正在使用的 API 報表。若要檢視此報表，請將回報器新增至您的開發 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 訂用帳戶、執行開發 Proxy，並使其攔截來自您應用程式的 API 要求。然後，開發 Proxy 會比較 API 要求的相關資訊與 Azure API 中心的資訊，並回報任何未在 API 中心註冊的 API。

連接到 Azure 訂用帳戶

開發 Proxy 會使用來自 Azure API 中心的資訊，判斷您的應用程式是否使用陰影 API。若要取得這項資訊，該功能需要連線到您的 Azure 訂用帳戶。您可以透過數種方式 (部分機器翻譯) 連線到您的 Azure 訂用帳戶。

執行開發代理

連線到您的 Azure 訂用帳戶之後，請啟動開發者代理。如果您從 devproxyrc.json 檔案所在的相同資料夾啟動開發 Proxy，其會自動載入設定。否則，請使用 --config-file 選項指定設定檔的路徑。

當開發 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 要求。

使用您的應用程式

像平常一樣使用您的應用程式。開發 Proxy 會攔截 API 要求，並將相關資訊儲存在記憶體中。在開發 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 鍵可停止錄製。開發代理連接到 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...

開發 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 上線，請在開發 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 的開發 Proxy 時，該功能會自動在 Azure API 中心為偵測到的陰影 API 建立新的 API 項目。

使用 OpenAPI 規格自動上線陰影 API

當您選擇將陰影 API 自動上線至 API 中心時，您可以讓開發 Proxy 產生 API 的 OpenAPI 規格。使用 OpenAPI 規格將 API 上線可加快遺失端點的上線速度，並提供 API 的必要資訊。當 ApiCenterOnboardingPlugin 偵測到開發 Proxy 創建了新的 OpenAPI 規格時，會將其關聯至 API 中心對應的上線 API。

若要自動產生上線 API 的 OpenAPI 規格，請更新開發 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
  }
}

這很重要

開發 Proxy 會依在設定中註冊的順序執行外掛程式。您需要先註冊 OpenApiSpecGeneratorPlugin，以便在 ApiCenterOnboardingPlugin 上線新的 API 之前，可先建立 OpenAPI 規格。

當您執行此設定的開發 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，再發行至生產環境。

詳細資訊

Last updated on 2024-07-15

共用方式為