REST API กลุ่มผู้ใช้

สร้างกลุ่มแบบรายการที่อัปเดตด้วยตนเอง และเขียนทับ เพิ่ม หรือลบสมาชิกตาม ID กลุ่ม

ทั่วไป

• คำขอและการตอบกลับใช้ JSON ที่เข้ารหัส UTF-8
• URL endpoint เต็มคือ Base URL ของศูนย์ข้อมูลบวก path ของ API ดู ภาพรวม REST API สำหรับวิธีรับ Base URL และ API Key / API Secret
• ใช้ HTTP Basic Authentication: Authorization: Basic ${base64(api_key:api_secret)} แหล่งข้อมูล API ที่ผูกกับ API Key กำหนดโปรเจกต์ ผู้เรียกไม่ต้องส่ง ID โปรเจกต์ใน body คำขอ
• การตอบกลับที่สำเร็จมีโครงสร้างร่วมกัน: code 0 หมายถึงสำเร็จ message อธิบายผลลัพธ์ และ data เป็น payload การจัดการ batch สำหรับการเขียนสมาชิกขึ้นกับการดำเนินการ: OVERRIDE ทำงานหลังจากได้รับ batch ทั้งหมด แต่ละ batch ของ APPEND และ REMOVE ใช้แยกกัน data.status และ data.complete ในการตอบกลับบอกสถานะการประมวลผล

สร้างกลุ่มแบบรายการ

สร้างกลุ่มที่มีโหมดอัปเดตแบบ manual และอัปโหลดรายการเป็นวิธีสร้าง หลังสร้างกลุ่มจะไม่มีสมาชิก ใช้ อัปเดตสมาชิกกลุ่ม เพื่ออัปโหลดรายการ

Endpoint

POST /v1/segments

ตัวอย่างคำขอ

              
              curl -X POST 'https://ma-api.engagelab.com/v1/segments' \
  -H 'Authorization: Basic {base64(api_key:api_secret)}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "High-value users",
    "description": "High-value user list synced from the order system"
  }'

            

พารามิเตอร์คำขอ

ตัวอย่างการตอบกลับ

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "segmentId": 123456789,
    "name": "High-value users",
    "generation": "generation-1"
  }
}

            

อัปเดตสมาชิกกลุ่ม

endpoint เดียวเขียนทับ เพิ่ม หรือลบสมาชิกในรายการ รับเฉพาะกลุ่มในโปรเจกต์ปัจจุบันที่สร้างด้วยการอัปโหลดรายการ ใช้การอัปเดต manual และอยู่ในสถานะ active ตัวระบุผู้ใช้ต้องตรงกับผู้ใช้ active ที่มีอยู่ในโปรเจกต์ API ไม่สร้าง asset ผู้ใช้ เมื่อกลุ่มไม่เข้าเงื่อนไข จะคืน error 55210–55214 (ดู การตอบกลับ error)

Endpoint

POST /v1/segments/{segmentId}/members

ตัวอย่างคำขอ

ตัวอย่างต่อไปนี้แบ่งการดำเนินการ OVERRIDE หนึ่งครั้งเป็นสอง batch แต่ละ batchId แทนการดำเนินการรายการหนึ่งครั้ง batch ทั้งหมดต้องใช้ batchId operation และ batchCount เดียวกัน OVERRIDE ใช้การเปลี่ยนรายการหลังจากได้รับ batch ทั้งหมด APPEND และ REMOVE มีผลทันทีที่คำขอ batch สำเร็จ

              
              curl -X POST 'https://ma-api.engagelab.com/v1/segments/123456789/members' \
  -H 'Authorization: Basic {base64(api_key:api_secret)}' \
  -H 'Content-Type: application/json' \
  -d '{
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "batchIndex": 0,
    "batchCount": 2,
    "members": [
      {"euid": "100001"},
      {"identityName": "user_id", "identityValue": "user-002"}
    ]
  }'

            

เมื่อได้รับ batch OVERRIDE แรก status ในการตอบกลับคือ RECEIVING และ complete เป็น false ส่ง batch ที่เหลือด้วย batchId เดียวกัน และตั้ง batchIndex เป็น 1

พารามิเตอร์คำขอ

องค์ประกอบ members รองรับสองรูปแบบต่อไปนี้ ไม่ส่ง euid พร้อม identityName / identityValue:

การดำเนินการรายการ

การลองใหม่ด้วย batchId เดียวกันต้องใช้ operation batchCount และเนื้อหา batch เดียวกัน batchId และ batchIndex เดียวกันไม่ส่งเนื้อหาต่างกัน เก็บผล idempotent 24 ชั่วโมง

batch OVERRIDE ถูกเก็บจนได้รับครบแล้วจึงใช้ ข้อมูลที่เก็บหมดอายุหลัง TTL 24 ชั่วโมง และรายการไม่เปลี่ยนหาก batch ไม่ครบก่อนหมดอายุ แต่ละ batch APPEND และ REMOVE ใช้แยกกัน batchCount และ batchIndex ยังระบุ batch รองรับ idempotency และติดตามความคืบหน้าโดยไม่บล็อก batch ปัจจุบัน

การเปลี่ยนรายการที่สำเร็จแต่ละครั้งบันทึกในประวัติอัปเดตกลุ่ม แหล่งที่มา REST API OVERRIDE บันทึกต่อ batch ที่เสร็จ APPEND และ REMOVE ต่อ batch ที่สำเร็จ บันทึก audit ไม่รวมตัวอย่างตัวระบุที่ไม่ match หรือไม่ valid

ตัวอย่างการตอบกลับ

batch ยังไม่ครบ:

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "status": "RECEIVING",
    "complete": false,
    "expectedBatchCount": 2,
    "receivedBatchCount": 1,
    "inputCount": 2,
    "matchedCount": 2,
    "unmatchedCount": 0,
    "unmatchedSamples": [],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 0,
    "invalidSamples": [],
    "invalidSamplesTruncated": false,
    "enterCount": 0,
    "exitCount": 0
  }
}

            

batch OVERRIDE เสร็จสมบูรณ์:

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-001",
    "operation": "OVERRIDE",
    "status": "COMPLETED",
    "complete": true,
    "expectedBatchCount": 2,
    "receivedBatchCount": 2,
    "inputCount": 3,
    "matchedCount": 2,
    "unmatchedCount": 1,
    "unmatchedSamples": [
      {"identityName": "user_id", "identityValue": "user-not-found"}
    ],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 1,
    "invalidSamples": [
      {"identityName": "not_configured", "identityValue": "example"}
    ],
    "invalidSamplesTruncated": false,
    "enterCount": 2,
    "exitCount": 1
  }
}

            

เมื่อ batch APPEND หรือ REMOVE สำเร็จ batch ปัจจุบันใช้ทันทีและคืน complete: true แม้ batchCount มากกว่าจำนวน batch ที่ได้รับจนถึงตอนนี้ ตัวอย่างเช่น batchCount เป็น 2 และได้รับแค่ batch แรก receivedBatchCount เป็น 1 และ status เป็น COMPLETED

              
              {
  "code": 0,
  "message": "success",
  "data": {
    "batchId": "crm-sync-20260915-append",
    "operation": "APPEND",
    "status": "COMPLETED",
    "complete": true,
    "expectedBatchCount": 2,
    "receivedBatchCount": 1,
    "inputCount": 2,
    "matchedCount": 1,
    "unmatchedCount": 1,
    "unmatchedSamples": [
      {"identityName": "user_id", "identityValue": "user-not-found"}
    ],
    "unmatchedSamplesTruncated": false,
    "invalidCount": 0,
    "invalidSamples": [],
    "invalidSamplesTruncated": false,
    "enterCount": 1,
    "exitCount": 0
  }
}

            

ตัวอย่างใช้โครงสร้าง object ตัวระบุสมาชิกจากคำขอ และอาจรวม identityValue ที่ส่ง เซิร์ฟเวอร์เก็บตัวอย่างเฉพาะใน cache idempotency 24 ชั่วโมง ไม่ใส่ในบันทึก audit จัดการการตอบกลับและ log ตามข้อกำหนด compliance ข้อมูลของคุณ

หากการตอบกลับเป็น PROCESSING ลองใหม่ด้วย batchId batchIndex และเนื้อหา batch เดิมเพื่อผล idempotent ไม่มี API แยกสำหรับสอบถามความคืบหน้า batch

การตอบกลับ error

error ใช้ code และ message ดู รหัสสถานะ HTTP สำหรับรหัสสถานะ HTTP และรหัส return ทั่วไป

เมื่อสร้างกลุ่ม รหัส error ทางธุรกิจและ message จาก Metadata ส่งต่อให้ผู้เรียก เช่น ชื่อซ้ำ 40026 ถึงขีดจำกัด 40032 ใน path อัปโหลดรายการ «ไม่มีกลุ่ม» คืน 55201 แทน 40027

ตัวระบุสมาชิกที่ไม่ match หรือไม่ valid ไม่ทำให้การดำเนินการรายการทั้งหมดล้มเหลว (ยกเว้น OVERRIDE เมื่อไม่มีผู้ใช้ match ดู 55214) การตอบกลับคืนจำนวนและตัวอย่างตัวระบุสูงสุด 100 รายการ ตัวอย่างอาจมี identityValue ปกป้องข้อมูลการตอบกลับตามความเหมาะสม