Java 用Azure Event Grid クライアントライブラリ - バージョン 4.19.0

[アーティクル]
10/24/2023

Azure Event Grid では、イベントベースのアーキテクチャを備えたアプリケーションを簡単に作成することができます。 Event Grid サービスは、任意のアプリケーションの任意のソースから任意の宛先へのイベントのすべてのルーティングを完全に管理します。 Azure サービスイベントとカスタムイベントは、サービスに直接発行できます。これにより、イベントをフィルター処理し、組み込みのハンドラーやカスタム Webhook などのさまざまな受信者に送信できます。 Azure Event Gridの詳細については、「Event Grid とは」を参照してください。

クライアントライブラリを使用して、次のAzure Event Gridを行います。

Event Grid イベント、Cloud Event 1.0、またはカスタムスキーマを使用して Event Grid サービスにイベントを発行する
イベントハンドラーに配信されたイベントを使用する
Azure Event Grid トピックへのクライアント発行イベントを認証するための SAS トークンを生成する

ソース | API リファレンスドキュメント | 製品ドキュメント | サンプル

作業の開始

前提条件

バージョン 8 以降の Java Development Kit (JDK)
Azure サブスクリプション
Event Grid トピックまたはドメイン。リソースを作成するには、Azure portalまたは Azure CLI を使用します

Azure CLI を使用する場合は、と <your-resource-name> を独自の一意の名前に置き換え、<location>有効な Azure サービスの場所に置き換えます<your-resource-group-name>。

トピックの作成 (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 ファイルを含める

GA バージョンのライブラリに依存するには、azure-sdk-bom をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

<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 Portal または Azure CLI を使用して取得できます。

エンドポイント

エンドポイントは、 Azure Portal のトピックまたはドメインのダッシュボードに一覧表示されるか、 Azure CLI で次のコマンドを使用して取得できます。

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

アクセスキー

キーは、Azure Portal の [アクセスキー] タブに一覧表示されます。または、 Azure CLI で次のコマンドを使用して取得できます。一覧表示されているキーはすべて機能します。

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

Azure Active Directory (AAD) トークン認証

Azure Event Gridでは、要求の ID ベースの認証のために Azure Active Directory (Azure AD) との統合が提供されます。 Azure AD では、ロールベースのアクセス制御 (RBAC) を使用して、ユーザー、グループ、またはアプリケーションにAzure Event Grid リソースへのアクセスを許可できます。を使用 TokenCredentialしてトピックまたはドメインにイベントを送信するには、認証された ID に "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 トークンを使用したクライアントの作成

限られた期間、Event Grid トピックまたはドメインにイベントを送信するために使用できる SAS (Shared Access Signature) がある場合は、それを使用してパブリッシャークライアントを作成できます。

同期クライアント:

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 トークンを作成する

イベントを Event Grid トピックまたはドメインにしばらく公開するアクセス許可を他のユーザーに付与する場合は、それらのユーザーに対して SAS (Shared Access Signature) を作成して、パブリッシャークライアントの作成に使用AzureSasCredentialする上記のようなを作成EventGridPublisherClientできます。

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 のドキュメントを参照してください。

主要な概念

Event Grid の一般的な概念の詳細については、「Azure Event Gridの概念」を参照してください。

EventGridPublisherClient

EventGridPublisherClient は、Event Grid トピックまたは Event Grid ドメインにイベントを送信するために使用されます。 EventGridPublisherAsyncClient はの非同期バージョン EventGridPublisherClientです。

イベントスキーマ

Event Grid では、イベントをエンコードするための複数のスキーマがサポートされています。 Event Grid トピックまたはドメインを作成するときは、イベントの発行時に使用するスキーマを指定します。 カスタムスキーマを使用するようにトピックを構成することもできますが、既に定義されている EventGridEvent スキーマまたは CloudEvent スキーマを使用する方が一般的です。 CloudEvent は、一般的な方法でイベントデータを記述するための仕様を生成する Cloud Native Computing Foundation プロジェクトです。 Event Grid サービスは CloudEvent 仕様と互換性があります。トピックまたはドメインが使用するように構成されているスキーマに関係なく、 EventGridPublisherClient イベントを発行するために使用されます。ただし、正しい型を使用してインスタンス化する必要があります。

イベントスキーマ	Publisher クライアントの汎用インスタンス化
Event Grid イベント	`EventGridPublisherClient<EventGridEvent>`
クラウドイベント	`EventGridPublisherClient<CloudEvent>`
[カスタムイベント]	`EventGridPublisherClient<BinaryData>`

間違った型を使用すると、サービスから BadRequest エラーが発生し、イベントは発行されません。この Azure CLI コマンドを使用して、Event Grid トピックまたはドメインが受け入れるスキーマに対してクエリを実行します。

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

イベントハンドラーとイベントの逆シリアル化。

EventGrid は、Event Grid トピックまたはドメイン自体にイベントを格納しません。 EventGrid トピックまたはドメインのサブスクリプションを作成する必要があります。トピックまたはドメインに送信されるイベントは、サブスクリプションのエンドポイント ( "イベントハンドラー" とも呼ばれます) に格納されます。

イベントハンドラーの SDK を使用して Json String でイベントを受信し、を使用 EventGridEvent.fromString() するか、イベント CloudEvent.fromString() を逆シリアル化できます。イベントのデータ部分は、バイナリ、文字列、または JSON データで指定できます。

例

Event Grid へのイベントの送信に関するトピック

イベントは、「イベントスキーマ」EventGridEventで詳しく説明されているように、、CloudEvent、またはカスタムスキーマで送信できます。送信されるスキーマを受け入れるようにトピックまたはドメインを構成する必要があります。わかりやすくするために、同期クライアントはサンプルに使用されますが、非同期クライアントのメソッド名は同じです。

注: 送信を開始する前に、イベントグリッドトピックが受け入れるスキーマ (クラウドイベント、イベントグリッドイベント、またはカスタムイベント) を確認します。

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);

Event Grid ドメインへのイベントの送信

Event Grid ドメインには何千ものトピックを含めることができますが、1 つのエンドポイントがあります。ドメインを使用して、一連の関連トピックを管理できます。 Event Grid ドメインのトピックへのイベントの送信は、通常の Event Grid トピックにイベントを送信する場合と同じですが、ドメインがスキーマを受け入れる場合は、の 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 場合は、ドメインの作成時にをマップ topic するように構成されている CloudEvent の属性を設定する必要があります。既定のマッピング属性はです source。

イベントの受信と使用

Event Grid サービスはイベントを格納しません。そのため、この Event Grid SDK にはイベントレシーバーがありません。代わりに、イベントは、ServiceBus、 EventHubs、ストレージキュー、WebHook エンドポイント、またはその他の多くのサポートされている Azure サービスを含むイベントハンドラーに格納されます。ただし、現在、すべてのイベントが送信され、エンコードされた JSON データとして格納されます。イベントハンドラーによって受信された後のイベントの逆シリアル化について詳しく説明する基本的なコードを次に示します。ここでも、処理は、トピック/サブスクリプションから受信されるイベントスキーマによって異なります。

Json 文字列からの逆シリアル化 `EventGridEvent` または `CloudEvent` 逆シリアル化

Json String には、1 つのイベントまたはイベントの配列を指定できます。返される結果は、イベントの一覧です。

// 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);

またはからデータを逆シリアル化する`CloudEventEventGridEvent`

Json String からまたはをEventGridEvent逆シリアル化したら、または EventGridEvent を使用getData()CloudEventしてイベントのペイロードを取得CloudEventできます。オブジェクトを 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`

システムトピックに送信されるイベントは、システムトピックイベントまたはシステムイベントと呼ばれます。 Event Grid のシステムトピックは、Azure Storage、Azure Event Hubs、App Configurationなどのイベントソースによって発行されたイベントを表します。たとえば、BLOB が作成されると、イベントの種類が "Microsoft.Storage.BlobCreated" のシステムイベントが、構成されたシステムトピックに送信されます。このイベントの種類のシステムイベントクラスは、パッケージ com.azure.messaging.eventgrid.systemeventsで定義されていますStorageBlobCreatedEventData。 EventGrid には、次のシステムイベントがあります。

Azure App Configuration
Azure App Service
Azure Blob Storage
...
その他の多くのサービスについては、システムトピックをサポートする Azure サービスに関するページを参照してください。
関連するシステムイベントクラスについては、パッケージ com.azure.messaging.eventgrid.systemevents を参照してください

この SDK を使用してシステムトピックにシステムイベントを送信することはできません。

システムイベントの受信と使用は、他のイベントと同じです。さらに、さまざまなシステムイベントデータのモデルクラスのセットは、パッケージ com.azure.messaging.eventgrid.systemeventsで定義されます。または CloudEvent.fromString()を使用してイベントを逆シリアル化した後、次の操作をEventGridEvent.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 、エラーコードがラップされます。

Event Grid サービスのリファレンスドキュメントについては、こちらを参照してください。これは、トピック/エンドポイントの構成に関連する問題や、サービスからのエラーコードに関連する問題の場合に開始するのに適した場所です。

分散トレース

Event Grid ライブラリでは、すぐにトレースを配布できます。 CloudEvents の仕様の分散トレースのガイダンスに準拠するため、このライブラリでは、分散トレースを有効にするときに CloudEvent の extensionAttributes に traceparent と tracestate を設定します。皆さまが使用しているアプリケーションでの分散トレースに関する情報は、Azure SDK Java の分散トレースのドキュメントをご覧ください。

ヘルプと問題

SDK のリファレンスドキュメントについては、こちらを参照してください。これは、呼び出される各メソッドの目的と、エラーや予期しない動作の考えられる理由を理解するための適切な最初の手順です。

これらの SDK でバグが発生した場合は、 Issue を使用して問題を報告するか、 Azure Java SDK の StackOverflow をチェックアウトしてください。

次の手順

Azure Java SDK
Microsoft Azure サブスクリプションをお持ちでない場合は、こちらから無料試用版アカウントを入手できます
その他のサンプルコードについては、こちらを参照してください。
その他の Event Grid チュートリアルについては、こちらを参照してください。

共同作成

このリポジトリへの投稿の詳細については、投稿ガイドを参照してください。

フォーク
機能ブランチを作成する (git checkout -b my-new-feature)
変更をコミットする (git commit -am 'Add some feature')
ブランチにプッシュする (git push origin my-new-feature)
新しい Pull Request を作成する

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

Java 用Azure Event Grid クライアント ライブラリ - バージョン 4.19.0