IBM Cloud Docs
Event Notifications 有效内容

Event Notifications 有效内容

本文档概述了 Event Notifications 规范。

简介

本文档介绍了使用 Event Notifications 中的 API 源发送事件通知的有效载荷详情。 API 源可用于从后端应用程序发送事件。 您可以使用本文档从业务后台发送推送通知。

来自 API 源的事件无法路由到 IBM 电子邮件和 IBM 短信目的地。

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

这些事件遵循云事件标准。 您可以在此处找到有关云事件的更多信息。

运输方式

Event Notifications 支持以下两种模式拨打 电话。HTTP 这符合云事件规范。

二进制方式

在二进制内容模式下，事件 data 的值会原封不动地放入 HTTP 请求或响应体。 datacontenttype 属性值在 HTTP Content-Type 标头中声明其媒体类型。 所有其他事件属性都映射到 HTTP 标头。

所有属性名称都以 ce- 为前缀，并添加到头中 ( data 和 datacontenttype 除外)。

二进制模式是发送通知的推荐方式。

结构化方式

在结构化内容模式下，事件元数据属性和事件数据被放入 HTTP 请求正文中。 对于结构化方式，将 Content-Type 头设置为 application/cloudevents+json。

Attributes

CE 必需属性

要接受事件请求，以下属性是必需的。

ID（字符串）

标识每个事件的唯一标识。source+id 必须唯一。 后台应能在日志和其他记录中唯一跟踪该 ID。 为每个发送通知发送一个唯一 ID。 如果发送通知失败，也可发送相同的 ID。

source+id 已记录在 IBM Cloud 日志记录服务中。 使用这些组合 IBM，客户能够追踪事件从一个系统到另一个系统的移动，并有助于调试和追踪。

示例
id: qwer-1234-1qsd-po94
二进制方式头
ce-id: qwer-1234-1qsd-po94

源 (URI-reference)

这是事件生产者的标识。 一种唯一标识事件源的方法。 对于 IBM Cloud 服务，这是产生事件的服务实例的 crn。 对于 API 源，这可能是事件生产者后端唯一标识自身的内容。

示例
source: com.mybank.customerbanking.accountmanagement
二进制方式头
ce-source: com.mybank.customerbanking.accountmanagement

specversion (字符串)

这是 Event Notifications 当前支持的云事件规范版本。 该值必须设置为 " 1.0 "。

示例
specversion:1.0
二进制方式头
ce-specversion:1.0

type (String)

这描述了事件的类型。 格式为 <event-type-name>:<sub-type>。 此类型由生产者定义。

事件类型名称必须以逆向 DNS 名称作为前缀，以便唯一地标识事件类型。 同一事件类型可以由两个不同的源生成。 强烈建议使用连字符 - 作为分隔符，而不是 _。

示例 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: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 不适用正文的一部分。

Event Notifications 扩展必需属性

这些是发送到 Event Notifications的每个事件的必需属性。

ibmens源标识 (字符串)

这是在 Event Notifications中创建的源的标识。 这在“源”部分的 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（Firebase Cloud Messaging）服务器的正文，必须是字符串格式的 JSON。 有关 FCM 主体的更多信息，请参见 REST 资源：projects.messages。

为了与现有推送通知客户的较早版本兼容，仍支持先前的统一数据格式，但不推荐使用。

示例通知有效载荷示例：
"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"}

要定制 APN 推送通知，可以提供 APN 头。 如果存在密钥，那么其中部分必须交付通知。 所需主体如下所示:

"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)

如果要向 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 Push 服务器的正文，必须是字符串格式的 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(string/json)

如果要向华为设备发送推送通知，则需要此属性。 这是要发送到华为 Push Kit 服务器的正文，必须是字符串格式的 JSON。 有关华为主体的更多信息，请参阅“华为推送通知有效载荷”。

您可以按照这些示例快速入门：

"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 或华为目标发送信息，必须使用此属性。

其中包含要发送推送通知的目的地的详细信息。 该字段也是 JSON 字符串格式，并进一步包含以下字段

  • user_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 设备的唯一标识
  • apns_devices-要将通知作为目标的 APNS 设备的唯一标识
  • chrome_devices-要将通知作为目标的 Chrome Web 设备的唯一标识
  • firefox_devices-要将通知作为目标的 Firefox Web 设备的唯一标识
  • safari_devices-要将通知作为目标的 Safari Web 设备的唯一标识
  • huawei_devices- 华为网络设备的唯一标识符，您希望将其作为通知目标
示例
"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\"]}"

要推送 user_ids 的目标通知。

"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\"]}"