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

适用于 JavaScript 的Azure 事件网格客户端库 - 版本 5.1.0-beta.1

Azure 事件网格是基于云的服务，可提供大规模可靠的事件传送。

使用客户端库可以执行以下操作：

• 使用事件网格、云事件 1.0 架构或自定义架构将事件发送到事件网格
• 解码和处理传递到事件网格处理程序的事件
• 为事件网格主题生成共享访问签名

关键链接：

• 源代码
• 包 (NPM)
• API 参考文档
• 产品文档
• 示例

入门

目前支持的环境

• LTS 版本的 Node.js
• 最新版本的 Safari、Chrome、Edge 和 Firefox。

有关更多详细信息，请参阅我们的支持政策。

先决条件

• 一个 Azure 订阅。
• 现有 事件网格 主题或域。 如果需要创建资源，可以使用 Azure 门户 或 Azure CLI。

如果使用 Azure CLI，请将 和 <your-resource-name> 替换为<your-resource-group-name>自己的唯一名称：

创建事件网格主题

az eventgrid topic create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

创建事件网格域

az eventgrid domain create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

安装 @azure/eventgrid 包

使用 npm安装适用于 JavaScript 的 Azure 事件网格 客户端库：

npm install @azure/eventgrid

创建 EventGridPublisherClient 并对其进行身份验证

若要创建客户端对象来访问事件网格 API，需要 endpoint 事件网格主题的 和 credential。 事件网格客户端可以使用访问密钥或共享访问签名 (从访问密钥创建的 SAS) 。

可以在 Azure 门户 或使用以下 Azure CLI 代码片段中找到事件网格主题的终结点：

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

使用访问密钥

使用 Azure 门户 浏览到事件网格资源并检索访问密钥，或使用下面的 Azure CLI 代码片段：

az eventgrid topic key list --resource-group <your-resource-group-name> --name <your-event-grid-topic-name>

拥有 API 密钥和终结点后，可以使用 AzureKeyCredential 类对客户端进行身份验证，如下所示：

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureKeyCredential("<Access Key>")
);

使用 SAS 令牌

与访问密钥一样，SAS 令牌允许访问将事件发送到事件网格主题。 与访问密钥不同，SAS 令牌在重新生成之前可以使用，SAS 令牌有一个加速时间，此时它不再有效。 若要使用 SAS 令牌进行身份验证，请使用 ， AzureSASCredential 如下所示：

const { EventGridPublisherClient, AzureSASCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureSASCredential("<SAS Token>")
);

可以使用 函数生成 SAS 令牌 generateSharedAccessSigniture 。

const { generateSharedAccessSignature, AzureKeyCredential } = require("@azure/eventgrid");

// Create a SAS Token which expires on 2020-01-01 at Midnight.
const token = generateSharedAccessSignature(
  "<endpoint>",
  new AzureKeyCredential("<API key>"),
  new Date("2020-01-01T00:00:00")
);

使用 Azure Active Directory (AAD)

Azure EventGrid 提供与 Azure Active Directory (Azure AD) 的集成，以便对请求进行基于标识的身份验证。 借助 Azure AD，可以使用基于角色的访问控制 (RBAC) 向用户、组或应用程序授予对Azure 事件网格资源的访问权限。

若要使用 TokenCredential将事件发送到主题或域，应为经过身份验证的标识分配“EventGrid 数据发送者”角色。

借助该 @azure/identity 包，可以在开发和生产环境中无缝授权请求。 若要详细了解 Azure Active Directory，请参阅 @azure/identity 自述文件。

例如，可以使用 DefaultAzureCredential 来构造将使用 Azure Active Directory 进行身份验证的客户端：

const { EventGridPublisherClient } = require("@azure/eventgrid");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new DefaultAzureCredential()
);

关键概念

EventGridPublisherClient

EventGridPublisherClient 用于将事件发送到事件网格主题或事件网格域。

事件架构

事件网格支持多个架构来编码事件。 创建自定义主题或域时，可以指定发布事件时将使用的架构。 虽然可以将主题配置为使用 自定义架构 ，但使用已定义的 事件网格架构 或 CloudEvents 1.0 架构更为常见。 CloudEvents 是一个云原生计算基础项目，它生成用于以通用方式描述事件数据的规范。 构造 EventGridPublisherClient 时，必须指定主题配置为使用的架构：

如果主题配置为使用事件网格架构，请将“EventGrid”设置为架构类型：

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API Key>")
);

如果主题配置为使用云事件架构，请将“CloudEvent”设置为架构类型：

const client = new EventGridPublisherClient(
  "<endpoint>",
  "CloudEvent",
  new AzureKeyCredential("<API Key>")
);

如果主题配置为使用自定义事件架构，请将“自定义”设置为架构类型：

const client = new EventGridPublisherClient(
  "<endpoint>",
  "Custom",
  new AzureKeyCredential("<API Key>")
);

使用与主题所预期的架构不同的架构构造客户端将导致服务出错，并且不会发布事件。

可以使用下面的 Azure CLI 代码片段查看为事件网格主题配置了哪些输入架构：

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "inputSchema"

EventGridDeserializer

事件网格传递给使用者的事件以 JSON 的形式传递。 根据要传递到的使用者类型，事件网格服务可能会将一个或多个事件作为单个有效负载的一部分传递。 虽然这些事件可以使用普通 JavaScript 方法（如 JSON.parse）进行反序列化，但此库提供了用于反序列化事件的帮助程序类型，称为 EventGridDeserializer。

与直接使用 JSON.parse 相比， EventGridDeserializer 在反序列化事件时执行一些额外的转换：

1. EventGridDeserializer 验证事件的必需属性是否存在以及是否为正确的类型。
2. EventGridDeserializer 将事件时间属性转换为 JavaScript Date 对象。
3. 使用云事件时，二进制数据可用于使用) (Uint8Array 事件的数据属性。 当事件通过事件网格发送时，它将在 Base 64 中编码。 EventGridDeserializer 将此数据解码回 的 Uint8Array实例。
4. 反序列化 系统事件 (另一个 Azure 服务) 生成的事件时， EventGridDeserializer 将执行其他转换，以便 data 对象与描述其数据的相应接口匹配。 使用 TypeScript 时，这些接口可确保在访问系统事件的数据对象属性时具有强类型。

创建 实例时， EventGridDeserializer 可以提供用于进一步转换 data 对象的自定义反序列化程序。

分布式跟踪和云事件

此库支持使用 @azure/core-tracing的分布式跟踪。 使用分布式跟踪时，此库将在操作期间 send 创建范围。 此外，在使用 Cloud Events 1.0 架构发送事件时，SDK 将使用分布式跟踪扩展向事件添加 分布式跟踪元数据。 和 tracestate 扩展属性的值traceparent对应于traceparent发送事件的 HTTP 请求中的 和 tracestate 标头。 如果事件已具有 traceparent 扩展属性，则它不会更新。

Kubernetes 上的事件网格

此库已在 Kubernetes 上使用 Azure Arc 进行测试和验证。

示例

使用事件网格架构将自定义事件发布到事件网格主题

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API key>")
);

await client.send([
  {
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world",
    },
  },
]);

使用事件网格架构将自定义事件发布到事件网格域中的主题

将事件发布到事件网格域类似于发布事件网格主题，但对事件使用事件网格架构时，必须包含 topic 属性。 在 Cloud Events 1.0 架构中发布事件时，所需的 source 属性将用作域中要发布到的主题的名称：

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API key>")
);

await client.send([
  {
    topic: "my-sample-topic",
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world",
    },
  },
]);

反序列化事件

EventGridDeserializer 可用于反序列化事件网格传递的事件。 在此示例中，我们有一个云事件，该事件使用 EventGridDeserializer 进行反序列化，并使用 isSystemEvent 来检测它们属于哪种类型的事件。

const { EventGridDeserializer, isSystemEvent } = require("@azure/eventgrid");

async function main() {
  const deserializer = new EventGridDeserializer();
  const message = {
    id: "5bc888aa-c2f4-11ea-b3de-0242ac130004",
    source:
      "/subscriptions/<subscriptionid>/resourceGroups/dummy-rg/providers/Microsoft.EventGrid/topics/dummy-topic",
    specversion: "1.0",
    type: "Microsoft.ContainerRegistry.ImagePushed",
    subject: "Test Subject",
    time: "2020-07-10T21:27:12.925Z",
    data: {
      hello: "world",
    },
  };
  const deserializedMessage = await deserializer.deserializeCloudEvents(message);
  console.log(deserializedMessage);

  if (
    deserializedMessage != null &&
    deserializedMessage.length !== 0 &&
    isSystemEvent("Microsoft.ContainerRegistry.ImagePushed", deserializedMessage[0])
  ) {
    console.log("This is a Microsoft.ContainerRegistry.ImagePushed event");
  }
}

main();

疑难解答

日志记录

启用日志记录可能有助于发现有关故障的有用信息。 若要查看 HTTP 请求和响应的日志，请将 AZURE_LOG_LEVEL 环境变量设置为 info。 或者，可以在运行时通过调用 @azure/logger 中的 setLogLevel 来启用日志记录：

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

有关如何启用日志的更详细说明，请参阅 @azure/记录器包文档。

后续步骤

请查看 示例 目录，获取有关如何使用此库的详细示例。

贡献

若要为此库做出贡献，请阅读贡献指南，详细了解如何生成和测试代码。

相关项目

• Microsoft Azure SDK for Javascript