พุชเดี่ยวแบบกลุ่ม API
Batch Single Push API
คำอธิบายฟังก์ชัน
ใช้สำหรับการส่ง push notification แบบกลุ่มให้กับผู้ใช้หลายรายในครั้งเดียว โดยรองรับการส่งผ่าน registration_id
หรือ alias
:
- ส่งผ่าน registration_id:
POST /v4/batch/push/regid
- ส่งผ่าน alias:
POST /v4/batch/push/alias
- ข้อจำกัดความสามารถ:
- สูงสุด 500 เป้าหมาย ต่อคำขอ
- รองรับการประมวลผลพร้อมกันเพื่อประสิทธิภาพ
- คืนผลลัพธ์บางส่วนเมื่อเกิดการจำกัดอัตราการเรียก
- API นี้และ https://www.engagelab.com/docs/app-push/developer-guide/rest-api/create-push-api ใช้โควตา QPS ร่วมกัน การใช้ API แบบกลุ่มเพื่อ push 1 regid หรือ 1 alias จะใช้โควตา QPS ของ Push API 1 ครั้ง
การรับรองความถูกต้อง
เพิ่มฟิลด์การรับรองความถูกต้องใน HTTP Header:
Authorization: Basic ${base64_auth_string}
Authorization: Basic ${base64_auth_string}
โค้ดนี้โชว์เป็นหน้าต่างลอย
- วิธีการสร้าง:
base64(username:password)
username
=AppKey
ของแอปพลิเคชันpassword
=Master Secret
- เส้นทางการเข้าถึง: คอนโซล → การตั้งค่าแอปพลิเคชัน → ข้อมูลแอปพลิเคชัน
จุดปลายทาง
- ส่งแบบกลุ่มผ่าน 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://webpushapi-sgp.engagelab.com/v4/batch/push/regid \
-H "Content-Type: application/json" \
-u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
-d '{
"requests": [
{
"target": "registration_id_1",
"platform": "web",
"notification": {
"alert": "Hi,Push !",
"web": {
"alert": "Hi,Push !",
"title": "web_push",
"url": "http://www.google.com",
"extras": {
"web-key1": "web-value1"
}
}
},
"options": {
"time_to_live": 60,
"apns_production": false
},
"custom_args": {
"business": "info"
}
},
{
"target": "registration_id_2",
"platform": "web",
"notification": {
"alert": "Hi,MTPush !",
"web": {
"alert": "Hi,MTPush !",
"title": "web_push",
"url": "http://www.google.com",
"extras": {
"web-key1": "web-value1"
}
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
}
]
}'
curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/regid \
-H "Content-Type: application/json" \
-u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
-d '{
"requests": [
{
"target": "registration_id_1",
"platform": "web",
"notification": {
"alert": "Hi,Push !",
"web": {
"alert": "Hi,Push !",
"title": "web_push",
"url": "http://www.google.com",
"extras": {
"web-key1": "web-value1"
}
}
},
"options": {
"time_to_live": 60,
"apns_production": false
},
"custom_args": {
"business": "info"
}
},
{
"target": "registration_id_2",
"platform": "web",
"notification": {
"alert": "Hi,MTPush !",
"web": {
"alert": "Hi,MTPush !",
"title": "web_push",
"url": "http://www.google.com",
"extras": {
"web-key1": "web-value1"
}
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
}
]
}'
โค้ดนี้โชว์เป็นหน้าต่างลอย
2. ส่งแบบกลุ่มผ่าน alias
curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/alias \
-H "Content-Type: application/json" \
-u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
-d '{
"requests": [
{
"target": "user_alias_1",
"platform": "web",
"notification": {
"alert": "Hi,Push !",
"web": {
"alert": "Hi,Push !",
"title": "web_push",
"url": "http://www.google.com",
"extras": {
"web-key1": "web-value1"
}
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
},
{
"target": "user_alias_2",
"platform": "web",
"notification": {
"alert": "Hi,MTPush !",
"web": {
"alert": "Hi,MTPush !",
"title": "web_push",
"url": "http://www.google.com",
"extras": {
"web-key1": "web-value1"
}
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
}
]
}'
curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/alias \
-H "Content-Type: application/json" \
-u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
-d '{
"requests": [
{
"target": "user_alias_1",
"platform": "web",
"notification": {
"alert": "Hi,Push !",
"web": {
"alert": "Hi,Push !",
"title": "web_push",
"url": "http://www.google.com",
"extras": {
"web-key1": "web-value1"
}
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
},
{
"target": "user_alias_2",
"platform": "web",
"notification": {
"alert": "Hi,MTPush !",
"web": {
"alert": "Hi,MTPush !",
"title": "web_push",
"url": "http://www.google.com",
"extras": {
"web-key1": "web-value1"
}
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
}
]
}'
โค้ดนี้โชว์เป็นหน้าต่างลอย
พารามิเตอร์คำขอ
โครงสร้างเนื้อหาคำขอ:
{
"requests": [
{
"target": "string", // จำเป็น, เป้าหมายการส่ง (registration_id หรือ alias)
"platform": "string", // จำเป็น, การตั้งค่าแพลตฟอร์มการส่ง (อ้างอิง Push API)
"notification": "object", // ไม่จำเป็น, เนื้อหาการแจ้งเตือน (อ้างอิง Push API)
"message": "object", // ไม่จำเป็น, ข้อความกำหนดเอง (อ้างอิง Push API), ไม่สามารถใช้ร่วมกับ notification
"options": "object", // ไม่จำเป็น, ตัวเลือกการส่ง (อ้างอิง Push API)
"custom_args": "object" // ไม่จำเป็น, พารามิเตอร์ที่ส่งไปยังไคลเอนต์
}
]
}
{
"requests": [
{
"target": "string", // จำเป็น, เป้าหมายการส่ง (registration_id หรือ alias)
"platform": "string", // จำเป็น, การตั้งค่าแพลตฟอร์มการส่ง (อ้างอิง Push API)
"notification": "object", // ไม่จำเป็น, เนื้อหาการแจ้งเตือน (อ้างอิง Push API)
"message": "object", // ไม่จำเป็น, ข้อความกำหนดเอง (อ้างอิง Push API), ไม่สามารถใช้ร่วมกับ notification
"options": "object", // ไม่จำเป็น, ตัวเลือกการส่ง (อ้างอิง Push API)
"custom_args": "object" // ไม่จำเป็น, พารามิเตอร์ที่ส่งไปยังไคลเอนต์
}
]
}
โค้ดนี้โชว์เป็นหน้าต่างลอย
คำอธิบายพารามิเตอร์:
ฟิลด์ | จำเป็น | ประเภท | คำอธิบาย |
---|---|---|---|
requests |
ใช่ | array | อาร์เรย์คำขอแบบกลุ่ม (สูงสุด 500 รายการ, target ต้องไม่ซ้ำกันในแต่ละกลุ่ม) |
target |
ใช่ | string | ค่าเป้าหมาย: - จุดปลายทาง /regid : registration_id - จุดปลายทาง /alias : alias |
platform |
ใช่ | string | แพลตฟอร์มการส่ง: android , ios หรือ all |
notification |
ไม่ | object | เนื้อหาการแจ้งเตือน (โครงสร้างเดียวกับ Push API) |
message |
ไม่ | object | ข้อความกำหนดเอง (โครงสร้างเดียวกับ 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 | ไม่มีสิทธิ์การส่ง push สำหรับแอปพลิเคชัน | ตรวจสอบการกำหนดค่าแอปพลิเคชัน | 400 |
21043 | ไม่มีสิทธิ์การส่ง push (รอการชำระเงิน) | แก้ไขปัญหาการเรียกเก็บเงิน | 400 |
23009 | IP ไม่อยู่ในรายการอนุญาต | เพิ่ม IP เซิร์ฟเวอร์ในรายการอนุญาต | 400 |
21009 | ข้อผิดพลาดระบบภายใน (ไม่ต้องลองใหม่) | ติดต่อฝ่ายสนับสนุนทางเทคนิค | 400 |
ข้อผิดพลาดการจำกัดอัตราการเรียก | |||
23008 | ถึงขีดจำกัดอัตราการเรียก API | ลองใหม่สำหรับรายการที่ล้มเหลวหากสำเร็จบางส่วน | 400 |
ข้อผิดพลาดพารามิเตอร์ | |||
21003 | ค่าพารามิเตอร์ไม่ถูกต้อง | ตรวจสอบรูปแบบเนื้อหาคำขอ | 400 |
21015 | พารามิเตอร์คำขอไม่ถูกต้อง | ตรวจสอบฟิลด์ที่จำเป็น | 400 |
21016 | การตรวจสอบพารามิเตอร์ล้มเหลว | ตรวจสอบประเภทฟิลด์และช่วงค่า | 400 |
รหัสข้อผิดพลาดทั้งหมด: https://www.engagelab.com/zh_CN/docs/app-push/developer-guide/rest-api/push-plan-api
หมายเหตุ
- การจัดการการจำกัดอัตราการเรียก: คืนผลลัพธ์บางส่วนเมื่อเกิดการจำกัดอัตราการเรียก (
msg_id
สำหรับรายการที่สำเร็จ +error
สำหรับรายการที่ล้มเหลว) - การตรวจสอบซ้ำซ้อน: ค่า
target
หรือcid
ทั้งหมดต้องไม่ซ้ำกันภายในกลุ่มเดียวกัน - ข้อจำกัดปริมาณ: สูงสุด 500 เป้าหมายต่อคำขอ
- การจัดการข้อผิดพลาด: ข้อผิดพลาดระดับโลก (เช่น การรับรองความถูกต้องล้มเหลว) จะหยุดการทำงานทันทีโดยไม่มีผลลัพธ์บางส่วน