共用方式為


教學課程 - 使用開發 Proxy 探索影子 API

Azure API 中心可用於編目組織中所使用的 API。 您可以藉此掌握所使用的 API、API 在其生命週期中的階段,以及有問題時要連絡的人員。 簡言之,擁有最新狀態的 API 目錄可協助您改善治理、合規性和安全性態勢。

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

檢查陰影 API 的其中一種方式是使用開發 Proxy (部分機器翻譯)。 開發 Proxy 是一種 API 模擬器,可攔截和分析來自應用程式的 API 要求。 開發 Proxy 的其中一項功能是檢查攔截到的 API 要求是否屬於已在 API 中心註冊的 API。

命令提示字元的螢幕擷取畫面,其中顯示開發 Proxy 檢查記錄的 API 要求是否已在 Azure API 中心註冊。

在您開始使用 Intune 之前

若要偵測影子 API,您需要有 Azure API 中心執行個體,其中包含您在組織中所使用的 API 相關資訊。 如果您尚未建立,請參閱快速入門:建立您的 API 中心。 此外,您必須安裝開發 Proxy (部分機器翻譯)。

複製 API 中心資訊

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

Azure API 中心概觀頁面的螢幕擷取畫面,其中已醒目提示數個屬性。

設定開發 Proxy

若要檢查您的應用程式是否使用陰影 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
  }
}

subscriptionIdresourceGroupNameserviceName 屬性中,提供 Azure API 中心執行個體的相關資訊。

urlsToWatch 屬性中,指定應用程式使用的 URL。

提示

使用開發 Proxy 工具組 (英文) Visual Studio Code 延伸模組輕鬆管理開發 Proxy 設定。

新增回報器

ApiCenterOnboardingPlugin 會產生應用程式正在使用的 API 報表。 若要檢視此報表,請將回報器新增至您的開發 Proxy 設定檔。 開發人員 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 訂用帳戶。

執行開發 Proxy

連線到您的 Azure 訂用帳戶之後,請啟動開發 Proxy。 如果您從 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 鍵可停止錄製。 開發 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...

開發 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 項目。

螢幕擷取畫面:顯示新上線 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,開發 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

Azure API 中心的螢幕擷取畫面,其中顯示具有 OpenAPI 規格的新上線 API。

摘要

使用開發 Proxy 及其 ApiCenterOnboardingPlugin,您可以檢查您的應用程式是否使用陰影 API。 外掛程式會分析來自您應用程式的 API 要求,並報告任何未在 Azure API 中心註冊的 API 要求。 此外掛程式可讓您輕鬆地將遺漏的 API 上線至 API 中心。 藉由結合 ApiCenterOnboardingPlugin 外掛程式與 OpenApiSpecGeneratorPlugin,您可以為新上線的 API 自動產生 OpenAPI 規格。 您可以手動執行這項檢查,或整合您的 CI/CD 管線,以便確認您的應用程式使用已註冊的 API,再發行至生產環境。

其他相關資訊