Event Notifications 페이로드

이 문서는 Event Notifications 사양에 대한 개요를 설명합니다.

소개

이 문서에서는 Event Notifications 의 API 소스를 사용하여 이벤트 알림을 전송하기 위한 페이로드 세부 정보를 설명합니다. API 소스를 사용하여 백엔드 애플리케이션에서 이벤트를 전송할 수 있습니다. 이 문서를 사용하여 비즈니스 백엔드에서 푸시 알림을 보낼 수 있습니다.

소스에 대한 스토어 알림을 활성화하여 수신 알림의 페이로드를 볼 수 있습니다. 자세한 내용은 알림 페이로드 보기를 참조하세요.

API 소스의 이벤트는 IBM 이메일 및 IBM SMS 대상으로 라우팅할 수 없습니다.

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

이벤트는 클라우드 이벤트 표준을 따릅니다. 여기에서 클라우드 이벤트에 대한 자세한 정보를 찾을 수 있습니다.

전송 모드

Event Notifications 는 다음 두 가지 모드를 지원하여 HTTP 호출을 수행합니다. 이는 클라우드 이벤트 사양을 준수하고 있습니다.

2진 모드

바이너리 콘텐츠 모드에서는 이벤트 data 값이 HTTP 요청 또는 응답 본문에 그대로 배치됩니다. datacontenttype 속성 값은 HTTP Content-Type 헤더에서 미디어 유형을 선언합니다. 다른 모든 이벤트 속성은 HTTP 헤더에 매핑됩니다.

모든 속성 이름 앞에는 ce- 가 붙고 헤더에 추가됩니다( data 및 datacontenttype 제외).

바이너리 모드는 알림을 보내는 데 권장되는 방식입니다.

구조화된 모드

구조화된 콘텐츠 모드에서 이벤트 메타데이터 속성과 이벤트 데이터는 HTTP 요청 본문에 배치됩니다. 구조화된 모드의 경우 Content-Type 헤더를 application/cloudevents+json 로 설정하십시오.

속성

CE 필수 속성

이벤트 요청을 승인하려면 다음 속성이 필수입니다.

ID(문자열)

각 이벤트를 식별하는 고유 식별자입니다. source+id은(는) 고유해야 합니다. 백엔드는 로그 및 기타 기록에서 이 ID를 고유하게 추적할 수 있어야 합니다. 각 전송 알림에 대해 고유 ID를 보냅니다. 알림 전송에 실패한 경우 동일한 아이디로 전송할 수 있습니다.

source+id 는 IBM Cloud 로깅 서비스에 로깅됩니다. 이러한 조합을 사용하여 IBM 고객은 한 시스템에서 다른 시스템으로의 이벤트 이동을 추적하고 디버깅 및 추적을 지원할 수 있습니다.

예

id: qwer-1234-1qsd-po94

2진 모드 헤더

ce-id: qwer-1234-1qsd-po94

source(URI-reference)

이는 이벤트 생성자의 식별자입니다. 이벤트의 소스를 고유하게 식별하는 방법입니다. IBM Cloud 서비스의 경우 이벤트를 생성하는 서비스 인스턴스의 crn입니다. API 소스의 경우 이는 이벤트 생성자 백엔드가 자신을 고유하게 식별할 수 있는 대상이 될 수 있습니다.

예

source: com.mybank.customerbanking.accountmanagement

2진 모드 헤더

ce-source: com.mybank.customerbanking.accountmanagement

specversion(string)

현재 Event Notifications 에서 지원하는 클라우드 이벤트 사양의 버전입니다. 이 값은 " 1.0 "로 설정해야 합니다.

예

specversion:1.0

2진 모드 헤더

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`

2진 모드 헤더

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진 모드 헤더 (예 2)

`ce-type:com.acmebank.password-changed`

CE 선택적 속성

다음 속성은 선택 사항이지만 Event Notifications 을 최대한 활용하기 위해 적극 권장됩니다.

시간(시간소인)

이벤트가 발생한 UTC 시간소인. RFC 3339 형식이어야 합니다.

예

time: 2022-02-10T10:51:37+00:00

2진 모드 헤더

ce-time: 2022-02-10T10:51:37+00:00

subject(String)

이는 이벤트 생성자(소스)에서 이벤트의 주제입니다. 따라서 이는 곧 만료될 비밀번호의 계정 ID일 수 있습니다.

예

subject:ajay@accts.acmebank.com`

2진 모드 헤더

`ce-subject:ajay@accts.acmebank.com`

datacontenttype

데이터 컨텐츠의 MIME 유형을 정의합니다. 현재는 "application/json"만 지원됩니다.

예

`datacontenttype: application/json`

2진 모드 헤더

`Content-Type:application/json`

데이터

이벤트의 페이로드. 여기에는 웹훅과 같은 대상에 전달할 수 있는 정보가 포함될 수 있습니다. 유효한 JSON 객체여야 합니다.

페이로드에 비밀번호, API 키, 개인 식별 번호, 신용카드 정보 또는 기타 기밀 데이터와 같은 민감한 정보를 포함하지 마세요. 페이로드는 다양한 대상에 기록, 저장 또는 전송될 수 있습니다.

예

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

바이너리 모드 - HTTP 본문의 일부입니다 N/A.

Event Notifications 확장 필수 속성

Event Notifications 으로 전송되는 모든 이벤트에 대한 필수 속성입니다.

ibmensourceid (문자열)

Event Notifications 에서 생성된 소스의 ID입니다. 이는 Event Notifications UI의 '소스' 섹션에서 확인할 수 있습니다.

예

ibmensourceid: 121313123:api

2진 모드 헤더

ce-ibmensourceid: 121313123:api

Event Notifications 확장 선택적 속성

이는 선택적 속성입니다.

ibmenseverity(문자열)

일부 소스는 이벤트 심각도의 개념을 가질 수 있습니다. 따라서 이벤트의 심각도를 지정하는 편리한 방법이 제공됩니다.

예

ibmenseverity:LOW

2진 모드 헤더

`ce-ibmenseverity:LOW`

ibmendefaultshort(String)

이 메시지는 사람이 읽을 수 있는 텍스트가 필요한 대상에게 라우팅되는 이벤트에 대상별 속성이 지정되지 않은 경우에 사용됩니다.

예를 들어 ibmenfcmbody 을 지정하지 않고 이벤트가 Android FCM 유형 대상으로 라우팅되는 경우 ibmendefaultshort 이 알림 제목(android_title)으로 사용됩니다.

예

ibmendefaultshort: "Change password"

2진 모드 헤더

ce-ibmendefaultshort: "Change password"

ibmendefaultlong(String)

이 메시지는 사람이 읽을 수 있는 텍스트가 필요한 대상에게 라우팅되는 이벤트에 대상별 속성이 지정되지 않은 경우에 사용됩니다.

예를 들어 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."

2진 모드 헤더

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(string/json)

이 속성은 Android 디바이스에 푸시 알림을 전송하려는 경우에 필요합니다. FCM 서버로 전송할 본문으로, 문자열 형식의 JSON이어야 합니다. FCM 본체에 대한 자세한 내용은 여기를 참조하세요.

알림 페이로드 샘플

"ibmenfcmbody": "{\"message\":{\"android\":{\"ttl\":\"86400s\",\"notification\":{\"click_action\":\"OPEN_ACTIVITY_1\"},\"data\":{\"id\":\"test_id\"}}}}"

2진 모드 헤더

ce-ibmenfcmbody: {"message":{"android":{"ttl":"86400s","notification":{"click_action":"OPEN_ACTIVITY_1"},"data":{"id":"test_id"}}}}

ibmenapnsbody(string/json)

이 속성은 iOS 디바이스로 푸시 알림을 전송하려는 경우에 필요합니다. APN 서버로 전송할 본문으로, 문자열 형식의 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 헤더를 제공하면 됩니다. 이들 중 일부는 키가 있는 경우 알림을 전달하는 것이 필수입니다. 필요한 본문은 다음과 같습니다.

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

APN 헤더에 대한 자세한 내용은 원격 알림 생성을 참조하세요.

2진 모드 헤더

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(string/json)

이 속성은 크롬 기기로 푸시 알림을 보내려는 경우 필요합니다. FCM 서버로 전송할 본문으로, 문자열 형식의 JSON이어야 합니다. 크롬 본문에 대한 자세한 내용은 알림을 참조하세요.

다음 예시를 따라 빠르게 시작할 수 있습니다:

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

크롬 푸시 알림을 맞춤 설정하려면 크롬 헤더를 제공하면 됩니다. 이들 중 일부는 키가 있는 경우 알림을 전달하는 것이 필수입니다. 예제 본문은 다음과 같습니다.

"ibmenchromeheaders":"{\"TTL\":100}"

2진 모드 헤더

ce-ibmenchromebody: {"title":"Hello Chrome", "options": {}}

ce-ibmenchromeheaders: "{"TTL":100}"

ibmenfirefoxbody(string/json)

Firefox 장치로 푸시 알림을 보내려면 이 속성이 필요합니다. Firefox 푸시 서버로 보낼 본문으로, 문자열 형식의 JSON이어야 합니다. Firefox 본문에 대한 자세한 내용은 알림을 참조하세요.

다음 예시를 따라 빠르게 시작할 수 있습니다:

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

크롬 푸시 알림을 맞춤 설정하려면 Firefox 헤더를 제공하면 됩니다. 이들 중 일부는 키가 있는 경우 알림을 전달하는 것이 필수입니다. 예제 본문은 다음과 같습니다.

"ibmenfirefoxheaders": "{\"TTL\":100, \"Urgency\": \"low\" , \"Topic\": \"Test Firefox Notifications\"}",

2진 모드 헤더

ce-ibmenfirefoxbody: {"title":"Hello Firefox", "options": {}}

ce-ibmenfirefoxheaders: {"TTL":100, "Urgency": "low" , "Topic": "Test Firefox Notifications"}

ibmensafaribody(string/json)

이 속성은 Safari 장치로 푸시 알림을 보내려는 경우 필요합니다. Apple 푸시 알림 서버로 전송할 본문으로, 문자열 형식의 JSON이어야 합니다. Safari 본문에 대한 자세한 내용은 Safari 푸시 알림 구성하기를 참조하세요.

다음 예시를 따라 빠르게 시작할 수 있습니다:

"ibmensafaribody": "{\"aps\":{\"alert\":{\"title\":\"Shipment Order 1832128321 Delevered\",\"body\":\"Shipment Order 1832128321 Delevered.\",\"action\":\"View\"},\"url-args\":[\"1832128321\"]}}"

2진 모드 헤더

ce-ibmensafaribody: {"aps":{"alert":{"title":"Shipment Order 1832128321 Delevered","body":"Shipment Order 1832128321 Delevered.","action":"View"},"url-args":["1832128321"]}}

이멘후아웨이바디(문자열/제이슨)

이 속성은 Huawei 디바이스로 푸시 알림을 보내려면 필요합니다. 이것은 화웨이 푸시 키트 서버로 전송할 본문이며, 문자열 형식의 JSON이어야 합니다. 화웨이 본체에 대한 자세한 내용은 화웨이 푸시 알림 페이로드를 참조하세요.

다음 예시를 따라 빠르게 시작할 수 있습니다:

"ibmenhuaweibody":"{\"message\":{\"android\":{\"notification\":{\"title\":\"New Message\",\"body\":\"Hello World\",\"click_action\":{\"type\":3}}}}}"

2진 모드 헤더

ce-ibmenhuaweibody: {"aps":{"alert":{"title":"Shipment Order 1832128321 Delevered","body":"Shipment Order 1832128321 Delevered.","action":"View"},"url-args":["1832128321"]}}

ibmenpushto(string/json)

이 속성은 Android, FCM, APNS 또는 Huawei 대상에 성공적으로 배달하려면 필수입니다.

여기에는 푸시 알림을 보낼 대상에 대한 세부 정보가 포함되어 있습니다. 이 필드도 JSON의 문자열 형식이며 다음 필드를 추가로 포함합니다

user_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 웹 디바이스의 고유 ID
firefox_devices - 알림을 대상으로 하려는 Firefox 웹 디바이스의 고유 ID
safari_devices - 알림을 대상으로 하려는 Safari 웹 디바이스의 고유 ID
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\"]}"

2진 모드 헤더

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

첨부 파일(배열)

이 속성은 사용자 지정 도메인 이메일 대상에 알림을 보낼 때 파일 첨부 파일을 포함하는 데 사용됩니다. 배열의 각 첨부 파일에는 파일 이름, 콘텐츠 유형 및 처분과 같은 메타데이터와 함께 Base64 형식으로 인코딩된 파일 콘텐츠가 포함되어야 합니다.

이메일 첨부 파일은 사용자 지정 도메인 이메일 대상에 대해서만 지원됩니다. 기본 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"
  }
]

2진 모드 헤더

ce-attachments: [{"content":"JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...","filename":"document.pdf","content_type":"application/pdf","disposition":"attachment"}]

사용 참고

첨부 파일에는 크기 제한이 적용됩니다. 총 페이로드 크기(모든 첨부 파일 포함)가 40MB를 초과하지 않도록 합니다.
이메일 알림당 최대 10개까지 파일을 첨부할 수 있습니다.
모든 파일 콘텐츠는 페이로드에 포함하기 전에 base64 인코딩해야 합니다.
attachments 배열에 여러 개의 개체를 추가하여 하나의 알림에 여러 개의 첨부파일을 포함할 수 있습니다.
이 기능은 사용자 지정 도메인 이메일 대상으로 알림을 보낼 때만 사용할 수 있습니다.
특정 파일 확장자는 보안상의 이유로 차단됩니다. 차단된 확장자의 전체 목록은 이메일 첨부 파일에 대해 차단된 파일 확장자는 무엇인가요?