通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

适用于：所有 API 管理层级

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

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

注意

目前无法在工作区中使用此功能。

Prerequisites

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

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

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

注意

建议尽可能使用托管标识凭据来提高安全性。

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

  1. 在 API 管理实例中为 API 管理启用系统分配的托管标识或用户分配的托管标识。

    • 如果启用用户分配的托管标识，请记下该标识 的对象 ID。

  2. 为标识分配 Azure 事件中心数据发送者角色，范围限定为事件中心命名空间或用于记录的事件中心。 若要分配角色，请使用 Azure 门户 或其他 Azure 工具。

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

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

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

创建 API 管理记录器

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

直接使用 API 管理 REST API 或使用其他工具（例如 Azure PowerShell、Bicep 文件或 Azure 资源管理模板）创建和管理 API 管理记录器。

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

使用系统分配的托管标识凭据创建记录器

有关先决条件，请参阅 配置 API 管理托管标识。

使用包含以下请求正文的 API 管理记录器 - 创建或更新 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 管理托管标识。

使用包含以下请求正文的 API 管理记录器 - 创建或更新 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"

配置日志到事件中心策略

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

  1. 转到 API 管理实例。

  2. 在 API 下，选择 API，然后选择要将策略添加到的 API。 在此示例中，我们向 Unlimited 产品中的 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 替换为在上一步中创建的 JSON 文件的名称。
    2. 可使用返回字符串作为 log-to-eventhub 元素值的任何表达式。 在此示例中，将记录一个 JSON 格式的字符串，其中包含日期和时间、服务名称、请求 ID、请求 IP 地址和操作名称。

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

注意

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

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

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

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

相关内容