Event Notifications ペイロード
この文書では、 Event Notifications の仕様の概要を示します。
概要
このドキュメントでは、 Event Notifications の API ソースを使用してイベント通知を送信するためのペイロードの詳細について説明します。 API ソースを使用して、バックエンド・アプリケーションからイベントを送信できます。 このドキュメントは、ビジネスバックエンドからPush通知を送信するために使用できます。
APIソースからのイベントは、 IBM Eメールおよび IBM SMS宛先にはルーティングできません。
`METHOD: POST`
`URL: /event-notifications/v1/apps/{instanceID}/notifications`
`Header: Authorization: Bearer <IAM token>`
イベントはクラウド・イベント標準に従います。 クラウド・イベントについて詳しくは、ここを参照してください。
トランスポートのモード
Event Notifications は、 通話するために、以下の2つのモードをサポートしています。 HTTP これは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オブジェクトでなければならない。
例
data: { "lastchanged-days": "74", "reason":"time-based"}
バイナリ・モード - これは HTTP ボディN/Aの一部である。
Event Notifications 拡張の必須属性
これらは、 Event Notifications に送信されるすべてのイベントに必須の属性である。
ibmensourceid (ストリング)
これは Event Notifications で作成されるソースのIDである。 これは、 Event Notifications UIの "Sources "セクションで利用できる。
例
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(Firebase Cloud Messaging)サーバーに送信するボディで、文字列形式のJSONでなければなりません。 FCM本体の詳細については、 REST Resource: projects.messages を参照。
既存のPush通知ユーザー向けの旧バージョンとの互換性のため、以前の統一データ形式はまだサポートされていますが、非推奨となっています。
例通知ペイロードの例:
"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 (Apple Push Notification Service)サーバーに送信する本文で、文字列形式のJSONでなければなりません。 APN本体の詳細については、 リモート通知ペイロードの作成を参照してください。
既存のPush通知ユーザー向けの旧バージョンとの互換性のため、以前の統一データ形式はまだサポートされていますが、非推奨となっています。
通知ペイロードのサンプル:
"ibmenapnsbody": {"aps":{"alert":{"title":"Game Request","subtitle":"Five Card Draw","body":"Bob wants to play poker"},"category":"GAME_INVITATION"},"gameID":"12345678"}
APNsプッシュ通知をカスタマイズするには、APNsヘッダーを指定します。 鍵が存在する場合に通知を送信する必要があるものもあります。 必要な本文は以下のとおりです。
"ibmenapnsheaders": "{\"apns-priority\":10, \"apns-collapse-id\": \"collapse\"}"
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)
この属性は、クローム端末にプッシュ通知を送信する場合に必要です。 これはFCMサーバーに送信するボディで、文字列形式のJSONでなければなりません。 クロームボディに関する詳細は、「 お知らせ 」を参照。
手っ取り早く始めるには、以下の例に従ってください:
"ibmenchromebody": "{\"title\":\"Hello Chrome\", \"options\": {}}"
クロームプッシュ通知をカスタマイズするには、クロームヘッダを指定します。 鍵が存在する場合に通知を送信する必要があるものもあります。 本文の例を以下に示します。
"ibmenchromeheaders":"{\"TTL\":100}"
バイナリー・モード・ヘッダー
ce-ibmenchromebody: {"title":"Hello Chrome", "options": {}}
ce-ibmenchromeheaders: "{"TTL":100}"
ibmenfirefoxbody (文字列/json)
この属性は、 Firefox デバイスにプッシュ通知を送信したい場合に必要です。 Firefox Pushサーバーに送信する本文です。文字列形式のJSONでなければなりません。 Firefox、詳細は 「通知 」を参照のこと。
手っ取り早く始めるには、以下の例に従ってください:
"ibmenfirefoxbody": "{\"title\":\"Hello Firefox\", \"options\": {}}"
クロームのプッシュ通知をカスタマイズするには、 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 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
- デバイスに関連付けられるユーザーIDtag
-これは、登録済みタグに関する通知を送信するために使用されますplatform
- プラットフォームごとに登録されたすべてのデバイスを対象とすることができます。
以下は、各ターゲットに対応するプラットフォームの値である。
FCM
: push_androidAPNS
: push_iosChrome
: push_chromeFirefox
: push_firefoxSafari
: push_safariHuawei
: push_huaweifcm_devices
-通知のターゲットにする FCM デバイスの固有 IDapns_devices
-通知のターゲットにする APNS デバイスの固有 IDchrome_devices
-通知のターゲットにする Chrome Web デバイスの固有 IDfirefox_devices
-通知のターゲットにする Firefox Web デバイスの固有 IDsafari_devices
-通知のターゲットにする Safari Web デバイスの固有 IDhuawei_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\"]}"