名前空間トピックに発行して Azure Event Grid でイベントを使用する

  • [アーティクル]

この記事では、curl bash シェル コマンドを使用してイベントを発行、受信、確認するプル配信の概要を説明します。 Event Grid リソースは、CLI コマンドを使用して作成されます。 この記事は、プル配信機能のクイック テストに適しています。 データ プレーン SDK を使用したサンプル コードについては、.NET または Java サンプルを参照してください。 Java の場合は、2 つの記事でサンプル コードが提供されています。イベントの発行とイベントの受信のクイック スタートです。 プル配信モデルの詳細については、プル配信の概念とプル配信の概要に関する記事を参照してください。

Azure サブスクリプションをお持ちでない場合は、開始する前に Azure 無料アカウントを作成してください。

前提条件

  • Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。

  • CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。

    • ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、Azure CLI でのサインインに関するページを参照してください。

    • 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。

    • az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。

  • この記事では、Azure CLI のバージョン 2.0.70 以降が必要です。 Azure Cloud Shell を使用している場合は、最新バージョンが既にインストールされています。

リソース グループを作成する

az group create コマンドで Azure リソース グループを作成します。 このリソース グループを使用して、この記事で作成したすべてのリソースを含めます。

Cloud Shell を使用してコマンドを実行する一般的な手順は次のとおりです。

  • [Cloud Shell を開く] を選択すると、右側のペインに Azure Cloud Shell ウィンドウが表示されます。
  • コマンドをコピーして Azure Cloud Shell ウィンドウに貼り付けます。
  • Enter キーを押してコマンドを実行します。

  1. Azure リソース グループの名前を保持する変数を宣言します。 <your-resource-group-name> を任意の値に置き換えて、リソース グループの名前を指定します。

    resource_group="<your-resource-group-name>"

  2. リソース グループを作成します。 必要に応じて場所を変更します。

    az group create --name $resource_group --location eastus

Event Grid リソース プロバイダーを有効にする

  1. Azure サブスクリプションで Event Grid を使用したことがない場合は、Event Grid リソース プロバイダーを登録する必要がある可能性があります。 以下のプロバイダーを登録するコマンドを実行します。

    az provider register --namespace Microsoft.EventGrid

  2. 登録完了まで少し時間がかかることがあります。 状態を確認するには、次のコマンドを実行します。

    az provider show --namespace Microsoft.EventGrid --query "registrationState"

    registrationState が Registered になったら、次に進めることができます。

名前空間の作成

Event Grid 名前空間は、イベントの投稿先となるユーザー定義のエンドポイントになります。 次の例では、Azure Cloud Shell の Bash を利用し、リソース グループに名前空間が作成されます。 名前空間名は、ドメイン ネーム システム (DNS) エントリの一部であるため、一意である必要があります。 名前空間名は、次の規則を満たしている必要があります。

  • 3 から 50 文字で指定してください。
  • リージョン内で一意である必要があります。
  • 使用できる文字は a-z、A-Z、0-9、および - のみです
  • 予約済みキーワード プレフィックス (Microsoft、System、EventGrid など) で始めることはできません。

  1. Event Grid 名前空間の名前を保持する変数を宣言します。 <your-namespace-name> を任意の値に置き換えて、名前空間の名前を指定します。

    namespace="<your-namespace-name>"

  2. 名前空間を作成する。 デプロイ先の場所を変更することもできます。

    az eventgrid namespace create -g $resource_group -n $namespace -l eastus

名前空間トピックの作成

名前空間エンドポイントに発行されたすべてのイベントを保持するために使用するトピックを作成します。

  1. 名前空間トピックの名前を保持する変数を宣言します。 <your-topic-name> を任意の値に置き換えて、名前空間トピックの名前を指定します。

    topic="<your-topic-name>"

  2. 名前空間トピックを作成します。

    az eventgrid namespace topic create -g $resource_group -n $topic --namespace-name $namespace

イベント サブスクリプションの作成

プル配信をサポートする "キュー" に配信モードを設定するイベント サブスクリプションを作成します。 すべての構成オプションの詳細については、最新の Event Grid コントロール プレーン REST API を参照してください。

  1. 名前空間トピックのイベント サブスクリプションの名前を保持する変数を宣言します。 <your-event-subscription-name> を任意の値に置き換えて、イベント サブスクリプションの名前を指定します。

    event_subscription="<your-event-subscription-name>"

  2. 名前空間トピックのイベント サブスクリプションを作成します。

    az eventgrid namespace topic event-subscription create -g $resource_group --topic-name $topic -n $event_subscription --namespace-name $namespace --delivery-configuration "{deliveryMode:Queue,queue:{receiveLockDurationInSeconds:300,maxDeliveryCount:4,eventTimeToLive:P1D}}"

トピックにイベントを送信する

ここで、このセクションの手順に従って、名前空間トピックにサンプル イベントを送信します。

名前空間アクセス キーを一覧表示する

  1. 作成した名前空間に関連付けられているアクセス キーを取得します。 イベントの発行時の認証には、そのうちの 1 つが使用されます。 キーを一覧表示するには、最初に、完全な名前空間リソース ID が必要です。 次のコマンドを実行して取得します。

    namespace_resource_id=$(az eventgrid namespace show -g $resource_group -n $namespace --query "id" --output tsv)

  2. 名前空間から最初のキーを取得します。

    key=$(az eventgrid namespace list-key -g $resource_group --namespace-name $namespace --query "key1" --output tsv)

イベントを発行する

  1. 名前空間のホスト名を取得します。 これを使用して、イベントの送信先となる名前空間 HTTP エンドポイントを作成します。 次の操作は、API バージョン 2023-06-01-preview で最初に利用可能になりました。

    publish_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic:publish?api-version=2023-06-01-preview

  2. CloudEvents に準拠したサンプル イベントを作成します。

    event=' { "specversion": "1.0", "id": "'"$RANDOM"'", "type": "com.yourcompany.order.ordercreatedV2", "source" : "/mycontext", "subject": "orders/O-234595", "time": "'`date +%Y-%m-%dT%H:%M:%SZ`'", "datacontenttype" : "application/json", "data":{ "orderId": "O-234595", "url": "https://yourcompany.com/orders/o-234595"}} '

    data 要素がイベントのペイロードです。 このフィールドには、適切な形式の JSON であればどのようなものでも格納することができます。 イベントに含めることができるプロパティ (コンテキスト属性とも呼ばれます) の詳細については、CloudEvents の仕様に関するページを参照してください。

  3. CURL を使用してイベントをトピックに送信します。 CURL は、HTTP 要求を送信するユーティリティです。

    curl -X POST -H "Content-Type: application/cloudevents+json" -H "Authorization:SharedAccessKey $key" -d "$event" $publish_operation_uri

イベントを受信する

イベント サブスクリプションを参照するエンドポイントを使用して、Event Grid からイベントを受信します。

  1. 次のコマンドを実行して、そのエンドポイントを作成します。

    receive_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic/eventsubscriptions/$event_subscription:receive?api-version=2023-06-01-preview

  2. イベントを使用する要求を送信します。

    curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" $receive_operation_uri

イベントを確認する

イベントを受け取ったら、そのイベントはアプリケーションに渡され、処理されます。 イベントが正常に処理されたら、そのイベントをイベント サブスクリプションに含める必要はなくなります。 Event Grid にイベントを削除するように指示するには、受信操作の応答で取得したロック トークンを使用してイベントを確認します。

  1. 前の手順では、lockToken プロパティを持つ brokerProperties オブジェクトを含む応答を受け取ったはずです。 ロック トークンの値をコピーし、環境変数に設定します。

    lockToken="<paste-the-lock-token-here>"

  2. 次に、確認操作のペイロードをビルドします。これは、確認するイベントのロック トークンを指定するものです。

    acknowledge_request_payload=' { "lockTokens": ["'$lockToken'"]} '

  3. 確認操作 URI を使用して文字列のビルドに進みます。

    acknowledge_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic/eventsubscriptions/$event_subscription:acknowledge?api-version=2023-06-01-preview

  4. 最後に、受信したイベントを確認する要求を送信します。

    curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" -d "$acknowledge_request_payload" $acknowledge_operation_uri

    ロック トークンの有効期限 (イベント サブスクリプションの作成時に設定された 300 秒) が切れる前に確認操作が実行された場合、次の例のような応答が表示されます。

    {"succeededLockTokens":["CiYKJDQ4NjY5MDEyLTk1OTAtNDdENS1BODdCLUYyMDczNTYxNjcyMxISChDZae43pMpE8J8ovYMSQBZS"],"failedLockTokens":[]}

次のステップ

プル配信モデルの詳細については、プル配信の概要に関するページを参照してください。