如何整合 Azure API 管理與 Azure 應用程式 Insights

適用於：所有 APIM 層

您可以輕鬆整合 Azure 應用程式 Insights 與 Azure API 管理。 Azure 應用程式 Insights 是可延伸的服務，可供 Web 開發人員在多個平台上建置和管理應用程式。在本指南中，您將會：

逐步解說 Application Insights 與 APIM 的整合。
了解在 API 管理服務執行個體上降低效能影響的策略。

Note

在 API 管理的工作區中，工作區擁有者可以獨立整合 Application Insights 並為工作區的 API 啟用 Application Insights 記錄。將工作區與 Application Insights 整合的一般指導與 API 管理執行個體的指導類似；不過，設定的範圍僅限於工作區。目前，您必須透過設定連接字串 (建議) 或檢測金鑰，在工作區中整合 Application Insights。

Warning

使用自架閘道時，我們不保證所有遙測資料都會推送到 Azure 應用程式 Insights，因為它依賴 Application Insights 的記憶體緩衝。

Prerequisites

建立一個 Azure API 管理實例。
建立一個 Application Insights 服務的實例。若要使用 Azure 入口網站建立實例，請參閱基於工作空間的應用程式洞察資源。

Note

Application Insights 資源可以在不同的訂閱中，甚至位於與 API 管理資源不同的租用戶中。
如果您打算將受控識別認證設定為搭配 Application Insights 使用，請完成下列步驟：
1. 針對 APIM 啟用系統指派或使用者指派的受控識別。
  - 如果您啟用使用者指派的受控識別，請記下身分識別的用戶端識別碼。
2. 為此身分識別指派監視計量發行者角色，且範圍設定為 Application Insights 資源。若要指派角色，請使用 Azure 入口網站或其他 Azure 工具。

案例概觀

以下步驟將提供此情境的高層次概述。

建立應用洞察與 API 管理之間的連結。

你可以透過 Azure 入口網站、REST API 或相關的 Azure 工具，建立 Application Insights 與 API 管理之間的連結。 APIM 會為連線設定「記錄器」資源。

Important

目前，在入口網站中，APIM 僅支援使用 Application Insights 檢測金鑰連線到 Application Insights。為了提升安全性，建議將 Application Insights 的連接字串與 API 管理的受控識別搭配使用。若要使用受控識別認證設定連接字串，請使用 REST API 或相關工具，如本文稍後小節所示。欲了解更多，請參閱應用洞察中的連接字串。

Note

如果你的 Application Insights 資源在不同租戶中，請使用 REST API 或相關工具建立日誌，如本文後面章節所示。
為您的 API 或多個 API 啟用 Application Insights 記錄。

在本文中，您可以使用 Azure 入口網站為 API 啟用 Application Insights 記錄功能。 APIM 會為 API 設定「診斷」資源。

透過 Azure 入口建立連線

遵循這些步驟，使用 Azure 入口網站來建立 Application Insights 與 APIM 之間的連線。

Note

可能的話，Microsoft 建議使用連接字串搭配受控識別認證來增強安全性。若要設定這些認證，請使用 REST API 或相關工具，如本文稍後小節所示。

前往 Azure 入口網站中的 Azure API 管理服務執行個體。
在側邊欄選單的監控中，選擇 應用程式洞察。
選取 [+ 新增] 。
選取先前建立的 Application Insights 執行個體，然後提供簡短描述。
若要在 Application Insights 中啟用 API 管理執行個體的可用性監視，請選取 [新增可用性監視] 核取方塊。
- 此設定定期檢查 API 管理閘道端點是否回應。
- 結果會出現在 Application Insights 執行個體的 [可用性] 窗格中。
選取 ，創建。
檢查新的 Application Insights 記錄器現在出現在清單中。

Note

在幕後，記錄器實體會建立於 APIM 執行個體，其中包含 Application Insights 執行個體的檢測金鑰。

Tip

如果您需要更新 Application Insights 記錄器中設定的檢測金鑰，則在清單中選取該記錄器的資料列 (而非記錄器的名稱)。輸入檢測金鑰，然後選取 [儲存]。

使用 REST API、Bicep 或 ARM 範本建立連線

請遵循下列步驟，使用 REST API、Bicep 或 ARM 範本，為您的 APIM 執行個體建立 Application Insights 記錄器。你可以設定使用含有受控識別憑證之連接字串的記錄器（建議），或設定僅使用連接字串的記錄器。

使用連接字串和受控識別認證的記錄器（建議）

請參閱使用 APIM 受控識別的必要條件。

Application Insights 連接字串會出現在 Application Insights 資源的 [概觀] 區段中。

使用系統指派的受控識別的連接字串

使用 APIM 的「記錄器 - 建立或更新」REST API，並使用以下的要求本文。

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with system-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"SystemAssigned"
    }
  }
}

請在你的二頭肌檔案中加入類似以下範例的片段。

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  properties: {
    loggerType: 'applicationInsights'
    description: 'Application Insights logger with system-assigned managed identity'
    credentials: {
      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
      identityClientId: 'systemAssigned'
    }
  }
}

在你的 Azure 資源管理器範本中加入類似以下範例的 JSON 片段。

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with system-assigned managed identity",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "SystemAssigned"
    }
  }
}

使用使用者指派的受控識別的連接字串

使用 APIM 的「記錄器 - 建立或更新」REST API，並使用以下的要求本文。

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with user-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"<client-ID>"
    }
  }
}

請在你的二頭肌檔案中加入類似以下範例的片段。

resource aiLoggerWithUserAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  properties: {
    loggerType: 'applicationInsights'
    description: 'Application Insights logger with user-assigned managed identity'
    credentials: {
      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
      identityClientId: '<client-ID>'
    }
  }
}

在你的 Azure 資源管理器範本中加入類似以下範例的 JSON 片段。

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with user-assigned managed identity",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "<client-ID>"
    }
  }
}

僅使用連接字串認證的記錄器

Application Insights 連接字串會出現在 Application Insights 資源的 [概觀] 區段中。

使用 APIM 的「記錄器 - 建立或更新」REST API，並使用以下的要求本文。

如果你要為工作區設定日誌，請使用 Workspace Logger - 建立或更新 REST API。

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."    
    }
  }
}

請在你的二頭肌檔案中加入類似以下範例的片段。

如果您要為工作區設定記錄器，請改為建立 Microsoft.ApiManagement/service.workspace/loggers@2023-09-01-preview 資源。

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  properties: {
    loggerType: 'applicationInsights'
    description: 'Application Insights logger with connection string'
    credentials: {
      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
    }
  }
}

在你的 Azure 資源管理器範本中加入類似以下範例的 JSON 片段。

如果您要為工作區設定記錄器，請建立 Microsoft.ApiManagement/service.workspace/loggers 資源，並將 apiVersion 設為 2023-09-01-preview。

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
    },
  }
}

為您的 API 啟用 Application Insights 記錄功能

使用下列步驟，為 API 啟用 Application Insights 記錄功能。您也可以為所有 API 啟用 Application Insights 記錄功能。

前往 Azure 入口網站中的 Azure API 管理服務執行個體。
從側邊欄選單選擇 API>API。
選取 API，例如 Swagger Petstore。如果已設定，請選取版本。

Tip

若要為所有 API 啟用記錄功能，請選取 [所有 API]。
選擇上方欄的設定標籤。
往下滑到 診斷日誌 區塊，勾選啟用選項。
從 [目的地] 下拉式清單中，選取已連結的記錄器。
輸入 100 作為 取樣 (%)，並選取 「一律記錄錯誤」 核取方塊。
讓其餘設定保持原狀。如需設定的詳細資訊，請參閱診斷記錄設定參考。

Warning

覆寫預設的 要記錄的有效載荷位元組數 值 0 可能會大幅降低您 API 的效能。
選取 [儲存]。
在幕後作業中，名為的applicationinsights實體會建立於 API 層級。

Note

一旦 API 管理將整個回應傳送至用戶端，要求即成功。

適用於單一 API 或所有 API 的記錄器

你可以在不同層級指定記錄器：

單一 API 記錄器
適用於所有 API 的記錄器

如果你同時指定兩者：

根據預設，單一 API 記錄器 (更細微的層級) 會覆寫適用於所有 API 的記錄器。
如果兩個層級的記錄器配置不同，且你需要兩個記錄器才能接收遙測（多工），請聯絡 Microsoft 支援。如果你同時在「所有 API」層級和單一 API 層級使用相同的記錄器（Application Insights 目的地），則不支援多路傳送。若要讓多工正常運作，您必須在「所有 API」和個別 API 層級上設定不同的記錄器，並向 Microsoft 支援服務要求協助，來為您的服務啟用多工。

哪些資料會新增至 Application Insights

Application Insights 會接收：

遙測項目	Description
Request	對於每個傳入要求：前端請求前端回應
Dependency	來自支援的原則執行之自動外部相依性遙測，包括轉送至後端服務的要求。
Exception	對於每個失敗的要求：因用戶端連線中斷而失敗已觸發 API 原則的 on-error 區段擁有符合 4xx 或 5xx 的回應 HTTP 狀態碼
Trace	如果您設定追蹤原則。 `severity` 原則中的 `trace` 設定必須等於或大於 Application Insights 記錄中的 `verbosity` 設定。

受支援原則的外部相依性遙測

在您設定並啟用 Application Insights 日誌後，API Management 會自動收集以下政策的外部相依性遙測資料。無需額外的政策或遙測設定：

authentication-managed-identity
authentication-token
azure-openai-semantic-cache-lookup
cosmosdb-request-handler
forward-request
get-authorization-context
http-data-source
invoke-dapr-binding
llm-content-safety
llm-semantic-cache-lookup
send-request
send-one-way-request
send-service-bus-message
sql-data-source
validate-jwt

Application Insights 將這些外部呼叫記錄為相關子操作。例如，您可以將重試、由 validate-jwt 進行的 OpenID Connect 中繼資料擷取、服務匯流排傳送作業或後端轉送視為相關作業。若要在 Azure 入口網站中驗證遙測資料，請在您的 Application Insights 資源中開啟 端對端交易詳細資料，並檢閱某項要求的相關作業。

目前，依賴追蹤僅支援前述列表中的政策。

Note

關於每個 Application Insights 實例最大大小及指標與事件數量的資訊，請參閱 Application Insights 限制。

發出自訂計量

您可以從 APIM 執行個體發出自訂計量到 Application Insights。 API Management 透過 emit-metric 和 llm-emit-token-metric 等政策來發布自訂指標。下一節使用 emit-metric 原則作為範例。

Note

自訂計量是 Azure 監視器的預覽功能，並受限制。

要發出自訂指標，請完成以下設定步驟：

使用 Application Insights 執行個體中的自訂維度，啟用 [自訂計量 (預覽)]。
1. 請前往入口網站中的 Application Insights 實例。
2. 在側邊欄選單的 「配置 」中，選擇 使用量與預估費用。
3. 選取 [自訂計量 (預覽)]>[具有維度]。
4. 請選擇 [確定]。

將 "metrics": true 屬性新增至你在 API Management 中設定的 applicationInsights 診斷實體。目前，您必須透過 API Management 診斷 - 建立或更新 REST API 來新增此屬性。例如：

PUT https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<API-management-service-name>/diagnostics/applicationinsights

{
    [...]
    {
    "properties": {
        "loggerId": "/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<API-management-service-name>/loggers/<application-insights-logger-name>",
        "metrics": true
        [...]
    }
  }
}

請確保 Application Insights 記錄器已設定於您要發出自訂計量的層級（無論是所有 API 還是單一 API）。如需詳細資訊，請參閱本文稍早的為 API 啟用 Application Insights 記錄功能。
在已設定 Application Insights 記錄並啟用自訂計量的範圍內（可為所有 API 或單一 API），設定 emit-metric 原則。如需原則詳細資料，請參閱 emit-metric 原則參考。

自訂計量的限制

Azure 監視器會針對自訂計量施加使用量限制，其可能會對您從 APIM 發出計量的能力產生影響。例如，Azure 監視器目前會為每個計量設定 10 個維度索引鍵的限制，以及為訂用帳戶中的每個區域設定總計 50,000 個使用中時間序列的限制 (在 12 小時內)。在 API 管理中，其中 5 個用於預設維度，包括下列各項：

Region
服務識別碼
服務名稱
服務類型

這些限制對於在 API 管理原則 (例如 emit-metric 或 azure-openai-emit-token-metric) 中設定自訂計量有下列隱含意義：

您可以在每個原則中最多設定 5 個自訂維度。
政策產生的活躍時間序列數是每個命名空間中每個配置維度唯一值數的乘積。例如，如果在原則中設定了三個自訂維度，而且每個維度在該期間內都有 10 個可能的值，則原則會提供 1,000 (10 x 10 x 10) 個使用中時間序列。
API 管理限制每個維度為 100 個獨特值，每個指標命名空間為 1,000 個活躍時間序列。當達到任一限制時，任何新的維度值或時間序列都不會被追蹤，對應的度量資料也會被靜默丟棄。
如果您在位於訂用帳戶相同區域內的多個 API 管理執行個體中設定原則，則所有執行個體可能都會影響區域使用中時間序列限制。

深入了解 Azure 監視器中自訂計量的設計限制和考量。

效能影響與記錄取樣

Warning

記錄所有事件可能會對效能造成嚴重影響，視收到的請求速率而定。

根據內部負載測試，當要求比率超過每秒 1,000 個要求時，啟用此記錄功能會造成輸送量降低 40%-50%。 Application Insights 的設計目的是使用統計分析來評估應用程式效能。它不是：

目的為稽核系統。
適用於記錄大量 API 的每個個別要求。

您可以透過調整 [取樣] 設定，來操控要記錄的要求數目。值為 100% 時，表示會記錄所有要求，值為 0% 時，則表示不進行記錄。

取樣有助於減少遙測量，可有效地防止嚴重的效能衰退，同時仍享有記錄功能的優點。

若要改善效能問題，請略過：

請求與回應標頭
本文記錄

Troubleshooting

解決從 APIM 到 Application Insights 的遙測資料流程問題：

調查在 API 管理資源所連接的虛擬網路中，是否存在連結的 Azure 監視器私有連結範圍（AMPLS）資源。 AMPLS 資源具有跨訂用帳戶的全域範圍，並負責管理所有 Azure 監視器資源的資料查詢和擷取。 AMPLS 可能已配置為僅限私人存取模式，專門用於資料匯入。在這種情況下，請在 AMPLS 中包含 Application Insights 資源及其相關聯的 Log Analytics 資源。新增之後，APIM 資料將成功內嵌至 Application Insights 資源，以解決遙測資料傳輸問題。

Application Insights 簡介 - OpenTelemetry 可檢視性
如何將事件記錄到 Azure API 管理中的 Azure 事件中樞
監視 APIM (部分內容可能是機器或 AI 翻譯)

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-09-17

如何整合 Azure API 管理與 Azure 應用程式 Insights

Prerequisites

案例概觀

透過 Azure 入口建立連線

使用 REST API、Bicep 或 ARM 範本建立連線

使用連接字串和受控識別認證的記錄器（建議）

使用系統指派的受控識別的連接字串

使用使用者指派的受控識別的連接字串

僅使用連接字串認證的記錄器

為您的 API 啟用 Application Insights 記錄功能

適用於單一 API 或所有 API 的記錄器

哪些資料會新增至 Application Insights

受支援原則的外部相依性遙測

發出自訂計量

自訂計量的限制

效能影響與記錄取樣

Troubleshooting

相關內容

意見反應

其他資源