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

Azure 事件网格 Java 客户端库 - 版本 4.19.0

通过 Azure 事件网格，可使用基于事件的体系结构轻松生成应用程序。 事件网格服务完全管理任何应用程序从任何源到任何目标的所有事件路由。 Azure 服务事件和自定义事件可以直接发布到服务，然后可以筛选事件并将其发送到各种收件人，例如内置处理程序或自定义 Webhook。 若要详细了解Azure 事件网格：什么是事件网格？

使用用于Azure 事件网格的客户端库可以：

• 使用事件网格事件、云事件 1.0 或自定义架构将事件发布到事件网格服务
• 使用已传递到事件处理程序的事件
• 生成 SAS 令牌以对客户端发布事件进行身份验证，Azure 事件网格主题

来源 | API 参考文档 | 产品文档 | 样品

入门

先决条件

• Java 开发工具包 (JDK) 版本 8 或更高版本
• Azure 订阅
• 事件网格主题或域。 若要创建资源，可以使用 Azure 门户 或 Azure CLI

如果使用 Azure CLI，请将 和 <your-resource-name> 替换为<your-resource-group-name>自己的唯一名称和<location>有效的 Azure 服务位置。

(Azure CLI) 创建主题

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

(Azure CLI) 创建域

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

添加包

包括 BOM 文件

请将 azure-sdk-bom 包含在项目中，以依赖于库的 GA 版本。 在以下代码段中，将 {bom_version_to_target} 占位符替换为版本号。 若要详细了解 BOM，请参阅 AZURE SDK BOM 自述文件。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后在没有版本标记的依赖项部分中包含直接依赖项。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventgrid</artifactId>
  </dependency>
</dependencies>

包括直接依赖项

如果要依赖于 BOM 中不存在的特定库版本，请将直接依赖项添加到项目，如下所示。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventgrid</artifactId>
    <version>4.19.0</version>
</dependency>

对客户端进行身份验证

为了发送事件，我们需要一个要发送到的终结点，并为该终结点进行一些身份验证。 身份验证可以是密钥凭据、共享访问签名或 Azure Active Directory 令牌身份验证。 可以通过 Azure 门户或 AzureCLI 获取终结点和密钥。

终结点

终结点列在 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 --name <your-resource-name> --resource-group <your-resource-group-name>

Azure Active Directory (AAD) 令牌身份验证

Azure 事件网格提供与 Azure Active Directory (Azure AD) 的集成，以便对请求进行基于标识的身份验证。 借助 Azure AD，可以使用基于角色的访问控制 (RBAC) 向用户、组或应用程序授予对Azure 事件网格资源的访问权限。 若要使用 TokenCredential将事件发送到主题或域，应为经过身份验证的标识分配“EventGrid 数据发送者”角色。

创建客户端

使用终结点和访问密钥创建客户端

获得访问密钥和主题终结点后，可以按如下所示创建发布者客户端：

适用于每个 Java 开发人员的同步客户端：

// For CloudEvent
EventGridPublisherClient<CloudEvent> cloudEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildCloudEventPublisherClient();

// For EventGridEvent
EventGridPublisherClient<EventGridEvent> eventGridEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts EventGridEvent schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildEventGridEventPublisherClient();

// For custom event
EventGridPublisherClient<BinaryData> customEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts custom event schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildCustomEventPublisherClient();

或异步客户端（如果技术堆栈具有反应式编程，例如项目反应堆）：

// For CloudEvent
EventGridPublisherAsyncClient<CloudEvent> cloudEventAsyncClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildCloudEventPublisherAsyncClient();

// For EventGridEvent
EventGridPublisherAsyncClient<EventGridEvent> eventGridEventAsyncClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts EventGridEvent schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildEventGridEventPublisherAsyncClient();

// For custom event
EventGridPublisherAsyncClient<BinaryData> customEventAsyncClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts custom event schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildCustomEventPublisherAsyncClient();

使用终结点和 SAS 令牌创建客户端

如果 SAS (共享访问签名) 可用于在有限的时间内将事件发送到事件网格主题或域，则可以使用它来创建发布者客户端：

同步客户端：

EventGridPublisherClient<CloudEvent> cloudEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new AzureSasCredential("<sas token that can access the endpoint>"))
    .buildCloudEventPublisherClient();

异步客户端：

EventGridPublisherAsyncClient<CloudEvent> cloudEventAsyncClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new AzureSasCredential("<sas token that can access the endpoint>"))
    .buildCloudEventPublisherAsyncClient();

使用终结点和 Azure Active Directory (AAD) 令牌凭据创建客户端

若要使用 AAD 令牌凭据，请包含 azure-identity 项目作为依赖项。 有关详细信息，请参阅 azure-identity README 。

同步客户端：

EventGridPublisherClient<CloudEvent> cloudEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildCloudEventPublisherClient();

异步客户端：

EventGridPublisherAsyncClient<CloudEvent> cloudEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildCloudEventPublisherAsyncClient();

为其他人创建 SAS 令牌，以便在有限的时间内发送事件

如果想要授予其他人在一段时间内将事件发布到事件网格主题或域的权限，可以为其创建 SAS (共享访问签名) ，以便他们创建 EventGridPublisherClient 类似于上述的 AzureSasCredential 用于创建发布者客户端的 。

下面是用于创建 20 分钟后过期的共享访问签名的示例代码：

OffsetDateTime expiration = OffsetDateTime.now().plusMinutes(20);
String sasToken = EventGridPublisherClient
    .generateSas("<your event grid endpoint>", new AzureKeyCredential("<key for the endpoint>"), expiration);

使用 BinaryData

此 SDK 使用 com.azure.util.BinaryData 表示事件的数据有效负载。 BinaryData 支持通过 com.azure.core.util.BinaryData.fromObject(Object object) 和 toObject() 方法（使用默认的 Jackson Json 序列化程序）或 fromObject(Object object, ObjectSerializer customSerializer) 和 方法（接受自定义的 Json 序列化程序）对对象进行序列化和 toObject(Class<T> clazz, ObjectSerializer serializer) 反序列化。 有关详细信息，请参阅 BinaryData 文档。

关键概念

有关常规事件网格概念的信息：Azure 事件网格中的概念。

EventGridPublisherClient

EventGridPublisherClient 用于将事件发送到事件网格主题或事件网格域。 EventGridPublisherAsyncClient 是 的 EventGridPublisherClient异步版本。

事件架构

事件网格支持多个架构来编码事件。 创建事件网格主题或域时，可以指定发布事件时将使用的架构。 虽然可以将主题配置为使用 自定义架构 ，但更常见的是使用已定义的 EventGridEvent 架构 或 CloudEvent 架构。 CloudEvent 是一个云原生计算基础项目，它生成用于以通用方式描述事件数据的规范。 事件网格服务与 CloudEvent 规范 兼容，无论主题或域配置为使用哪种架构， EventGridPublisherClient 都将用于向其中发布事件。 但是，必须使用正确的类型来实例化它：

事件架构	Publisher 客户端泛型实例化
事件网格事件	EventGridPublisherClient<EventGridEvent>
云事件	EventGridPublisherClient<CloudEvent>
自定义事件	EventGridPublisherClient<BinaryData>

使用错误的类型将导致服务出现 BadRequest 错误，并且不会发布事件。 使用此 Azure CLI 命令查询事件网格主题或域接受的架构：

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

事件处理程序和事件反序列化。

EventGrid 不会将任何事件存储在事件网格主题或域本身中。 需要 创建 EventGrid 主题或域的订阅。 发送到主题或域的事件将存储在订阅的终结点中，也称为“事件处理程序”。

可以使用事件处理程序的 SDK 接收 Json 字符串中的事件， EventGridEvent.fromString() 然后使用 或 CloudEvent.fromString() 反序列化事件。 事件的数据部分可以位于二进制、字符串或 JSON 数据中。

示例

将事件发送到事件网格主题

事件可以在 、 CloudEvent或自定义架构中EventGridEvent发送，详见事件架构。 必须将主题或域配置为接受正在发送的架构。 为简单起见，同步客户端用于示例，但异步客户端具有相同的方法名称。

注意：在开始发送之前，请确定 (云事件、事件网格事件或自定义事件) 事件网格主题接受的架构。

发送到 EventGridEvent 接受 EventGridEvent 架构的主题

// Make sure that the event grid topic or domain you're sending to is able to accept the EventGridEvent schema.
List<EventGridEvent> events = new ArrayList<>();
User user = new User("John", "James");
events.add(new EventGridEvent("exampleSubject", "Com.Example.ExampleEventType", BinaryData.fromObject(user), "0.1"));
eventGridEventClient.sendEvents(events);

发送到 CloudEvent 接受 CloudEvent 架构的主题

// Make sure that the event grid topic or domain you're sending to is able to accept the CloudEvent schema.
List<CloudEvent> events = new ArrayList<>();
User user = new User("John", "James");
events.add(new CloudEvent("https://source.example.com", "Com.Example.ExampleEventType",
    BinaryData.fromObject(user), CloudEventDataFormat.JSON, "application/json"));
cloudEventClient.sendEvents(events);

将自定义事件发送到接受自定义事件架构的主题

// Make sure that the event grid topic or domain you're sending to is able to accept the custom event schema.
List<BinaryData> events = new ArrayList<>();
events.add(BinaryData.fromObject(new HashMap<String, String>() {
    {
        put("id", UUID.randomUUID().toString());
        put("time", OffsetDateTime.now().toString());
        put("subject", "Test");
        put("foo", "bar");
        put("type", "Microsoft.MockPublisher.TestEvent");
        put("data", "example data");
        put("dataVersion", "0.1");
    }
}));
customEventClient.sendEvents(events);

将事件发送到事件网格域

事件网格域可以有数千个主题，但有一个终结点。 可以使用域来管理一组相关主题。 将事件发送到事件网格域的主题与将事件发送到常规事件网格主题相同，只是在域接受EventGridEvent架构时需要指定 topic 的 EventGridEvent 。

List<EventGridEvent> events = new ArrayList<>();
User user = new User("John", "James");
events.add(new EventGridEvent("com/example", "Com.Example.ExampleEventType", BinaryData.fromObject(user), "1")
    .setTopic("yourtopic"));
eventGridEventClient.sendEvents(events);

如果域接受 CloudEvent 架构，则必须设置 CloudEvent 的属性，该属性配置为在创建域时映射 topic 。 默认映射属性为 source。

接收和使用事件

事件网格服务不存储事件。 因此，此事件网格 SDK 没有事件接收器。 相反，事件存储在 事件处理程序中，包括 ServiceBus、EventHubs、存储队列、WebHook 终结点或许多其他受支持的 Azure 服务。 但是，目前所有事件都将作为编码的 JSON 数据发送和存储。 下面是一些基本代码，这些代码详细介绍了事件处理程序接收事件后事件的反序列化。 同样，根据从主题/订阅接收的事件架构，处理方式也有所不同。

反序列化 Json 字符串或CloudEvent从 Json 字符串反序列化EventGridEvent

Json 字符串可以有单个事件或事件数组。 返回的结果是事件列表。

// Deserialize an EventGridEvent
String eventGridEventJsonData = "<your EventGridEvent json String>";
List<EventGridEvent> eventGridEvents = EventGridEvent.fromString(eventGridEventJsonData);

// Deserialize a CloudEvent
String cloudEventJsonData = "<your CloudEvent json String>";
List<CloudEvent> cloudEvents = CloudEvent.fromString(cloudEventJsonData);

从 CloudEvent 或 反序列化数据 EventGridEvent

从 Json 字符串反序列化 EventGridEvent 或 CloudEvent 后，可以使用 getData()CloudEvent 或 EventGridEvent 获取事件的有效负载。 它返回一个 BinaryData 对象，该对象具有进一步将数据反序列化为可用类型的方法：

• BinaryData.toBytes() 以字节的形式获取数据[]
• BinaryData.toString() 获取字符串格式的数据
• BinaryData.toObject() 获取数据作为特定类型的对象。 默认情况下，它使用 Json 反序列化程序。 如果想要使用自己的反序列化程序，它有一个用于接受反序列化程序的重载。

BinaryData eventData = eventGridEvent.getData();

//Deserialize data to a model class
User dataInModelClass = eventData.toObject(User.class);

//Deserialize data to a Map
Map<String, Object> dataMap = eventData.toObject(new TypeReference<Map<String, Object>>() {
});

//Deserialize Json String to a String
String dataString = eventData.toObject(String.class);

//Deserialize String data to a String
String dataInJsonString = eventData.toString();

//Deserialize data to byte array (byte[])
byte[] dataInBytes = eventData.toBytes();

从 CloudEvent 或 反序列化系统事件数据 EventGridEvent

发送到 系统主题 的事件称为系统主题事件或系统事件。 事件网格中的系统主题表示事件源（如 Azure 存储、Azure 事件中心、应用程序配置等）发布的事件。 例如，创建 Blob 时，会将事件类型为“Microsoft.Storage.BlobCreated”的系统事件发送到配置的系统主题。 此事件类型的系统事件类在 StorageBlobCreatedEventData 包 com.azure.messaging.eventgrid.systemevents中定义。 EventGrid 具有用于：

• Azure 应用配置
• Azure 应用服务
• Azure Blob 存储
• ...
• 请参阅 支持许多其他服务的系统主题的 Azure 服务。
• 有关相关系统事件类的包，请参阅包com.azure.messaging.eventgrid.systemevents

不能使用此 SDK 将系统事件发送到系统主题。

接收和使用系统事件与其他事件相同。 此外，包 中 com.azure.messaging.eventgrid.systemevents还定义了一组用于各种系统事件数据的模型类。 在反序列化事件后， EventGridEvent.fromString() 可以使用 或 CloudEvent.fromString()执行以下操作：

• 查找系统事件数据可反序列化到的系统事件数据模型类;

// Look up the System Event data class
Class<?> eventDataClazz = SystemEventNames.getSystemEventMappings().get(event.getEventType());

• 将系统事件的数据反序列化为模型类实例，例如反序列化任何其他事件数据;

// Deserialize the event data to an instance of a specific System Event data class type
BinaryData data = event.getData();
if (data != null) {
    StorageBlobCreatedEventData blobCreatedData = data.toObject(StorageBlobCreatedEventData.class);
    System.out.println(blobCreatedData.getUrl());
}

• 处理多个事件类型。

List<EventGridEvent> eventGridEvents = EventGridEvent.fromString("<Your EventGridEvent Json String>");
for (EventGridEvent eventGridEvent : eventGridEvents) {
    BinaryData binaryData = eventGridEvent.getData();
    switch (eventGridEvent.getEventType()) {
        case SystemEventNames.APP_CONFIGURATION_KEY_VALUE_DELETED:
            AppConfigurationKeyValueDeletedEventData keyValueDeletedEventData =
                binaryData.toObject(TypeReference.createInstance(AppConfigurationKeyValueDeletedEventData.class));
            System.out.println("Processing the AppConfigurationKeyValueDeletedEventData...");
            System.out.printf("The key is: %s%n", keyValueDeletedEventData.getKey());
            break;
        case SystemEventNames.APP_CONFIGURATION_KEY_VALUE_MODIFIED:
            AppConfigurationKeyValueModifiedEventData keyValueModifiedEventData =
                binaryData.toObject(TypeReference.createInstance(AppConfigurationKeyValueModifiedEventData.class));
            System.out.println("Processing the AppConfigurationKeyValueModifiedEventData...");
            System.out.printf("The key is: %s%n", keyValueModifiedEventData.getKey());
            break;
        default:
            System.out.printf("%s isn't an AppConfiguration event data%n", eventGridEvent.getEventType());
            break;
    }
}

更多示例

可 在此处找到一些其他示例代码。

疑难解答

响应和错误代码

服务响应以 Http 状态代码的形式返回，包括许多错误代码。 可以选择性地返回 PublisherClient这些代码。 意外的状态代码在包装错误代码时引发 HttpResponseException 。

可 在此处找到事件网格服务的参考文档。 对于涉及主题/终结点配置的问题以及涉及服务错误代码的问题，这是一个很好的起点。

分布式跟踪

事件网格库支持现成分布跟踪。 根据有关分布式跟踪的 CloudEvents 规范指南，当分布式跟踪已启用时，该库会在 CloudEvent 的 extensionAttributes 上设置 traceparent 和 tracestate。 若要详细了解如何在应用程序中启用分布式跟踪，请参阅 Azure SDK Java 分布式跟踪文档。

帮助和问题

可 在此处找到 SDK 的参考文档。 这是了解每个调用方法的用途以及错误或意外行为可能原因的第一步。

如果这些 SDK 遇到任何 bug，请通过 “问题” 提交问题，或查看 适用于 Azure Java SDK 的 StackOverflow。

后续步骤

• Azure Java SDK
• 如果没有 Microsoft Azure 订阅，可以在此处获取免费试用版帐户
• 可在此处找到一些其他示例代码
• 可在此处找到其他事件网格教程

贡献

有关参与此存储库的详细信息，请参阅 参与指南。

1. 分叉它
2. 创建功能分支 (git checkout -b my-new-feature)
3. () git commit -am 'Add some feature' 提交更改
4. 推送到分支 (git push origin my-new-feature)
5. 创建新的拉取请求

---

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。