พุชเดี่ยวแบบกลุ่ม API
API การส่งข้อความแบบเดี่ยวในรูปแบบแบตช์ (Batch Single Push API)
คำอธิบายฟังก์ชัน
ใช้สำหรับการส่งข้อความแบบเดี่ยวในรูปแบบแบตช์ ซึ่งทำให้ผู้ใช้หลายรายสามารถได้รับการแจ้งเตือนในคำขอเดียว รองรับการส่งข้อความผ่าน registration_id
หรือ alias
:
การส่งข้อความผ่าน registration_id:
POST /v4/batch/push/regid
การส่งข้อความผ่าน alias:
POST /v4/batch/push/alias
ขีดจำกัดความสามารถ:
- รองรับการส่งข้อความสูงสุด 500 เป้าหมาย ต่อคำขอ
- รองรับการประมวลผลพร้อมกันเพื่อประสิทธิภาพที่สูงขึ้น
- คืนผลลัพธ์บางส่วนเมื่อมีการจำกัดการใช้งาน
- API นี้และ Push API ใช้โควต้าของ QPS เดียวกัน การใช้ Batch Push API เพื่อส่ง 1 regid หรือ 1 alias จะใช้โควต้าของ Push API 1 คิว
การยืนยันตัวตน
เพิ่มฟิลด์การยืนยันตัวตนใน HTTP Header:
Authorization: Basic ${base64_auth_string}
Authorization: Basic ${base64_auth_string}
โค้ดนี้โชว์เป็นหน้าต่างลอย
วิธีการสร้าง:
base64(username:password)
username
=AppKey
ของแอปพลิเคชันpassword
=Master Secret
เส้นทางการเข้าถึง: Console → Application Settings → Application Info
จุดสิ้นสุด
- การส่งข้อความแบตช์ผ่าน registration_id
POST /v4/batch/push/regid
POST /v4/batch/push/regid
โค้ดนี้โชว์เป็นหน้าต่างลอย
- การส่งข้อความแบตช์ผ่าน alias
POST /v4/batch/push/alias
POST /v4/batch/push/alias
โค้ดนี้โชว์เป็นหน้าต่างลอย
ตัวอย่างคำขอ
1. การส่งข้อความแบตช์ผ่าน registration_id
curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/regid \
-H "Content-Type: application/json" \
-u "AppKey:MasterSecret" \
-d '{
"requests": [
{
"target": "registration_id_1",
"platform": "android",
"notification": {
"android": {
"alert": "Hi, Push!",
"title": "Send to Android",
"builder_id": 1,
"extras": { "newsid": 321 }
}
},
"options": {
"time_to_live": 60,
"apns_production": false
},
"custom_args": { "business": "info" }
},
{
"target": "registration_id_2",
"platform": "ios",
"notification": {
"ios": {
"alert": "Hi, MTPush!",
"sound": "default",
"badge": "+1",
"extras": { "newsid": 321 }
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
}
]
}'
curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/regid \
-H "Content-Type: application/json" \
-u "AppKey:MasterSecret" \
-d '{
"requests": [
{
"target": "registration_id_1",
"platform": "android",
"notification": {
"android": {
"alert": "Hi, Push!",
"title": "Send to Android",
"builder_id": 1,
"extras": { "newsid": 321 }
}
},
"options": {
"time_to_live": 60,
"apns_production": false
},
"custom_args": { "business": "info" }
},
{
"target": "registration_id_2",
"platform": "ios",
"notification": {
"ios": {
"alert": "Hi, MTPush!",
"sound": "default",
"badge": "+1",
"extras": { "newsid": 321 }
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
}
]
}'
โค้ดนี้โชว์เป็นหน้าต่างลอย
2. การส่งข้อความแบตช์ผ่าน alias
curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/alias \
-H "Content-Type: application/json" \
-u "AppKey:MasterSecret" \
-d '{
"requests": [
{
"target": "user_alias_1",
"platform": "all",
"notification": {
"android": { "alert": "Hi, Push!", "title": "Send to Android" },
"ios": { "alert": "Hi, MTPush!", "sound": "default" }
},
"options": {
"time_to_live": 60,
"apns_production": false
}
},
{
"target": "user_alias_2",
"platform": "ios",
"notification": {
"ios": {
"alert": "Hi, MTPush!",
"sound": "default",
"badge": "+1",
"extras": { "newsid": 321 }
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
}
]
}'
curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/alias \
-H "Content-Type: application/json" \
-u "AppKey:MasterSecret" \
-d '{
"requests": [
{
"target": "user_alias_1",
"platform": "all",
"notification": {
"android": { "alert": "Hi, Push!", "title": "Send to Android" },
"ios": { "alert": "Hi, MTPush!", "sound": "default" }
},
"options": {
"time_to_live": 60,
"apns_production": false
}
},
{
"target": "user_alias_2",
"platform": "ios",
"notification": {
"ios": {
"alert": "Hi, MTPush!",
"sound": "default",
"badge": "+1",
"extras": { "newsid": 321 }
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
}
]
}'
โค้ดนี้โชว์เป็นหน้าต่างลอย
พารามิเตอร์คำขอ
โครงสร้างเนื้อหาคำขอ:
{
"requests": [
{
"target": "string", // จำเป็น, เป้าหมายการส่ง (registration_id หรือ alias)
"platform": "string", // จำเป็น, แพลตฟอร์มการส่ง (android/ios/all)
"notification": "object", // ไม่จำเป็น, เนื้อหาการแจ้งเตือน (ดูที่ Push API)
"message": "object", // ไม่จำเป็น, ข้อความที่กำหนดเอง (ดูที่ Push API), ไม่สามารถอยู่ร่วมกับ notification ได้
"options": "object", // ไม่จำเป็น, ตัวเลือกการส่ง (ดูที่ Push API)
"custom_args": "object" // ไม่จำเป็น, พารามิเตอร์ที่ส่งไปยังไคลเอนต์
}
]
}
{
"requests": [
{
"target": "string", // จำเป็น, เป้าหมายการส่ง (registration_id หรือ alias)
"platform": "string", // จำเป็น, แพลตฟอร์มการส่ง (android/ios/all)
"notification": "object", // ไม่จำเป็น, เนื้อหาการแจ้งเตือน (ดูที่ Push API)
"message": "object", // ไม่จำเป็น, ข้อความที่กำหนดเอง (ดูที่ Push API), ไม่สามารถอยู่ร่วมกับ notification ได้
"options": "object", // ไม่จำเป็น, ตัวเลือกการส่ง (ดูที่ Push API)
"custom_args": "object" // ไม่จำเป็น, พารามิเตอร์ที่ส่งไปยังไคลเอนต์
}
]
}
โค้ดนี้โชว์เป็นหน้าต่างลอย
คำอธิบายพารามิเตอร์:
ฟิลด์ | จำเป็น | ประเภท | คำอธิบาย |
---|---|---|---|
requests |
ใช่ | array | อาร์เรย์คำขอแบบกลุ่ม (สูงสุด 500 รายการ, target ต้องไม่ซ้ำกันในแต่ละกลุ่ม) |
target |
ใช่ | string | ค่าเป้าหมาย: - /regid endpoint: registration_id - /alias endpoint: alias |
platform |
ใช่ | string | แพลตฟอร์มการส่ง: android , ios , หรือ all |
notification |
ไม่ | object | เนื้อหาการแจ้งเตือน (โครงสร้างเดียวกับ Single Push API) |
message |
ไม่ | object | ข้อความที่กำหนดเอง (โครงสร้างเดียวกับ Single Push API) |
options |
ไม่ | object | ตัวเลือกการส่ง (เช่น time_to_live , apns_production ) |
custom_args |
ไม่ | object | พารามิเตอร์ที่กำหนดเองสำหรับส่งผ่าน |
ตัวอย่างการตอบกลับ
การตอบกลับสำเร็จ (สำเร็จทั้งหมด)
{
"results": {
"registration_id_1": {
"target": "registration_id_1",
"success": true,
"msg_id": 2460001
},
"registration_id_2": {
"target": "registration_id_2",
"success": true,
"msg_id": 2460002
}
}
}
{
"results": {
"registration_id_1": {
"target": "registration_id_1",
"success": true,
"msg_id": 2460001
},
"registration_id_2": {
"target": "registration_id_2",
"success": true,
"msg_id": 2460002
}
}
}
โค้ดนี้โชว์เป็นหน้าต่างลอย
การตอบกลับที่สำเร็จ (การจำกัดอัตรา)
การตอบกลับสำเร็จ (บางส่วนถูกจำกัดอัตรา)
{
"rate_limit_info": {
"message": "Some requests were rate limited during batch processing",
"rate_limit_occurred": true
},
"results": {
"170976fa8a0771c2647": {
"target": "170976fa8a0771c2647",
"success": false,
"error": {
"code": 23008,
"message": "Rate limit exceeded for the API"
}
},
"170976fa8a9277c25d4": {
"target": "170976fa8a9277c25d4",
"success": false,
"error": {
"code": 23008,
"message": "Rate limit exceeded for the API"
}
}
}
}
{
"rate_limit_info": {
"message": "Some requests were rate limited during batch processing",
"rate_limit_occurred": true
},
"results": {
"170976fa8a0771c2647": {
"target": "170976fa8a0771c2647",
"success": false,
"error": {
"code": 23008,
"message": "Rate limit exceeded for the API"
}
},
"170976fa8a9277c25d4": {
"target": "170976fa8a9277c25d4",
"success": false,
"error": {
"code": 23008,
"message": "Rate limit exceeded for the API"
}
}
}
}
โค้ดนี้โชว์เป็นหน้าต่างลอย
การตอบกลับที่ล้มเหลว (ข้อผิดพลาดทั่วไป)
การตอบกลับล้มเหลว (ข้อผิดพลาดทั่วไป)
{
"error": {
"code": 21004,
"message": "basic auth failed"
}
}
{
"error": {
"code": 21004,
"message": "basic auth failed"
}
}
โค้ดนี้โชว์เป็นหน้าต่างลอย
การตอบกลับล้มเหลว (ข้อผิดพลาดของพารามิเตอร์)
{
"error": {
"code": 21003,
"message": "Parameter value is invalid"
}
}
{
"error": {
"code": 21003,
"message": "Parameter value is invalid"
}
}
โค้ดนี้โชว์เป็นหน้าต่างลอย
อ้างอิงรหัสข้อผิดพลาด
รหัสข้อผิดพลาด | คำอธิบาย | วิธีการแก้ไข | สถานะ HTTP |
---|---|---|---|
รหัสข้อผิดพลาดทั่วไป | |||
21004 | การยืนยันตัวตนล้มเหลว | ตรวจสอบ AppKey/MasterSecret | 401 |
21008 | ความยาว AppKey ไม่ใช่ 24 ตัวอักษร | ตรวจสอบรูปแบบ AppKey | 400 |
21038 | ไม่มีสิทธิ์การส่งข้อความสำหรับแอป | ตรวจสอบการตั้งค่าแอป | 400 |
21043 | ไม่มีสิทธิ์การส่งข้อความ (รอการชำระเงิน) | แก้ไขปัญหาการชำระเงิน | 400 |
23009 | IP ไม่อยู่ในรายการที่อนุญาต | เพิ่ม IP เซิร์ฟเวอร์ในรายการที่อนุญาต | 400 |
21009 | ข้อผิดพลาดระบบภายใน (ไม่ต้องลองใหม่) | ติดต่อฝ่ายสนับสนุนทางเทคนิค | 400 |
ข้อผิดพลาดการจำกัดอัตรา | |||
23008 | ถึงขีดจำกัดอัตรา API | ลองรายการที่ล้มเหลวใหม่หากสำเร็จบางส่วน | 400 |
ข้อผิดพลาดของพารามิเตอร์ | |||
21003 | ค่าในพารามิเตอร์ไม่ถูกต้อง | ตรวจสอบรูปแบบเนื้อหาคำขอ | 400 |
21015 | พารามิเตอร์คำขอไม่ถูกต้อง | ตรวจสอบฟิลด์ที่จำเป็น | 400 |
21016 | การตรวจสอบพารามิเตอร์ล้มเหลว | ตรวจสอบประเภทฟิลด์และช่วงค่า | 400 |
รหัสข้อผิดพลาดทั้งหมด: Create Push API - Response
หมายเหตุ
- การจัดการการจำกัดอัตรา: ส่งคืนผลลัพธ์บางส่วนเมื่อมีการจำกัดอัตรา (
msg_id
สำหรับสำเร็จ +error
สำหรับล้มเหลว) - การตรวจสอบความซ้ำซ้อน: ค่า
target
หรือcid
ทั้งหมดต้องไม่ซ้ำกันในแต่ละกลุ่ม - ข้อจำกัดปริมาณ: สูงสุด 500 เป้าหมายต่อคำขอ
- การจัดการข้อผิดพลาด: ข้อผิดพลาดทั่วไป (เช่น การยืนยันตัวตนล้มเหลว) จะหยุดทันทีโดยไม่มีผลลัพธ์บางส่วน