カスタム配信プロパティ

  • [アーティクル]

イベント サブスクリプションを使用すると、配信されたイベントに含まれる HTTP ヘッダーを設定できます。 この機能を使用すると、宛先に必要なカスタム ヘッダーを設定できます。 イベント サブスクリプションを作成するときに、最大 10 個のヘッダーを設定できます。 各ヘッダーの値は、4,096 (4 K) バイトより大きくすることはできません。

次の宛先に配信されるイベントにカスタム ヘッダーを設定できます。

  • Webhooks
  • Azure Service Bus のトピックとキュー
  • Azure Event Hubs
  • Azure Functions
  • Azure Relay ハイブリッド接続

Azure portal でイベント サブスクリプションを作成する場合は、 [配信プロパティ] タブを使用してカスタム HTTP ヘッダーを設定できます。 このページでは、固定と動的ヘッダー値を設定できます。

静的ヘッダー値の設定

固定値を使用してヘッダーを設定するには、対応するフィールドにヘッダーの名前とその値を指定します。

Delivery properties - static

機密データを指定する場合は、[秘密ですか?] チェックボックスをオンにできます。 Azure portal での機密データの表示は、ユーザーの RBAC アクセス許可によって異なります。

動的ヘッダー値の設定

受信イベントのプロパティに基づいてヘッダーの値を設定できます。 JsonPath 構文を使用して、送信要求のヘッダーの値として使用する受信イベントのプロパティ値を参照します。 文字列、数値、およびブール値の JSON 値のみがサポートされています。 たとえば、イベント データの受信イベント プロパティ system の値を使用して、Channel という名前のヘッダーの値を設定するには、次の方法でイベント サブスクリプションを構成します。

Delivery properties - dynamic

Azure CLI の使用

az eventgrid event-subscription create コマンドを使用してサブスクリプションを作成するときに --delivery-attribute-mapping パラメーターを使用します。 次に例を示します。

az eventgrid event-subscription create -n es1 \
    --source-resource-id /subscriptions/{SubID}/resourceGroups/{RG}/providers/Microsoft.EventGrid/topics/topic1
    --endpoint-type storagequeue \
    --endpoint /subscriptions/{SubID}/resourceGroups/TestRG/providers/Microsoft.Storage/storageAccounts/sa1/queueservices/default/queues/q1 \
    --enable-advanced-filtering-on-arrays true
    --delivery-attribute-mapping staticproperty1 static somestaticvalue2 true 
    --delivery-attribute-mapping staticproperty2 static somestaticvalue3 false 
    --delivery-attribute-mapping dynamicproperty1 dynamic data.key1

例

ここでは、配信プロパティの使用例をいくつか紹介します。

ベアラー トークンを使用した Authorization ヘッダーの設定 (非標準例)

Webhook ハンドラーで要求を識別するために、Authorization ヘッダーに値を設定します。 Microsoft Entra ID で Webhook を保護していない場合は、Authorization ヘッダーを設定できます。

ヘッダー名 ヘッダーの種類 ヘッダー値
Authorization スタティック BEARER SlAV32hkKG...

送信要求に、イベント サブスクリプションに設定されたヘッダーが含まれるようになりました。

POST /home.html HTTP/1.1
Host: acme.com

Authorization: BEARER SlAV32hkKG...

Note

Authorization ヘッダーを定義することは、宛先が Webhook の場合、適切なオプションです。 リソース ID を使用してサブスクライブしている関数、Service Bus、Event Hubs、および Hybrid Connections には使用しないでください。Event Grid と使用した場合、これらの宛先では独自の認証スキームがサポートされているからです。

Service Bus の例

Azure Service Bus は、単一メッセージを送信する際に、以下のメッセージプロパティの使用をサポートしています。

ヘッダー名 ヘッダーの種類
MessageId 動的
PartitionKey 静的または動的
SessionId 静的または動的
CorrelationId 静的または動的
Label 静的または動的
ReplyTo 静的または動的
ReplyToSessionId 静的または動的
To 静的または動的
ViaPartitionKey 静的または動的

Note

  • MessageId の既定値は、Event Grid のイベントの内部 ID です。 これはオーバーライドできます。 たとえば、「 data.field 」のように入力します。
  • 設定できるのは SessionId か MessageId のみです。

Service Bus のキューまたはトピックにメッセージを送信する際もカスタム プロパティを指定できます。 メッセージ ヘッダーのシステム プロパティで使用されているため、aeg- プレフィックスは使用しないでください。 メッセージ ヘッダーのプロパティ一覧については、イベント ハンドラーとしての Service Bus に関するページを参照してください

Event Hubs の例

イベントをイベント ハブ内の特定のパーティションに発行する必要がある場合は、イベント サブスクリプションに PartitionKey プロパティを設定して、対象のイベント ハブ パーティションを識別するパーティション キーを指定します。

ヘッダー名 ヘッダーの種類
PartitionKey 静的または動的

イベント ハブにメッセージを送信する際も、カスタム プロパティを指定できます。 メッセージ ヘッダーのシステム プロパティで使用されているため、aeg- プレフィックスをプロパティ名に使用しないでください。 メッセージ ヘッダーのプロパティ一覧については、イベント ハンドラーとしての Event Hubs に関するページを参照してください

Azure Storage キューへの送信イベントの有効期限を構成する

Azure Storage キューの宛先の場合は、送信メッセージが Azure Storage キューに配信されてからのみ、その有効期限を構成できます。 時間が指定されていない場合、メッセージの既定の有効期限は 7 日間です。 また、イベントを無期限に設定することもできます。

Delivery properties - storage queue

次のステップ

イベント配信の詳細については、次の記事を参照してください。