共用方式為

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

適用於：所有 APIM 層

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

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

附註

目前，此功能無法在工作區中使用。

先決條件

設定存取事件中樞

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

  • 適用於 APIM 執行個體的受控識別 (推薦項目)
  • 事件中樞連接字串

附註

建議您盡可能使用受控識別認證，以增強安全性。

選項 1：設定 API 管理 受控識別

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

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

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

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

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

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

建立 API 管理記錄器

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

直接使用 API 管理 REST API 或使用其他工具 （ 例如 Azure PowerShell、Bicep 檔案或 Azure 資源管理範本） 來建立和管理 API 管理記錄器。

您可以使用系統指派或使用者指派的受控識別認證，將 API 管理 記錄器設定為事件中樞。

使用系統指派的受控識別認證建立記錄器

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

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

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

使用使用者指派的受控識別認證建立記錄器

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

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

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

選項 2。 使用連接字串認證建立記錄器

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

附註

建議您盡可能使用受控識別認證來設定記錄器。 請參閱本文稍早的設定使用受控身份認證的記錄器。

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

# Details specific to API Management 
$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"

設定 log-to-eventhub 原則

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

  1. 移至您的 API 管理實例。

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

  3. 在 [設計 ] 索引標籤上，選取 [所有作業]。

  4. 在 [ 輸入處理 ] 或 [輸出處理 ] 窗格中，選取 </> （原則代碼編輯器） 按鈕。 如需詳細資訊，請參閱如何設定或編輯原則。

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

  6. 選取索引標籤頂端的 顯示程式碼片段。選取 進階原則>記錄至 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 格式)。

  7. 選取 [儲存] 來儲存更新的原則設定。 儲存設定後，原則就會處於作用中狀態，且事件會記錄到指定的事件中樞。

附註

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

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

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

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

相關內容

  • Last updated on