次の方法で共有

Azure Event Grid 名前空間 - CloudEvents スキーマのサポート

  • [アーティクル]

Event Grid 名前空間トピックでは、JSON 形式 で HTTP プロトコル バインド を使用して、Cloud Native Computing Foundation (CNCF) のオープン標準の CloudEvents 1.0 仕様に準拠するイベントを受け入れます。 CloudEvent は、イベント データと呼ばれる、通信内容とそれに関するメタデータを入れた一種のメッセージです。 イベント ドリブン アーキテクチャのイベント データでは、通常、システム状態の変化を通知する情報が伝送されます。 CloudEvents メタデータは、メッセージの送信元 (ソース システム)、その種類など、メッセージに関するコンテキスト情報を提供する一連の属性で構成されます。CloudEvents 仕様に準拠するすべての有効なメッセージには、次の必須コンテキスト属性を含める必要があります。

さらに、CloudEvents 仕様では、Event Grid を使用するときに含めることができる省略可能なコンテキスト属性と拡張コンテキスト属性も定義します。

Event Grid を使用する場合、推奨されるイベント形式は CloudEvents です。これは、ユース ケース (イベントやイベント形式などを転送するためのモード) が十分に文書化されており、拡張性があり、相互運用性が高いためです。 CloudEvents を使用すると、イベントを発行したり使用したりするための共通のイベント形式を提供して、相互運用性を向上させることができます。 これにより、ツールを統一化して、イベントのルーティングや処理方法を標準化することができます。

CloudEvents コンテンツ モード

CloudEvents 仕様では、3 つのコンテンツ モードが定義されています。これらは、バイナリ、構造化、バッチです。

重要

どのコンテンツ モードでも、テキスト (JSON、テキスト/* など) やバイナリ エンコードのイベント データを交換できます。 バイナリ コンテンツ モードは、バイナリ データの送信専用に使用されるわけではありません。

コンテンツ モードは、使用するエンコードがバイナリかテキストかということではなく、イベント データとそのメタデータが記述および交換される方法に関する種類を示します。 構造化コンテンツ モードでは、JSON オブジェクトなどの 1 つの構造が使用されます。ここでは、コンテキスト属性とイベント データの両方が HTTP ペイロード内にまとめて配置されます。 バイナリ コンテンツ モードでは、HTTP ヘッダーにマップされるコンテキスト属性と、Content-Type で設定されるメディアの種類に従ってエンコードされる HTTP ペイロードであるイベント データが分離されます。

CloudEvents サポート

次の表に、CloudEvents 仕様の現在のサポートを示します。

CloudEvents コンテンツ モード サポート対象
構造化された JSON はい
構造化された JSON バッチ処理 はい (イベントを発行する場合)
Binary はい (イベントを発行する場合)

イベントの最大許容サイズは 1 MB です。 64 KB を超えるイベントは、64 KB の増分単位で課金されます。

構造化コンテンツ モード

CloudEvents 構造化コンテンツ モードのメッセージには、HTTP ペイロード内のコンテキスト属性とイベント データの両方が含まれます。

重要

現在、Event Grid では、HTTP で CloudEvents JSON 形式がサポートされています。

JSON 形式を使用した構造化モードの CloudEvent の例を次に示します。 メタデータ ("data" ではないすべての属性) とメッセージ/イベント データ ("data" オブジェクト) の両方が JSON を使用して記述されます。 この例には、必要なすべてのコンテキスト属性と、いくつかの省略可能な属性 (subject、 time、datacontenttype) と拡張属性 (comexampleextension1、 comexampleothervalue) が含まれています。

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "subject" : "O-28964",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "comexampleextension1" : "value",
    "comexampleothervalue" : 5,
    "datacontenttype" : "application/json",
    "data" : {
       "orderId" : "O-28964",
       "URL" : "https://com.yourcompany/orders/O-28964"
    }
}

構造化されたコンテンツに JSON 形式を使用して、JSON 値ではないイベント データを送信することができます。 これを行うため、次の手順を実行します。

  1. データがエンコードされるメディアの種類を持つ datacontenttype 属性を含めます。
  2. メディアの種類が text/plain、 text/csv、 application/xml などのテキスト形式でエンコードされる場合は、data 属性を使用し、通信している内容を格納する JSON 文字列をその値として設定する必要があります。
  3. メディアの種類がバイナリ エンコードになる場合は、data_base64 属性を使用し、BASE64 でエンコードされたバイナリ値を格納する JSON 文字列をその値として設定する必要があります。

たとえば、この CloudEvent は、Protobuf メッセージを交換するために application/protobuf でエンコードされたイベント データを伝送します。

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "datacontenttype" : "application/protobuf",
    "data_base64" : "VGhpcyBpcyBub3QgZW5jb2RlZCBpbiBwcm90b2J1ZmYgYnV0IGZvciBpbGx1c3RyYXRpb24gcHVycG9zZXMsIGltYWdpbmUgdGhhdCBpdCBpcyA6KQ=="
}

data 属性または data_base64 属性の使用の詳細については、Handling of data (データの処理) をご覧ください。

このコンテンツ モードの詳細については、CloudEvents の HTTP 構造化コンテンツ モードの仕様に関する記事をご覧ください。

バッチ コンテンツ モード

現在、Event Grid では、CloudEvents を Event Grid に発行するときに JSON バッチ コンテンツ モードをサポートしています。 このコンテンツ モードでは、構造化コンテンツ モードで CloudEvents を格納する JSON 配列が使用されます。 たとえば、アプリケーションでは、次のような配列を使用して 2 つのイベントを発行できます。 同様に、Event Grid のデータ プレーン SDK を使用している場合、このペイロードも送信されます。

[
    {
        "specversion": "1.0",
        "id": "E921-1234-1235",
        "source": "/mycontext",
        "type": "com.example.someeventtype",
        "time": "2018-04-05T17:31:00Z",
        "data": "some data"
    },
    {
        "specversion": "1.0",
        "id": "F555-1234-1235",
        "source": "/mycontext",
        "type": "com.example.someeventtype",
        "time": "2018-04-05T17:31:00Z",
        "data": {
            "somekey" : "value",
            "someOtherKey" : 9
        }
    }
]

詳細については、CloudEvents のバッチ コンテンツ モード仕様に関する記事をご覧ください。

バッチ処理

アプリケーションでは、複数のイベントを 1 つの配列にまとめてバッチ処理する必要があります。そうすれば、1 回の発行要求で効率とスループットを高めて処理できます。 バッチは最大 1 MB とすることができ、イベントの最大サイズは 1 MB です。

バイナリ コンテンツ モード

バイナリ コンテンツ モードの CloudEvent では、コンテキスト属性が HTTP ヘッダーとして記述されています。 HTTP ヘッダーの名前は、コンテキスト属性の前に ce- が付いた名前になっています。 Content-Type ヘッダーには、イベント データがエンコードされるメディアの種類が反映されます。

重要

バイナリ コンテンツ モードを使用する場合、ce-datacontenttype HTTP ヘッダーを配置してはなりません。

重要

バイナリ コンテンツ モードを使用するときに独自の属性 (つまり拡張属性) を含める場合は、名前が ASCII 文字の小文字 ('a' から 'z') または数字 ('0' から '9') で構成されていること、および長さが 20 文字を超えないようにしてください。 つまり、CloudEvents コンテキスト属性に名前を付けるための名前付け規則は、有効な HTTP ヘッダー名よりも制限が厳しくなっています。 すべての有効な HTTP ヘッダー名が有効な拡張属性名であるわけではありません。

HTTP ペイロードは、Content-Type のメディアの種類に従ってエンコードされたイベント データです。

コンテンツ バイナリ モードで CloudEvent を発行するために使用される HTTP 要求は、次の例のようになります。

POST / HTTP/1.1
HOST mynamespace.eastus-1.eventgrid.azure.net/topics/mytopic
ce-specversion: 1.0
ce-type: com.example.someevent
ce-source: /mycontext
ce-id: A234-1234-1234
ce-time: 2018-04-05T17:31:00Z
ce-comexampleextension1: value
ce-comexampleothervalue: 5
content-type: application/protobuf

Binary data according to protobuf encoding format. No context attributes are included.

CloudEvents のバイナリ コンテンツ モードまたは構造化コンテンツ モードを使用する場面

ホップとプロトコルをまたいで CloudEvent を転送するための簡単なアプローチが必要な場合は、構造化コンテンツ モードを使用できます。 構造化コンテンツ モードの CloudEvents にはメッセージとそのメタデータが含まれるため、クライアントはメッセージ全体を使用して他のシステムに転送するのが簡単です。

ダウンストリーム アプリケーションがメッセージのみを必要としていて追加情報 (つまりコンテキスト属性) は不要であることがわかっている場合は、バイナリ コンテンツ モードを使用できます。 構造化コンテンツ モードでも CloudEvent からイベント データ (メッセージ) を取得できますが、コンシューマー アプリケーションの HTTP ペイロード内にイベント データだけを含んでいる方が簡単です。 たとえば、他のアプリケーションは他のプロトコルを使用することができて、必要なのは中核となるメッセージのみで、メタデータではない場合もあります。 実際、メタデータは、直接の最初のホップに対してだけしか意味を持たない場合があります。 この場合、交換するデータをメタデータとは別にして扱うことで、処理と転送が容易になります。

関連するコンテンツ