如何將事件記錄到 Azure API 管理中的 Azure 事件中樞

  • 發行項

適用於：所有 API 管理 層

本文描述如何使用 Azure 事件中樞記錄 API 管理事件。

事件中樞是可高度調整的資料輸入服務，每秒可擷取數百萬個事件，可讓您處理和分析連接的裝置和應用程式所產生的大量資料。 事件中樞能做為事件管線的「大門」，一旦收集的資料進入事件中樞，它可以使用任何即時分析提供者或批次/儲存配接器轉換及儲存資料。 事件中樞能分隔事件串流的生產與這些事件的使用，讓事件消費者依照自己的排程存取事件。

必要條件

設定存取事件中樞

若要將事件記錄至事件中樞，您必須設定要用於從 APIM 存取的認證。 APIM 支援下列兩種存取機制之一：

  • 事件中樞連接字串
  • 適用於 APIM 執行個體的受控識別。

選項 1：設定事件中樞連接字串

若要建立事件中樞連接字串，請參閱取得事件中樞連接字串。

  • 您可以針對事件中樞命名空間，或針對用於從 APIM 記錄的特定事件中樞，使用連接字串。
  • 連接字串的共用存取原則至少必須啟用傳送權限。

選項 2：設定 APIM 受控識別

注意

APIM REST API 版本 2022-04-01-preview 或更新版本支援使用 APIM 受控識別來將事件記錄到事件中樞。

  1. 在 API 管理執行個體中，啟用系統指派或使用者指派之適用於 API 管理的受控識別。

    • 如果您啟用使用者指派的受控識別，請記下身分識別的用戶端識別碼。

  2. 為身分識別指派 Azure 事件中樞資料傳送者角色，並將範圍限定為事件中樞命名空間或用於記錄的事件中樞。 若要指派角色，請使用 Azure 入口網站或其他 Azure 工具。

建立 API 管理記錄器

下一個步驟是在 APIM 服務中設定記錄器，如此便可將事件記錄至事件中樞。

直接使用 APIM REST API，或使用包括 Azure PowerShell、Bicep 範本或 Azure 資源管理範本在內的工具，來建立和管理 APIM 記錄器。

具有連接字串認證的記錄器

如需必要條件，請參閱設定事件中樞連接字串。

下列範例使用 New-AzApiManagementLogger Cmdlet，透過設定連接字串來建立事件中樞的記錄器。

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# Create logger
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName
New-AzApiManagementLogger -Context $context -LoggerId "ContosoLogger1" -Name "ApimEventHub" -ConnectionString "Endpoint=sb://<EventHubsNamespace>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<key>" -Description "Event hub logger with connection string"

具有系統指派受控識別認證的記錄器

如需必要條件，請參閱設定 APIM 受控識別。

使用 APIM REST API 或是 Bicep 或 ARM 範本，使用系統指派的受控識別認證來將記錄器設定到事件中樞。

{
  "properties": {
    "loggerType": "azureEventHub",
    "description": "adding a new logger with system assigned managed identity",
    "credentials": {
         "endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
         "identityClientId":"SystemAssigned",
         "name":"<EventHubName>"
    }
  }
}

具有使用者指派受控識別認證的記錄器

如需必要條件，請參閱設定 APIM 受控識別。

使用 APIM REST API 或是 Bicep 或 ARM 範本，使用使用者指派的受控識別認證來將記錄器設定到事件中樞。

{
  "properties": {
    "loggerType": "azureEventHub",
    "description": "adding a new logger with user-assigned managed identity",
    "credentials": {
         "endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
         "identityClientId":"<ClientID>",
         "name":"<EventHubName>"
    }
  }
}

設定 log-to-eventhub 原則

當您在 APIM 中設定記錄器之後，便可設定 log-to-eventhub 原則來記錄所需的事件。 例如，在輸入原則區段中使用 log-to-eventhub 原則來記錄要求，或在輸出原則區段中記錄回應。

  1. 瀏覽至您的 API 管理執行個體。

  2. 選取 [API]，然後選取您要新增原則的 API。 在此範例中，我們將原則新增至 [無限制] 產品中的 [Echo API]。

  3. 選取 [所有作業]。

  4. 選取畫面頂端的 [設計] 索引標籤。

  5. 在 [輸入處理] 或 [輸出處理] 視窗中，選取 </> (程式碼編輯器) 圖示。 如需詳細資訊，請參閱如何設定或編輯原則。

  6. 將游標置於 inbound 或 outbound 原則區段。

  7. 在右側視窗中，選取 [進階原則]>[登入 EventHub]。 這會插入 log-to-eventhub 原則陳述式範本。

    <log-to-eventhub logger-id="logger-id">
    @{
        return new JObject(
            new JProperty("EventTime", DateTime.UtcNow.ToString()),
            new JProperty("ServiceName", context.Deployment.ServiceName),
            new JProperty("RequestId", context.RequestId),
            new JProperty("RequestIp", context.Request.IpAddress),
            new JProperty("OperationName", context.Operation.Name)
        ).ToString();
    }
</log-to-eventhub>
    1. 使用您在上一個步驟中建立的記錄器名稱來取代 logger-id。
    2. 您可以使用任何能傳回字串做為 log-to-eventhub 項目之值的運算式。 在此範例中，會記錄包含日期和時間、服務名稱、要求識別碼、要求 IP 位址和作業名稱的字串 (JSON 格式)。

  8. 選取 [儲存] 來儲存更新的原則設定。 儲存完成之後，原則即會處於使用中狀態，並將事件記錄至指定的事件中樞。

注意

此 API 管理原則可傳送至事件中樞的支援訊息大小上限為 200 千位元組 (KB)。 如果傳送至事件中樞的訊息大於 200 KB，即會自動截斷，而截斷的訊息將會傳輸至事件中樞。 針對較大的訊息，請考慮搭配 Azure API 管理 使用 Azure 儲存體 作為略過 200KB 限制的因應措施。 如需詳細資訊，請參閱 這篇文章。

使用 Azure 串流分析來預覽事件中樞的記錄

您可以使用 Azure 串流分析查詢來預覽事件中樞的記錄。

  1. 在 Azure 入口網站中，瀏覽至記錄器傳送事件至的事件中樞。
  2. 在 [功能] 下，選取 [處理資料] 索引標籤。
  3. 在 [允許即時從事件擷取見解] 卡片上，選取 [開始]。
  4. 您應該能夠在 [輸入預覽] 索引標籤上預覽記錄。如果顯示的資料不是最新的，請選取 [重新整理] 以查看最新的事件。

下一步