如何在 Azure API 管理中将事件记录到 Azure 事件中心

项目
10/24/2024

适用于：所有 API 管理层级

本文介绍如何使用 Azure 事件中心记录 API 管理事件。

事件中心是一个高度可缩放的引入服务，每秒可以引入数百万的事件，使用户能够处理和分析连接设备和应用程序生成的海量数据。事件中心充当事件管道的“前门”，将数据收集到事件中心后，可以使用任何实时分析提供程序或批处理/存储适配器来转换和存储这些数据。事件中心可将事件流的生成与这些事件的使用分离开来，因此，事件使用者可以根据自己的计划访问事件。

先决条件

API Management 服务实例。如果没有，请参阅创建 API 管理服务实例。
Azure 事件中心命名空间和事件中心。有关详细步骤，请参阅使用 Azure 门户创建事件中心命名空间和事件中心。

注意

事件中心资源可位于不同的订阅中，也可位于不同于 API 管理资源的租户

配置对事件中心的访问权限

若要将事件记录到事件中心，需要配置凭据以便从API 管理进行访问。 API 管理支持使用以下任意一种访问机制：

供 API 管理实例使用的托管标识（推荐）
事件中心连接字符串

注意

如果可能，Microsoft 建议使用托管标识凭据以增强安全性。

选项 1：配置 API 管理托管标识

在 API 管理实例中为 API 管理启用系统分配的托管标识或用户分配的托管标识。
- 如果启用用户分配的托管标识，请记下该标识的“客户端 ID”。
为标识分配 Azure 事件中心数据发送者角色，范围限定为事件中心命名空间或用于记录的事件中心。若要分配角色，请使用 Azure 门户或其他 Azure 工具。

选项 2：配置事件中心连接字符串

有关事件中心连接字符串的详细信息，请参阅获取事件中心连接字符串。

连接字符串既可以供事件中心命名空间使用，也可以供用于从 API 管理进行记录的特定事件中心所使用。
连接字符串的共享访问策略必须至少启用“发送”权限。

创建 API 管理记录器

下一步是在 API 管理服务中配置记录器，以便它可以将事件记录到事件中心。

直接使用 API 管理 REST API 或使用工具（包括 Azure PowerShell、Bicep 模板或 Azure 资源管理模板）创建和管理 API 管理记录器。

选项 1：使用托管标识凭据的记录器（推荐）

可使用系统分配的或用户分配的托管标识凭据将 API 管理记录器配置到事件中心。

包含系统分配的托管标识凭据的记录器

如需了解先决条件，请参阅配置API 管理托管标识。

使用包含以下请求正文的 API 管理记录器 - 创建或更新 REST API。

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

在 Bicep 模板中包含类似于以下内容的代码片段。

resource ehLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  properties: {
    loggerType: 'azureEventHub'
    description: 'Event hub logger with system-assigned managed identity'
    credentials: {
      endpointAddress: '<EventHubsNamespace>.servicebus.chinacloudapi.cn'
      identityClientId: 'systemAssigned'
      name: '<EventHubName>'
    }
  }
}

在 Azure 资源管理器模板中包含类似于以下内容的 JSON 代码片段。

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "azureEventHub",
    "description": "Event Hub logger with system-assigned managed identity",
    "resourceId": "<EventHubsResourceID>",
    "credentials": {
      "endpointAddress": "<EventHubsNamespace>.servicebus.chinacloudapi.cn",
      "identityClientId": "SystemAssigned",
      "name": "<EventHubName>"
    },
  }
}

包含用户分配的托管标识凭据的记录器

如需了解先决条件，请参阅配置API 管理托管标识。

使用包含以下请求正文的 API 管理记录器 - 创建或更新 REST API。

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

在 Bicep 模板中包含类似于以下内容的代码片段。

resource ehLoggerWithUserAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  properties: {
    loggerType: 'azureEventHub'
    description: 'Event Hub logger with user-assigned managed identity'
    credentials: {
      endpointAddress: '<EventHubsNamespace>.servicebus.chinacloudapi.cn'
      identityClientId: '<ClientID>'
      name: '<EventHubName>'
    }
  }
}

在 Azure 资源管理器模板中包含类似于以下内容的 JSON 代码片段。

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "azureEventHub",
    "description": "Event Hub logger with user-assigned managed identity",
    "resourceId": "<EventHubsResourceID>",
    "credentials": {
      "endpointAddress": "<EventHubsNamespace>.servicebus.chinacloudapi.cn",
      "identityClientId": "<ClientID>",
      "name": "<EventHubName>"
    },
  }
}

选项 2. 包含连接字符串凭据的记录器

如需了解先决条件，请参阅配置事件中心连接字符串。

注意

如果可能，Microsoft 建议使用托管标识凭据配置记录器。请参阅本文前面的“使用托管标识凭据配置记录器”。

以下示例使用 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.chinacloudapi.cn/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<key>" -Description "Event hub logger with connection string"

在 Bicep 模板中包含类似于以下内容的代码片段。

resource ehLoggerWithConnectionString 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  properties: {
    loggerType: 'azureEventHub'
    description: 'Event Hub logger with connection string credentials'
    credentials: {
      connectionString: 'Endpoint=sb://<EventHubsNamespace>.servicebus.chinacloudapi.cn/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<key>'
      name: 'ApimEventHub'
    }
  }
}

在 Azure 资源管理器模板中包含类似于以下内容的 JSON 代码片段。

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "azureEventHub",
    "description": "Event Hub logger with connection string credentials",
    "resourceId": "<EventHubsResourceID>"
    "credentials": {
      "connectionString": "Endpoint=sb://<EventHubsNamespace>/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<key>",
      "name": "ApimEventHub"
    },
  }
}

配置 log-to-eventhub 策略

在 API 管理中配置了记录器后，就可以配置 log-to-eventhub 策略以记录所需事件。例如，使用 log-to-eventhub 入站策略部分中的策略来记录请求，或在出站策略部分中使用策略来记录响应。

浏览到 API 管理实例。
选择 API，然后选择要将策略添加到的 API。在此示例中，我们向 Unlimited 产品中的 Echo API 添加策略。
选择“所有操作”。
选择屏幕顶部的“设计”选项卡。
在“入站处理”或“出站处理”窗口中，选择 </>（代码编辑器）图标。有关详细信息，请参阅如何设置或编辑策略。
将光标放在 inbound 或 outbound 策略部分中。

在右侧窗口中，选择“高级策略”>“记录到 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>

将 logger-id 替换为在上一步中创建的 JSON 文件的名称。
可使用返回字符串作为 log-to-eventhub 元素值的任何表达式。在此示例中，将记录一个 JSON 格式的字符串，其中包含日期和时间、服务名称、请求 ID、请求 IP 地址和操作名称。

选择“保存”保存更新后的策略配置。保存后，策略立即处于活动状态，并且事件记录到指定的事件中心。

注意

允许从此 API 管理策略发送到事件中心的最大消息大小为 200 KB。如果发送到事件中心的消息大于 200 KB，系统会自动截断该消息，而截断的消息则会传输到事件中心。对于较大的消息，请考虑将 Azure 存储与 Azure API 管理结合使用，以此作为绕过 200KB 限制的解决方法。

使用 Azure 流分析在事件中心预览日志

可以使用 Azure 流分析查询来预览事件中心中的日志。

在 Azure 门户中，浏览到记录器发送事件到的事件中心。
在“功能”下，选择“处理数据”选项卡。
在“启用来自事件的实时见解”卡片上选择“开始”。
可以在“输入预览”选项卡上预览日志。如果显示的数据不是最新的，请选择“刷新”查看最新事件。

后续步骤

了解有关 Azure 事件中心的详细信息
- Azure 事件中心入门
- 使用 EventProcessorHost 接收消息
了解有关 API 管理和事件中心集成的详细信息
- 记录器实体引用
- log-to-eventhub 策略引用
详细了解如何与 Azure Application Insights 集成

通过

如何在 Azure API 管理中将事件记录到 Azure 事件中心

先决条件

配置对事件中心的访问权限

选项 1：配置 API 管理托管标识

选项 2：配置事件中心连接字符串

创建 API 管理记录器

选项 1：使用托管标识凭据的记录器（推荐）

包含系统分配的托管标识凭据的记录器

包含用户分配的托管标识凭据的记录器

选项 2. 包含连接字符串凭据的记录器

配置 log-to-eventhub 策略

使用 Azure 流分析在事件中心预览日志

后续步骤

其他资源