พุชเดี่ยวแบบกลุ่ม 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

หมายเหตุ

  1. การจัดการการจำกัดอัตราการเรียก: คืนผลลัพธ์บางส่วนเมื่อเกิดการจำกัดอัตราการเรียก (msg_id สำหรับรายการที่สำเร็จ + error สำหรับรายการที่ล้มเหลว)
  2. การตรวจสอบซ้ำซ้อน: ค่า target หรือ cid ทั้งหมดต้องไม่ซ้ำกันภายในกลุ่มเดียวกัน
  3. ข้อจำกัดปริมาณ: สูงสุด 500 เป้าหมายต่อคำขอ
  4. การจัดการข้อผิดพลาด: ข้อผิดพลาดระดับโลก (เช่น การรับรองความถูกต้องล้มเหลว) จะหยุดการทำงานทันทีโดยไม่มีผลลัพธ์บางส่วน
icon
ติดต่อฝ่ายขาย