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

适用于 JavaScript 的 Azure 事件网格客户端库 - 版本 5.5.1

项目
07/17/2024

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

使用客户端库可以：

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

关键链接：

开始

当前支持的环境

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

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

先决条件

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

如果使用 Azure CLI，请将 <your-resource-group-name> 和 <your-resource-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 的客户端对象，需要事件网格主题和 credentialendpoint。事件网格客户端可以使用从访问密钥创建的访问密钥或共享访问签名（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 令牌进行身份验证，请使用 AzureSASCredential，如下所示：

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

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

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

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 是一个 Cloud Native Computing Foundation 项目，该项目生成一个规范，用于以常见方式描述事件数据。构造 EventGridPublisherClient 时，必须指定主题配置为使用的架构：

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

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

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

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

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

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 在反序列化事件时执行一些其他转换：

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

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

分布式跟踪和云事件

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

Kubernetes 上的事件网格

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

例子

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

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

通过