如何整合 Azure API 管理與 Azure Application Insights

發行項
10/01/2024

適用於：所有 APIM 層

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

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

注意

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

警告

使用自我裝載閘道時，我們並不保證所有遙測都會推送至 Azure Application Insights，因為它依賴 Application Insights 的記憶體內部緩衝處理。

必要條件

您需要 Azure API 管理執行個體。請先建立一個。
若要使用 Application Insights，請建立 Application Insights 服務的執行個體。若要使用 Azure 入口網站建立執行個體，請參閱以工作區為基礎的 Application Insights 資源。

注意

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

案例概觀

以下是此案例的高階步驟。

首先，在 Application Insights 與 APIM 之間建立連線

您可以使用 Azure 入口網站、REST API 或相關的 Azure 工具，在 Application Insights 與 APIM 之間建立連線。 APIM 會為連線設定「記錄器」資源。

重要

目前，在入口網站中，APIM 僅支援使用 Application Insights 檢測金鑰連線到 Application Insights。為了增強安全性，我們建議使用 Application Insights 連接字串搭配 APIM 受控識別。若要使用受控識別認證設定連接字串，請使用 REST API 或相關工具，如本文稍後小節所示。深入了解 Application Insights 連接字串。

注意

如果您的 Application Insights 資源位於不同的租用戶中，則您必須使用 REST API 或相關工具來建立記錄器，如本文稍後的小節所示。
接著，為您的一或多個 API 啟用 Application Insights 記錄功能。

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

使用 Azure 入口網站建立連線

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

注意

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

在「Azure 入口網站」中，瀏覽至您的「Azure API 管理服務執行個體」。
從左側功能表中，選取 [Application Insights]。
選取 + 新增。
選取先前建立的 Application Insights 執行個體，然後提供簡短描述。
若要在 Application Insights 中啟用 API 管理執行個體的可用性監視，請選取 [新增可用性監視] 核取方塊。
- 此設定會定期驗證 API 管理閘道端點是否回應。
- 結果會出現在 Application Insights 執行個體的 [可用性] 窗格中。
選取建立。
檢查新的 Application Insights 記錄器現在出現在清單中。

注意

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

提示

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

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

請遵循下列步驟，使用 REST API、Bicep 或 ARM 範本，為您的 APIM 執行個體建立 Application Insights 記錄器。您可以設定使用連接字串搭配受控識別認證的記錄器 (建議)，或只使用連接字串的記錄器。

使用連接字串搭配受控識別認證的記錄器 (建議)

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

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

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

使用 API 管理的「記錄器 - 建立或更新」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"
    }
  }
}

在您的 Bicep 範本中，包含類似下列內容的程式碼片段。

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  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 Resource Manager 範本中，包含類似下列內容的 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": "<ApplicationInsightsResourceID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "SystemAssigned"
    }
  }
}

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

使用 API 管理的「記錄器 - 建立或更新」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":"<ClientID>"
    }
  }
}

在您的 Bicep 範本中，包含類似下列內容的程式碼片段。

resource aiLoggerWithUserAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  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: '<ClientID>'
    }
  }
}

在您的 Azure Resource Manager 範本中，包含類似下列內容的 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": "<ApplicationInsightsResourceID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "<ClientID>"
    }
  }
}

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

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

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

如果您要為工作區設定記錄器，請使用「工作區記錄器 - 建立或更新」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/;..."    
    }
  }
}

在您的 Bicep 範本中，包含類似下列內容的程式碼片段。

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

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  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 Resource Manager 範本中，包含類似下列內容的 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": "<ApplicationInsightsResourceID>",
    "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，在此案例中為 [Demo Conference API]。如果已設定，請選取版本。

提示

若要為所有 API 啟用記錄功能，請選取 [所有 API]。
從頂端列移至 [設定] 索引標籤。
向下捲動至 [診斷記錄] 區段。
選取 [啟用] 方塊。
從 [目的地] 下拉式清單中，選取已連結的記錄器。
輸入 100 作為 [取樣 (%)]，然後選取 [一律記錄錯誤] 核取方塊。
讓其餘設定保持原狀。如需設定的詳細資訊，請參閱診斷記錄設定參考。

警告

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

注意

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

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

您可以指定不同層級的記錄器：

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

同時指定「兩者」：

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

哪些資料會新增至 Application Insights

Application Insights 會接收：

遙測項目	描述
要求	對於每個傳入要求：前端要求前端回應
相依性	對於每個轉送至後端服務的要求：後端要求後端回應
例外狀況	對於每個失敗的要求：因用戶端連線中斷而失敗已觸發 API 原則的 on-error 區段擁有符合 4xx 或 5xx 的回應 HTTP 狀態碼
追蹤	如果您設定追蹤原則。 `trace` 原則中的 `severity` 設定必須等於或大於 Application Insights 記錄中的 `verbosity` 設定。

注意

如需每個 Application Insights 執行個體的計量和事件大小和數目上限的相關資訊，請參閱 Application Insights 限制。

發出自訂計量

您可以從 APIM 執行個體發出自訂計量到 Application Insights。 APIM 會使用 emit-metric 和 azure-openai-emit-token-metric 等原則發出自訂計量。下一節使用 emit-metric 原則作為範例。

注意

自訂計量是 Azure 監視器的預覽功能，有其相關限制。

若要發出自訂計量，請執行下列設定步驟。

使用 Application Insights 執行個體中的自訂維度，啟用 [自訂計量 (預覽)]。
1. 在入口網站中，瀏覽到您的 Application Insights 執行個體。
2. 在左側功能表中，選取 [使用量和估計成本]。
3. 選取 [自訂計量 (預覽)]>[具有維度]。
4. 選取 [確定]。

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

PUT https://management.azure.com/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/diagnostics/applicationinsights

{
    [...]
    {
    "properties": {
        "loggerId": "/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/loggers/{ApplicationInsightsLoggerName}",
        "metrics": true
        [...]
    }
}

確定會在您想要發出自訂計量的範圍 (所有 API 或單一 API) 中設定 Application Insights 記錄器。如需詳細資訊，請參閱本文稍早的為 API 啟用 Application Insights 記錄功能。
在已設定 Application Insights 記錄功能的範圍 (所有 API 或單一 API) 中設定 emit-metric 原則，並針對自訂計量加以啟用。如需原則詳細資料，請參閱 emit-metric 原則參考。

自訂計量的限制

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

這些限制對於在 API 管理原則中設定自訂計量有下列影響，例如 emit-metric 或 azure-openai-emit-token-metric：

您可以在每個原則中最多設定 10 個自訂維度。
原則在 12 小時內所產生的使用中時間序列數目，是在該期間內每個已設定維度之唯一值數目的乘積。例如，如果在原則中設定了三個自訂維度，而且每個維度在該期間內都有 10 個可能的值，則原則會提供 1,000 (10 x 10 x 10) 個使用中時間序列。
如果您在位於訂用帳戶相同區域內的多個 APIM 執行個體中設定原則，則所有執行個體可能都會影響區域使用中時間序列限制。

深入瞭解 Azure 監視器中自定義計量的設計限制和考慮。

效能影響與記錄取樣

警告

視連入要求速率而定，記錄所有事件可能會帶來嚴重的效能影響。

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

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

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

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

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

要求和回應標頭。
本文記錄。

影片

疑難排解

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

調查連結的 Azure 監視器私人連結範圍 (AMPLS) 資源是否存在於連線 APIM 資源的 VNet 內。 AMPLS 資源具有跨訂用帳戶的全域範圍，並負責管理所有 Azure 監視器資源的資料查詢和擷取。 AMPLS 可能已特別針對資料擷取使用僅限私人存取模式進行設定。在這種情況下，請在 AMPLS 中包含 Application Insights 資源及其相關聯的 Log Analytics 資源。新增之後，APIM 資料將成功內嵌至 Application Insights 資源，以解決遙測資料傳輸問題。

深入了解 Azure Application Insights。
考慮使用 Azure 事件中樞來進行記錄。
了解如何使用 Azure 受控 Grafana 從 Application Insights 將資料視覺化

共用方式為

如何整合 Azure API 管理與 Azure Application Insights

必要條件

案例概觀

使用 Azure 入口網站建立連線

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

使用連接字串搭配受控識別認證的記錄器 (建議)

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

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

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

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

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

哪些資料會新增至 Application Insights

發出自訂計量

自訂計量的限制

效能影響與記錄取樣

影片

疑難排解

意見反應

其他資源

共用方式為

如何整合 Azure API 管理與 Azure Application Insights

必要條件

案例概觀

使用 Azure 入口網站建立連線

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

使用連接字串搭配受控識別認證的記錄器 (建議)

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

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

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

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

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

哪些資料會新增至 Application Insights

發出自訂計量

自訂計量的限制

效能影響與記錄取樣

影片

疑難排解

相關內容

意見反應

其他資源