Event Notifications ペイロード

本文書は、 Event Notifications 仕様について概説する。

概要

このドキュメントでは、 Event Notifications の API ソースを通じてイベント通知を送信する際のペイロードの詳細について説明します。 APIソースを使用すると、バックエンドアプリケーションから、カスタムメール、カスタムSMS、プッシュ通知、Webhookなど、設定済みの任意の送信先へイベントを送信することができます。

イベントをカスタムメールやカスタムSMSの送信先へルーティングするには、ペイロード内の「 ibmendefaultshort 」および「 ibmendefaultlong 」拡張属性に値を設定してください。 これらのフィールドは、EメールおよびSMSチャネル向けのデフォルトのメッセージ本文を指定します。 プッシュ通知の配信には、 ibmenfcmbodyibmenapnsbodyibmenchromebody など、配信先固有の属性を使用してください。

ソースに対して「イベントのキャプチャ」を有効にすることで、受信イベントのペイロードを確認できます。 詳細については、 通知のペイロードを表示するを 参照してください。

API ソースからのイベントは、他の IBM のメール宛先および IBM の SMS 宛先には転送できません。

`METHOD: POST`
`URL: /event-notifications/v1/apps/{instanceID}/notifications`
`Header: Authorization: Bearer <IAM token>`

イベントはクラウド・イベント標準に従います。 クラウド・イベントについて詳しくは、ここを参照してください。

トランスポートのモード

Event Notifications HTTP への呼び出しを行うために、以下の2つのモードをサポートしています。 これは、Cloud Events仕様に準拠しています。

バイナリー・モード

バイナリコンテンツモードでは、イベント data の値は、そのまま HTTP リクエストボディ(またはレスポンスボディ)に置かれる。 datacontenttype 属性値は、 HTTP Content-Type ヘッダでメディアタイプを宣言する。 その他のイベント属性はすべて、 HTTP ヘッダーにマッピングされる。

すべての属性名には「 ce- 」というプレフィックスが付けられ、ヘッダーに追加されます( data および datacontenttype を除く)。

通知の送信には、バイナリモードの使用が推奨されます。

構造化モード

構造化コンテンツモードでは、イベントのメタデータ属性とイベントデータが、 HTTP のリクエスト本文に格納されます。 構造化モードの場合は、 Content-Type ヘッダーを application/cloudevents+json に設定します。

属性

CE 必須属性

イベント要求を受け入れるには、以下の属性が必須です。

ID (String)

各イベントを識別する固有 ID。source+idは固有でなければなりません。 バックエンドは、ログやその他の記録において、このIDを一意に追跡できるものでなければならない。 通知を送信するたびに、一意のIDを送信してください。 通知の送信に失敗した場合、同じIDを送信することができます。

source+id は、 IBM Cloud ロギング・サービスに記録されます。 これらの組み合わせ( IBM )を使用することで、顧客はイベントがシステム間でどのように移動したかを追跡でき、デバッグやトレースに役立ちます。

id: qwer-1234-1qsd-po94
バイナリー・モード・ヘッダー
ce-id: qwer-1234-1qsd-po94

ソース (URI 参照)

これはイベント・プロデューサーの ID です。 イベントのソースを一意的に識別する方法。 IBM Cloud サービスの場合、これはイベントを生成するサービスインスタンスの crn である。 API ソースの場合、これは、イベント・プロデューサー・バックエンドがそれ自体を一意的に識別できるものである可能性があります。

source: com.mybank.customerbanking.accountmanagement
バイナリー・モード・ヘッダー
ce-source: com.mybank.customerbanking.accountmanagement

specversion (ストリング)

これは、 Event Notifications が現在サポートしている Cloud Events 仕様のバージョンである。 この値は「 1.0 」に設定する必要があります。

specversion:1.0
バイナリー・モード・ヘッダー
ce-specversion:1.0

タイプ (ストリング)

これは、イベントのタイプを記述します。 これは <event-type-name>:<sub-type> の形式です。 このタイプはプロデューサーによって定義されます。

イベントタイプの名前には、そのイベントタイプが一意に識別されるよう、逆DNS名をプレフィックスとして付ける必要があります。 同じイベントタイプが、2つの異なるソースから生成されることがあります。 _ の代わりに、ハイフン( - )を区切り文字として使用することを強くお勧めします。

例 1
`type:com.acmebank.password:expiring-in-15-days`
Type: `com.acmebank.password`
Sub type: `expiring-in-15-days`
バイナリー・モード・ヘッダー
ce-type:com.acmebank.password:expiring-in-15-days`
例 2
`type:com.acmebank.password-changed`
Type: `com.acmebank.password-changed`
Sub type: N/A
バイナリー・モード・ヘッダー (例 2)
`ce-type:com.acmebank.password-changed`

CE オプション属性

以下の属性はオプションですが、 Event Notifications の機能を最大限に活用するためには、設定することを強くお勧めします。

時刻 (タイム・スタンプ)

イベント発生時の UTC タイム・スタンプ。 RFC 3339 形式でなければなりません。

time: 2022-02-10T10:51:37+00:00
バイナリー・モード・ヘッダー
ce-time: 2022-02-10T10:51:37+00:00

subject (ストリング)

これは、イベント・プロデューサー (ソース) 内のイベントのサブジェクトです。 つまり、これは有効期限が迫っているパスワードのアカウント IDである可能性があります。

subject:ajay@accts.acmebank.com`
バイナリー・モード・ヘッダー
`ce-subject:ajay@accts.acmebank.com`

データ・コンテンツ・タイプ

データ内容の MIME タイプを定義します。 現在、「application/json」のみがサポートされています。

`datacontenttype: application/json`
バイナリー・モード・ヘッダー
`Content-Type:application/json`

データ

イベントのペイロードです。 これには、Webhook などの宛先に渡すことができる情報を含めることができます。 これは有効なJSONオブジェクトでなければなりません。

パスワード、APIキー、個人識別番号、クレジットカード情報などの機密情報をペイロードに含めないでください。 ペイロードは、ログに記録されたり、保存されたり、さまざまな宛先に送信されたりする。

data: { "lastchanged-days": "74", "reason":"time-based"}

バイナリモード – これは HTTP ボディの一部です(該当なし)。

Event Notifications 拡張の必須属性

これらは、 Event Notifications に送信されるすべてのイベントに必須の属性です。

ibmensourceid (ストリング)

これは、 Event Notifications で作成されたソースのIDです。 これは、 Event Notifications のUIにある「ソース」セクションで確認できます。

ibmensourceid: 121313123:api
バイナリー・モード・ヘッダー
ce-ibmensourceid: 121313123:api

Event Notifications 拡張のオプション属性

これらはオプションの属性です。

ibmenseverity (ストリング)

一部のソースには、イベント重大度の概念があります。 したがって、イベントの重大度を指定するための便利な方法が用意されています。

ibmenseverity:LOW
バイナリー・モード・ヘッダー
`ce-ibmenseverity:LOW`

ibmendefaultshort (ストリング)

このメッセージは、人間が読めるテキストを必要とする宛先にイベントがルーティングされたものの、宛先固有の属性が指定されていない場合に使用されます。

たとえば、 ibmenfcmbody が指定されておらず、イベントがAndroid FCMタイプの宛先にルーティングされた場合、 ibmendefaultshort が通知タイトル(android_title)として使用されます。

ibmendefaultshort: "Change password"
バイナリー・モード・ヘッダー
ce-ibmendefaultshort: "Change password"

ibmendefaultlong (ストリング)

このメッセージは、人間が読めるテキストを必要とする宛先にイベントがルーティングされたものの、宛先固有の属性が指定されていない場合に使用されます。

たとえば、 ibmenfcmbody が指定されておらず、イベントがAndroid FCMタイプの宛先にルーティングされた場合、 ibmendefaultlong が通知本文(アラート)として使用されます。

ibmendefaultlong: "Password will expire in 10 Days. Please log in to the Bank home page and click on Change Password link to change your password."
バイナリー・モード・ヘッダー
ce-ibmendefaultlong: "Password will expire in 10 Days. Please log in to the Bank home page and click on Change Password link to change your password."

ibmenfcmbody (文字列/json)

この属性は、Android デバイスにプッシュ通知を送信する場合に必要です。 これはFCMサーバーに送信する本体データです。JSON形式の文字列でなければなりません。 FCMボディの詳細については、 こちらをご覧ください。

通知ペイロードのサンプル
"ibmenfcmbody": "{\"message\":{\"android\":{\"ttl\":\"86400s\",\"notification\":{\"click_action\":\"OPEN_ACTIVITY_1\"},\"data\":{\"id\":\"test_id\"}}}}"
バイナリー・モード・ヘッダー
ce-ibmenfcmbody: {"message":{"android":{"ttl":"86400s","notification":{"click_action":"OPEN_ACTIVITY_1"},"data":{"id":"test_id"}}}}

ibmenapnsbody (文字列/json)

この属性は、iOS デバイスにプッシュ通知を送信する場合に必要です。 これはAPNsサーバーに送信する本体データです。JSON形式の文字列でなければなりません。 APN本体の詳細については、 こちらのドキュメントを参照されたい。

通知ペイロードのサンプル
"ibmenapnsbody": {"aps":{"alert":{"title":"Game Request","subtitle":"Five Card Draw","body":"Bob wants to play poker"},"category":"GAME_INVITATION"},"gameID":"12345678"}

APNsのプッシュ通知をカスタマイズするには、APNsヘッダーを指定することができます。 鍵が存在する場合に通知を送信する必要があるものもあります。 必要な本文は以下のとおりです。

ce-ibmenapnsbody: {"aps":{"alert":{"title":"Game Request","subtitle":"Five Card Draw","body":"Bob wants to play poker"},"category":"GAME_INVITATION"},"gameID":"12345678"}

APNヘッダーの詳細については、 リモート通知の生成を参照してください。

バイナリー・モード・ヘッダー
ce-ibmenapnsbody: {"en_data":{"alert":"alert","url":"https","badge":9,"sound":"bingbong.aiff","payload":{"myaarray":["cc75e4a6-edd8-3bec-a7c3-dfca6572a03b"]},"type":"DEFAULT","subtitle":"dummy","title":"dummy1","body":"body","ios_action_key":"key","interactive_category":"interactiveCategory","title_loc_key":"titleLocKey","loc_key":"GAME_PLAY_REQUEST_FORMAT","launch_image":"image.png","title_loc_args":["Shelly","Rick"],"loc_args":["Shelly","Rick"],"attachment_url":"some url","apns_collapse_id":"12","apns_thread_id":"1","apns_group_summary_arg":"apnsGroupSummaryArg","apns_group_summary_arg_count":1}}

ibmenchromebody (文字列/json)

Chromeデバイスにプッシュ通知を送信したい場合は、この属性が必要です。 これはFCMサーバーに送信する本文です。JSON形式の文字列でなければなりません。 クロームボディに関する詳細は、「 お知らせ 」を参照。

すぐに使い始めるには、以下の例を参考にしてください:

"ibmenchromebody": "{\"title\":\"Hello Chrome\", \"options\": {}}"

Chromeのプッシュ通知をカスタマイズするには、Chromeヘッダーを指定することができます。 鍵が存在する場合に通知を送信する必要があるものもあります。 本文の例を以下に示します。

"ibmenchromeheaders":"{\"TTL\":100}"
バイナリー・モード・ヘッダー
ce-ibmenchromebody: {"title":"Hello Chrome", "options": {}}
ce-ibmenchromeheaders: "{"TTL":100}"

ibmenfirefoxbody (文字列/json)

Firefox デバイスにプッシュ通知を送信するには、この属性が必要です。 これは、 Firefox のプッシュサーバーに送信する本文です。これは文字列形式のJSONでなければなりません。 Firefox、詳細は 「通知 」を参照のこと。

すぐに使い始めるには、以下の例を参考にしてください:

"ibmenfirefoxbody": "{\"title\":\"Hello Firefox\", \"options\": {}}"

Chromeのプッシュ通知をカスタマイズするには、 Firefox ヘッダーを設定してください。 鍵が存在する場合に通知を送信する必要があるものもあります。 本文の例を以下に示します。

"ibmenfirefoxheaders": "{\"TTL\":100, \"Urgency\": \"low\" , \"Topic\": \"Test Firefox Notifications\"}",
バイナリー・モード・ヘッダー
ce-ibmenfirefoxbody: {"title":"Hello Firefox", "options": {}}
ce-ibmenfirefoxheaders: {"TTL":100, "Urgency": "low" , "Topic": "Test Firefox Notifications"}

ibmensafaribody (文字列/json)

Safari搭載デバイスにプッシュ通知を送信するには、この属性が必要です。 これは、Apple Push Notification Server に送信したい本体データです。これは文字列形式の JSON でなければなりません。 Safari本体の詳細については、 Safariプッシュ通知の設定を参照してください。

すぐに使い始めるには、以下の例を参考にしてください:

"ibmensafaribody": "{\"aps\":{\"alert\":{\"title\":\"Shipment Order 1832128321 Delevered\",\"body\":\"Shipment Order 1832128321 Delevered.\",\"action\":\"View\"},\"url-args\":[\"1832128321\"]}}"
バイナリー・モード・ヘッダー
ce-ibmensafaribody: {"aps":{"alert":{"title":"Shipment Order 1832128321 Delevered","body":"Shipment Order 1832128321 Delevered.","action":"View"},"url-args":["1832128321"]}}

ibmenhuaweibody(文字列/json)

Huawei製デバイスにプッシュ通知を送信したい場合は、この属性が必要です。 Huawei Push Kitサーバーに送信する本文で、文字列形式のJSONでなければなりません。 Huawei本体に関する詳細は、 Huawei Push Notificationペイロードを 参照。

すぐに使い始めるには、以下の例を参考にしてください:

"ibmenhuaweibody":"{\"message\":{\"android\":{\"notification\":{\"title\":\"New Message\",\"body\":\"Hello World\",\"click_action\":{\"type\":3}}}}}"
バイナリー・モード・ヘッダー
ce-ibmenhuaweibody: {"aps":{"alert":{"title":"Shipment Order 1832128321 Delevered","body":"Shipment Order 1832128321 Delevered.","action":"View"},"url-args":["1832128321"]}}

ibmenpushto (文字列/json)

この属性は、Android、FCM、APNS、またはHuaweiの配信先への正常な配信に必須です。

ここには、プッシュ通知を送信したい宛先に関する詳細が記載されています。 このフィールドはJSONの文字列形式でもあり、さらに以下のフィールドを含んでいます

  • user_id – デバイスに関連付けるユーザーID。通知の配信先として指定したいユーザーID
  • tag-これは、登録済みタグに関する通知を送信するために使用されます
  • platform- プラットフォームごとに、登録済みのすべてのデバイスを対象に設定できます。

以下は、各ターゲットタイプに対応するプラットフォーム値です。

  • FCM: push_android
  • APNS: push_ios
  • Chrome: push_chrome
  • Firefox: push_firefox
  • Safari: push_safari
  • Huawei: push_huawei
  • fcm_devices-通知のターゲットにする FCM デバイスの固有 ID
  • apns_devices-通知のターゲットにする APNS デバイスの固有 ID
  • chrome_devices-通知のターゲットにする Chrome Web デバイスの固有 ID
  • firefox_devices-通知のターゲットにする Firefox Web デバイスの固有 ID
  • safari_devices-通知のターゲットにする Safari Web デバイスの固有 ID
  • huawei_devices- 通知の配信先とするHuawei Webデバイスの一意の識別子
"ibmenpushto": "{\"fcm_devices\": [\"9c75975a-37d0-3898-905d-3b5ee0d7c172\",\"C9CACDF5-6EBF-49E1-AD60-E25BA23E954C\"]}"`
"ibmenpushto": "{\"apns_devices\": [\"1c75972a-37d0-3898-905d-3b5ee0d7c172\",\"M9CACDF5-1EBF-49E1-AD60-E25BA23E954C\"]}"
"ibmenpushto": "{\"chrome_devices\": [\"2c75972a-37d0-3898-905d-3b5ee0d7c182\",\"N9CACDF5-1EBF-49E1-AD60-E25BA23E994D\"]}"
"ibmenpushto": "{\"firefox_devices\": [\"3c75972a-37d0-3898-905d-3b5ee0d7c182\",\"L9CACDF5-1EBF-49E1-AD60-E25BA23E994E\"]}"
"ibmenpushto": "{\"safari_devices\": [\"1175972a-37d0-3898-905d-3b5ee0d7c1D2\",\"Q9CACDF5-1EBF-49E1-AD60-E25BA23E994N\"]}"
"ibmenpushto": "{\"huawei_devices\": [\"1175972a-37d0-3898-905d-3b5ee0d7c1D2\",\"Q9CACDF5-1EBF-49E1-AD60-E25BA23E994N\"]}"

以下の方法を使用することで、複数の宛先を指定することができます

"ibmenpushto": "{\"fcm_devices\": [\"9c75975a-37d0-3898-905d-3b5ee0d7c172\",\"C9CACDF5-6EBF-49E1-AD60-E25BA23E954C\"],\"apns_devices\": [\"1c75972a-37d0-3898-905d-3b5ee0d7c172\",\"M9CACDF5-1EBF-49E1-AD60-E25BA23E954C\"],\"chrome_devices\": [\"2c75972a-37d0-3898-905d-3b5ee0d7c182\",\"N9CACDF5-1EBF-49E1-AD60-E25BA23E994D\"],\"firefox_devices\": [\"3c75972a-37d0-3898-905d-3b5ee0d7c182\",\"L9CACDF5-1EBF-49E1-AD60-E25BA23E994E\"],\"safari_devices\": [\"1175972a-37d0-3898-905d-3b5ee0d7c1D2\",\"Q9CACDF5-1EBF-49E1-AD60-E25BA23E994N\"]}"

プッシュ・ユーザー ID への通知のターゲット設定。

"ibmenpushto": "{\"user_ids\": [\"ajay@accts.acmebank.com\",\"ankit@accts.acmebank.com\"]}"

プッシュ・タグに対する通知のターゲット設定。

"ibmenpushto": "{\"tags\": [\"salesTeam\",\"TechTeam\"]}"

プラットフォームへの通知のターゲット設定。

"ibmenpushto": "{\"platforms\":[\"push_android\",\"push_ios\"]]}"

特定のプラットフォームを対象とした通知。

"ibmenpushto": "{\"platforms\":[\"push_android\"]}"
"ibmenpushto": "{\"platforms\":[\"push_ios\"]}"
"ibmenpushto": "{\"platforms\":[\"push_chrome\"]}"
"ibmenpushto": "{\"platforms\":[\"push_firefox\"]}"
"ibmenpushto": "{\"platforms\":[\"push_safari\"]}"
"ibmenpushto": "{\"platforms\":[\"push_huawei\"]}"
バイナリー・モード・ヘッダー
ce-ibmenpushto: "{\"user_id\": [\"ajay@accts.acmebank.com\",\"ankit@accts.acmebank.com\"]}"

添付ファイル(配列)

この属性は、カスタムドメインの電子メール宛先に通知を送信する際に、添付ファイルを含めるために使用されます。 配列内の各添付ファイルには、 Base64 形式でエンコードされたファイルコンテンツと、ファイル名、コンテンツタイプ、disposition などのメタデータが含まれていなければなりません。

電子メールの添付ファイルは、カスタムドメインの電子メール宛先でのみサポートされています。 この機能は、デフォルトの IBM Cloud 電子メール宛先では使用できません。

attachments 配列には、以下のプロパティを持つオブジェクトが含まれる:

内容 (文字列, 必須)

base64 フォーマットでエンコードされたファイルの内容。

ペイロードに含める前に、コンテンツが適切にエンコードされていることを確認してください。

ファイル名 (文字列、必須)

受信者に表示されるファイル名。 ファイルの拡張子を含める(例: " document.pdf ", " report.xlsx " )。

content_type (文字列。必須ではありません。)

ファイルのMIMEタイプ。 一般的な例としては、以下のようなものがあります:

  • application/pdf PDFファイル用
処分 (文字列、必須)

ファイルが添付ファイルであることを示すには、 attachment を使用します。

"attachments": [
  {
    "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...",
    "filename": "document.pdf",
    "content_type": "application/pdf",
    "disposition": "attachment"
  },
  {
    "content": "UEsDBBQAAAAIAKt8elYAAAAAAAAAAAAAAAAJAAAA...",
    "filename": "report.xlsx",
    "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "disposition": "attachment"
  }
]
バイナリー・モード・ヘッダー
ce-attachments: [{"content":"JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...","filename":"document.pdf","content_type":"application/pdf","disposition":"attachment"}]
使用上の注意
  • 添付ファイルのサイズには制限があります。 ペイロードの合計サイズ(すべての添付ファイルを含む)が40MBを超えないようにしてください。
  • 1通の通知メールに添付できるファイルは最大10個です。
  • すべてのファイル・コンテンツは、ペイロードに含める前に、 base64 エンコードされなければならない。
  • attachments 配列に複数のオブジェクトを追加することで、1つの通知に複数の添付ファイルを含めることができます。
  • この機能は、カスタムドメインの電子メール宛先に通知を送信する場合にのみ使用できます。
  • 特定のファイル拡張子は、セキュリティ上の理由からブロックされています。 ブロックされる拡張子の完全なリストについては、 電子メールの添付ファイルでブロックされるファイル拡張子は?