@azure/event-hubs

中文文档
6.0.4发布于 2026/04/23MITTypeScriptESM + CJS近 30 天下载 121.2万

(原始内容存档于2018-03-26) (英语). Azure Evention Hubs SDK for JS.

中文使用文档
文档目录20 节
  1. 开始
  2. 安装软件包
  3. 目前得到支持的环境
  4. 先决条件
  5. Java 脚本套装
  6. 反应原生支持
  7. 认证客户端
  8. 关键概念
  9. 关于复试的指导
  10. 实例
  11. 检查一个事件枢纽
  12. 将事件发布到事件中心
  13. 从事件中心接收事件
  14. 使用 EventHub 客户端与 IotHub 合作
  15. 解决问题
  16. AMQP 依赖关系
  17. 日志
  18. 今后的步骤
  19. 更多样本代码
  20. 捐款

JavaScript 的 Azure 事件枢纽客户端库

Azure Event Hubs是一种高度可扩展的出版订阅服务,每秒可以摄取上百万个事件并流到多个消费者. 这使得您可以处理和分析您连接的设备和应用程序所产生的大量数据. 如果你想了解更多有关Azure事件中心的信息,不妨回顾一下: 什么是活动中心? 吗?

Azure Event Hubs 客户端库允许您在节点.js应用程序中发送并接收事件.

密钥链接 :

页:1: 如果您正在使用2. 1.0 或 更低的版本并想要迁移到最新版本 这个包裹请看看我们 从事件Hubs V2到事件Hubs V5的迁移指南

V2的样本和文件在这里仍然可用:

V2.1.0 的源代码 | V2.1.0 (npm) 软件包 | V2.1.0样本

开始

安装软件包

使用 npm 安装 Azure 事件中心客户端库

npm install @azure/event-hubs

目前得到支持的环境

看我们的 支助政策 更多细节.

先决条件

配置类型脚本

TypeScript 用户需要安装节点类型定义 :

npm install @types/node

您还需要启用 compilerOptions.allowSyntheticDefaultImports 在你的Tsconfig.json中。 请注意, 如果您已启用 compilerOptions.esModuleInterop, (中文(简体) ), allowSyntheticDefaultImports 默认启用。 见 TypeScript 的编译器选项手册 更多信息.

Java 脚本套装

要在浏览器中使用此客户端库,首先需要使用捆绑器. 关于如何做到这一点的详情,请参见我们 捆绑文件。 。 。 .

除了上面描述的内容外,这个库还需要为以下节点JS核心内置模块增加多填充,以便在浏览器中正常工作: 1

  • buffer
  • os
  • path
  • process

装入 Webpack 软件包

如果您正在使用 Webpack v5, 您可以安装以下依赖性

  • npm install --save-dev os-browserify path-browserify

然后将以下内容添加到您的 webpack.config.js

 const path = require("path");
+const webpack = require("webpack");

 module.exports = {
   entry: "./src/index.ts",
@@ -12,8 +13,21 @@ module.exports = {
       },
     ],
   },
+  plugins: [
+    new webpack.ProvidePlugin({
+      process: "process/browser",
+    }),
+    new webpack.ProvidePlugin({
+      Buffer: ["buffer", "Buffer"],
+    }),
+  ],
   resolve: {
     extensions: [".ts", ".js"],
+    fallback: {
+      buffer: require.resolve("buffer/"),
+      os: require.resolve("os-browserify"),
+      path: require.resolve("path-browserify"),
+    },
   },

与滚滚相撞

如果您正在使用 Rollup 捆绑器, 请安装以下依赖性

  • npm install --save-dev @rollup/plugin-commonjs @rollup/plugin-inject @rollup/plugin-node-resolve

然后在您的滚动中包含以下内容

+import nodeResolve from "@rollup/plugin-node-resolve";
+import cjs from "@rollup/plugin-commonjs";
+import shim from "rollup-plugin-shim";
+import inject from "@rollup/plugin-inject";

export default {
  // other configs
  plugins: [
+    shim({
+      fs: `export default {}`,
+      net: `export default {}`,
+      tls: `export default {}`,
+      path: `export default {}`,
+      dns: `export function resolve() { }`,
+    }),
+    nodeResolve({
+      mainFields: ["module", "browser"],
+      preferBuiltins: false,
+    }),
+    cjs(),
+    inject({
+      modules: {
+        Buffer: ["buffer", "Buffer"],
+        process: "process",
+      },
+      exclude: ["./**/package.json"],
+    }),
  ]
};

请查看您最喜欢的捆绑者的文档, 了解使用多填充的更多信息 .

反应原生支持

与浏览器类似,React Introduct不支持这个SDK库使用的一些JavaScript API,所以需要为他们提供多填充. 请看 以 Expo 发布原始样本 更多细节.

认证客户端

与事件中心的互动始于其中任一实例 事件Hub 客户端 类 或实例 事件生成器 课. 有构造器超载支持这些类的不同即时化方式如下:

事件中心命名空间使用连接字符串

构造器中有一个超载 Endpoint=sb://my-servicebus-namespace.servicebus.windows.net/;SharedAccessKeyName=my-SA-name;SharedAccessKey=my-SA-key; 和实体名称到事件中心实例。 您可以创建消费组,并从中获取连接字符串以及实体名称 Azure 门户网站。 。 。 .

import { EventHubProducerClient, EventHubConsumerClient } from "@azure/event-hubs";

const producerClient = new EventHubProducerClient("my-connection-string", "my-event-hub");
const consumerClient = new EventHubConsumerClient(
  "my-consumer-group",
  "my-connection-string",
  "my-event-hub",
);

事件中心策略使用连接字符串

另一个构造器超载取取了与您在事件中心实例(而不是事件中心命名空间)上直接定义的共享访问策略相对应的连接字符串. 此连接字符串将属于形式 Endpoint=sb://my-servicebus-namespace.servicebus.windows.net/;SharedAccessKeyName=my-SA-name;SharedAccessKey=my-SA-key;EntityPath=my-event-hub-name。 。 。 . 连接字符串格式与前一个构建器超载的关键差异是 ;EntityPath=my-event-hub-name。 。 。 .

import { EventHubProducerClient, EventHubConsumerClient } from "@azure/event-hubs";

const producerClient = new EventHubProducerClient("my-connection-string-with-entity-path");
const consumerClient = new EventHubConsumerClient(
  "my-consumer-group",
  "my-connection-string-with-entity-path",
);

使用事件中心命名空间和 Azure 身份

此构建器超载会占用您 Event Hub 实例的主机名和实体名以及执行 Token 证书界面的证书 。 这允许您使用 Azure 活动目录主目录进行认证 。 已执行 TokenCredential 接口 @azure/身份 软件包。 主机名称为格式 <yournamespace>.servicebus.windows.net。当使用 Azure 活动目录时,您的主机必须被指定一个可以访问事件中心的角色,例如 Azure 事件中心数据拥有者角色。 关于使用Azure Active Directory授权的更多信息,请参见: 相关文件。 。 。 .

import { DefaultAzureCredential } from "@azure/identity";
import { EventHubProducerClient, EventHubConsumerClient } from "@azure/event-hubs";

const credential = new DefaultAzureCredential();
const producerClient = new EventHubProducerClient("my-host-name", "my-event-hub", credential);
const consumerClient = new EventHubConsumerClient(
  "my-consumer-group",
  "my-host-name",
  "my-event-hub",
  credential,
);

关键概念

  • 一个 活动中心制作人 是一种遥测数据,诊断信息,用法日志或其他日志数据的来源,作为嵌入式设备解决方案,移动设备应用程序,在控制台或其他设备上运行的游戏标题,一些基于客户端或服务器的业务解决方案,或者网站的一部分.

  • 一个 活动中心消费者 从活动中心收集此类信息并加以处理。 处理可能涉及汇总、复杂的计算和过滤。 处理还可能涉及以原始或转变的方式分发或储存信息。 事件中心消费者往往是具有内置分析能力的强大和高规模的平台基础设施部件,如Azure Stream Analytics、Apache Spark或Apache Storm.

  • A 类 分区 在事件中心举行的一系列活动。 分块是数据组织的一种手段,它与事件消费者所要求的平行性有关. Azure Event Hubs通过分割的消费者模式提供消息流,每个消费者只读取信息流的特定子集,即分区. 随着更新的事件到来,它们被加入到这个序列的结尾. 在事件枢纽创建时指定分区数,不能更改 .

  • A 类 消费群体 是整个事件中心的一个视图。 消费者群体能够使每个用户对事件流有单独的视图,并且能够按照自己的速度和位置独立地阅读流. 在每个消费群体中,最多可有5个同时配对的读者;然而,建议只有1个活跃的消费者进行特定的配对和消费群体配对。 每个活跃的读者都从其分区接收所有事件; 如果同一分区上有多个读者,那么他们会收到重复的事件.

关于更多概念和更深入的讨论,见: 活动中心特征

关于复试的指导

这个 EventHubConsumerClient 财务报告和审定财务报表 EventHubProducerClient 接受 options 在那里你可以设置 retryOptions 让你可以调谐SDK如何处理瞬间出错. 短暂错误的例子包括临时的网络或服务问题.

消耗事件时重复

如果在SDK接收事件时遇到瞬态错误(例如临时网络问题), 它将根据输入到 EventHubConsumerClient。 。 。 . 如果最大重试尝试已用尽 processError 函数将被引用.

您可以使用重试设置来控制您对临时问题的了解速度, 如 a 网络连接问题. 例如,如果您需要知道什么时候有网络问题,您可以立刻降低 数值 maxRetries 财务报告和审定财务报表 retryDelayInMs。 。 。 .

执行后 processError 函数,客户端继续接收分区中的事件 因为错误是可重试的。 否则,客户端会引用用户提供的 processClose 函数. 当您停止订阅或客户端停止阅读时,此功能也会被引用 当前分区中由于它而被您申请的另一个实例所取出的事件 作为负载平衡的一部分.

这个 processClose 职能为在必要时更新检查站提供了机会. 执行后 processClose,客户端(或在负载平衡的情况下, 来自您应用程序中另一个实例的客户端)将引用用户提供的 processInitialize 函数以恢复同一分区上次更新的检查点的读取事件.

如果你想停止尝试阅读事件, 你必须打电话 close() 编辑 subscription 已返回 编辑 subscribe 方法.

实例

以下各节提供代码片段,以使用 Azure 事件中心来覆盖一些常见任务

检查一个事件枢纽

许多事件中心业务是在具体分区范围内进行的. 由于分区由事件枢纽拥有,因此其名称在创建时被指定. 要了解什么是可用的分区, 您可以使用可用的两个客户端中的任何一个查询事件枢纽 : EventHubProducerClient 或者说 EventHubConsumerClient

在以下例子中,我们使用 EventHubProducerClient。 。 。 .

import { EventHubProducerClient } from "@azure/event-hubs";

const client = new EventHubProducerClient("connectionString", "eventHubName");

const partitionIds = await client.getPartitionIds();

await client.close();

将事件发布到事件中心

为了公布事件,你需要建立一个 EventHubProducerClient。以下示例显示了创建客户端的一种方法,请参见 认证客户端 用于学习其他即时处理客户端的方法.

您可以将事件发布到特定的分区, 或者允许事件中心服务决定应该发布哪些分区事件 。 建议在事件出版需要高度可用或事件数据应在分区间均匀分布时使用自动路由. 在下面的例子中,我们将利用自动线路.

  • 创建一个 EventDataBatch 对象使用 创建批次
  • 使用 尝试添加 方法。 您可以做到这一点, 直到达到最大批量大小限制, 或者直到您完成添加您喜欢的事件数, 以先到者为准 。 这种方法将会回归 false 以表示由于达到最大批量尺寸而无法在批量中添加任何事件.
  • 使用 发送批次 方法.

在下面的例子中,我们试图向Azure活动中心发送10项活动.

import { EventHubProducerClient } from "@azure/event-hubs";

const producerClient = new EventHubProducerClient("connectionString", "eventHubName");

const eventDataBatch = await producerClient.createBatch();
let numberOfEventsToSend = 10;

while (numberOfEventsToSend > 0) {
  const wasAdded = eventDataBatch.tryAdd({ body: "my-event-body" });
  if (!wasAdded) {
    break;
  }
  numberOfEventsToSend--;
}

await producerClient.sendBatch(eventDataBatch);
await producerClient.close();

在不同阶段可以通过一些选项来控制向Azure事件中心发送事件的过程.

  • 这个 EventHubProducerClient 构造器需要类型的可选参数 EventHubClientOptions 用于指定复试次数等选项.
  • 这个 createBatch 方法需要类型的可选参数 CreateBatchOptions 可以用来预测由正在创建的批次所支持的最大批次大小.
  • 这个 sendBatch 方法需要类型的可选参数 SendBatchOptions 用于指定 abortSignal 以取消当前操作.
  • 如果您想要发送到特定的分区, 超载的 sendBatch 方法允许您通过分区的id来发送事件. 这个 检查一个事件枢纽 以上示例显示如何获取可用的分区 id.

说明:在与Azure Stream Analytics合作时,被发送的事件体也应该是JSON对象. 例如: body: { "message": "Hello World" }

从事件中心接收事件

要消耗事件中心的事件, 您还需要知道您想要针对哪个消费者群体. 一旦你意识到这一点, 你准备创建一个 事件Hub 客户端。以下示例显示了创建客户端的一种方法,请参见 认证客户端 用于学习其他即时处理客户端的方法.

这个 subscribe 客户端上的方法有超载性,与构造器结合,可以满足几个 消耗事件的方式:

这个 subscribe 方法需要类型的可选参数 SubscriptionOptions 用于指定选项,例如最大批量Size(等待的事件数)和最大等时间Inseconds(等待最大批量Size事件到达的时间数).

在一个单一进程中完成事件

从创建实例开始 EventHubConsumerClient,然后调用 subscribe() 启动方法 消费事件.

这个 subscribe 方法在从Azure事件枢纽接收事件时会召回处理事件. 为了停止接收事件,你可以打电话 close() 上标注 subscribe() 方法.

import { EventHubConsumerClient, earliestEventPosition } from "@azure/event-hubs";

const client = new EventHubConsumerClient("my-consumer-group", "connectionString", "eventHubName");

// In this sample, we use the position of earliest available event to start from
// Other common options to configure would be `maxBatchSize` and `maxWaitTimeInSeconds`
const subscriptionOptions = {
  startPosition: earliestEventPosition,
};

const subscription = client.subscribe(
  {
    processEvents: async (events, context) => {
      // event processing code goes here
    },
    processError: async (err, context) => {
      // error reporting/handling code here
    },
  },
  subscriptionOptions,
);

// Wait for a few seconds to receive events before closing
setTimeout(async () => {
  await subscription.close();
  await client.close();
  console.log(`Exiting sample`);
}, 3 * 1000);

承担多个进程均匀负荷的事件

Azure事件中心每秒能处理上百万起事件. 要缩放您的处理应用程序, 您可以运行多个应用程序实例, 并让它们相互平衡负载 .

从创建实例开始 EventHubConsumerClient 使用其中的 构造器超载 CheckpointStore,然后调用 subscribe() 开始消耗事件的方法。 检查站商店可以让订户入住 在一个消费群体内协调多个实例之间的处理 您的申请.

在这个例子中,我们将使用 BlobCheckpointStore 从 @azure/eventhubs-checkpointstore-blob 软件包 使用 Azure Blob 存储器执行所需的读取/写入持久存储器.

这个 subscribe 方法在从Azure事件枢纽接收事件时会召回处理事件. 为了停止接收事件,你可以打电话 close() 上标注 subscribe() 方法.

import { ContainerClient } from "@azure/storage-blob";
import { BlobCheckpointStore } from "@azure/eventhubs-checkpointstore-blob";
import { EventHubConsumerClient } from "@azure/event-hubs";

const storageAccountConnectionString = "storage-account-connection-string";
const containerName = "container-name";
const eventHubConnectionString = "eventhub-connection-string";
const consumerGroup = "my-consumer-group";
const eventHubName = "eventHubName";

const blobContainerClient = new ContainerClient(storageAccountConnectionString, containerName);

if (!(await blobContainerClient.exists())) {
  await blobContainerClient.create();
}

const checkpointStore = new BlobCheckpointStore(blobContainerClient);
const consumerClient = new EventHubConsumerClient(
  consumerGroup,
  eventHubConnectionString,
  eventHubName,
  checkpointStore,
);

const subscription = consumerClient.subscribe({
  processEvents: async (events, context) => {
    // event processing code goes here
    if (events.length === 0) {
      // If the wait time expires (configured via options in maxWaitTimeInSeconds) Event Hubs
      // will pass you an empty array.
      return;
    }

    // Checkpointing will allow your service to pick up from
    // where it left off when restarting.
    //
    // You'll want to balance how often you checkpoint with the
    // performance of your underlying checkpoint store.
    await context.updateCheckpoint(events[events.length - 1]);
  },
  processError: async (err, context) => {
    // handle any errors that occur during the course of
    // this subscription
    console.log(`Errors in subscription to partition ${context.partitionId}: ${err}`);
  },
});

// Wait for a few seconds to receive events before closing
await new Promise((resolve) => setTimeout(resolve, 10 * 1000));

await subscription.close();
await consumerClient.close();
console.log(`Exiting sample`);

请看 在应用程序的多个实例中平衡分区负载 学习更多.

从一个分区控制事件

从创建实例开始 EventHubConsumerClient,然后调用 subscribe() 启动方法 消费事件。 将您想要瞄准的分区的 ID 传递到 subscribe() 仅使用该分区的方法.

在下面的例子中,我们正在使用第一个分区.

这个 subscribe 方法在从Azure事件枢纽接收事件时会召回处理事件. 为了停止接收事件,你可以打电话 close() 上标注 subscribe() 方法.

import { EventHubConsumerClient, earliestEventPosition } from "@azure/event-hubs";

const client = new EventHubConsumerClient("my-consumer-group", "connectionString", "eventHubName");
const partitionIds = await client.getPartitionIds();

// In this sample, we use the position of earliest available event to start from
// Other common options to configure would be `maxBatchSize` and `maxWaitTimeInSeconds`
const subscriptionOptions = {
  startPosition: earliestEventPosition,
};

const subscription = client.subscribe(
  partitionIds[0],
  {
    processEvents: async (events, context) => {
      // event processing code goes here
    },
    processError: async (err, context) => {
      // error reporting/handling code here
    },
  },
  subscriptionOptions,
);

// Wait for a few seconds to receive events before closing
setTimeout(async () => {
  await subscription.close();
  await client.close();
  console.log(`Exiting sample`);
}, 3 * 1000);

使用 EventHub 客户端与 IotHub 合作

你用得着 EventHubConsumerClient 也和IotHub一起工作。 这对于从相联事件Hub接收IotHub的遥测数据很有用. 关联的连接字符串将不会发送请求, 因此无法发送事件.

  • 请注意连接字符串需要为 事件中心兼容终点 (例如"endpoint=sb://my-iothub-namespace-[uid]. servicebus.windows.net/;SharedAccessKeyName=My-SA-name;SharedAccessKey=My-SA-key;实体Path=My-iot-hub-name")
import { EventHubConsumerClient } from "@azure/event-hubs";

const client = new EventHubConsumerClient(
  "my-consumer-group",
  "Endpoint=sb://my-iothub-namespace-[uid].servicebus.windows.net/;SharedAccessKeyName=my-SA-name;SharedAccessKey=my-SA-key;EntityPath=my-iot-hub-name",
);

await client.getEventHubProperties();

// retrieve partitionIds from client.getEventHubProperties() or client.getPartitionIds()
const partitionId = "0";
await client.getPartitionProperties(partitionId);

await client.close();

解决问题

AMQP 依赖关系

活动中心图书馆取决于 rhea - 保证 用于管理连接、发送和接收事件的数据库 AMQP 调试 协议.

日志

你可以设置 AZURE_LOG_LEVEL 环境变量使日志能够 stderr数字 :

export AZURE_LOG_LEVEL=verbose

也可以在运行时通过呼叫启用日志 setLogLevel 输入 @azure/logger数字 :

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

关于如何启用日志的更详细指示,您可以查看 @ azure/ logger 包文件。 。 。 .

你可以选择设置 DEBUG 使用此库时获取日志的环境变量. 如果您也想要从依赖源中发送日志, 这将有所帮助 rhea-promise 财务报告和审定财务报表 rhea 还有.

说明: AZURE LOG LEVEL 如果设定,则优先于DEBUG. 不指定任何 azure 当同时指定时, 通过 DEBUG 的库 AZURE LOG LEVEL 或调用 setLOGLE.

  • 从事件中心SDK只获取信息级别调试日志 .
export DEBUG=azure:*:info
  • 从事件中心SDK和协议级别库获取调试日志 .
export DEBUG=azure*,rhea*
  • 如果你是的话 对查看原始事件数据不感兴趣 (它消耗了大量控制台/磁盘空间)然后可以设置 DEBUG 环境变量如下:
export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message
  • 如果你只对 错误 和 SDK 数据 警告,然后可以设置 DEBUG 环境变量如下:
export DEBUG=azure:*:(error|warning),rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

今后的步骤

更多样本代码

请看一下 样本 关于如何使用此库发送和接收事件的详细示例的目录 活动中心。 。 。 .

捐款

如果您想为图书馆捐钱 请读一下 贡献指南 学习如何构建和测试密码.

版本与发布记录

@azure/event-hubs 共发布 684 个版本,首次发布于 2018/09/13;过去 12 个月发布了 54 个版本。

版本发布日期距今
6.0.4latest2026/04/236 个月前
6.0.4-alpha.20260310.1dev2026/03/117 个月前
6.0.4-alpha.20260309.12026/03/107 个月前
6.0.4-alpha.20260306.12026/03/078 个月前
6.0.4-alpha.20260305.22026/03/068 个月前
6.0.4-alpha.20260304.22026/03/058 个月前

关于 @azure/event-hubs 的常见问题

@azure/event-hubs 是什么?

(原始内容存档于2018-03-26) (英语). Azure Evention Hubs SDK for JS.

如何安装 @azure/event-hubs?

在项目目录运行 npm install @azure/event-hubs,或使用 pnpm add / yarn add / bun add。

@azure/event-hubs 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@azure/event-hubs 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@azure/event-hubs 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@azure/event-hubs 可以商用吗?

@azure/event-hubs 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@azure/event-hubs 的下载量有多少?

根据 npm 官方下载统计,@azure/event-hubs 在 2026/10/08 – 2026/11/06 这 30 天内被下载 1,212,321 次,日均约 40,411 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@azure/event-hubs 还在维护吗?

最新版本 6.0.4 发布于 2026/04/23(6 个月前);至今共发布 684 个版本,其中过去 12 个月发布了 54 个;首次发布于 2018/09/13。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。