ข้ามไปยังเนื้อหาหลัก
เวอร์ชัน: ล่าสุด

Pagination

นำทางผ่านชุดผลลัพธ์ขนาดใหญ่อย่างมีประสิทธิภาพด้วย Omise API pagination เรียนรู้วิธีใช้พารามิเตอร์ limit และ offset เพื่อดึงข้อมูลเป็นส่วนที่จัดการได้

ภาพรวม​

endpoints ของ Omise API หลายตัวส่งคืนรายการทรัพยากร (charges, customers, transfers ฯลฯ) เพื่อให้ responses รวดเร็วและจัดการได้ endpoints เหล่านี้จะส่งคืนผลลัพธ์แบบแบ่งหน้า คุณสามารถควบคุมจำนวนรายการที่จะดึงต่อ request และหน้าที่จะดึง

เริ่มต้นอย่างรวดเร็ว
  • ใช้ limit เพื่อควบคุมจำนวนรายการต่อหน้า (ค่าเริ่มต้น: 20, สูงสุด: 100)
  • ใช้ offset เพื่อข้ามรายการและนำทางไปยังหน้า
  • ตรวจสอบ total เพื่อดูจำนวนรายการทั้งหมดที่มีอยู่
  • list responses ทั้งหมดใช้โครงสร้างเดียวกัน

พารามิเตอร์ Pagination​

limit​

ประเภท: integer ค่าเริ่มต้น: 20 ช่วง: 1-100 วัตถุประสงค์: จำนวนรายการที่ส่งคืนต่อ request

# ดึง 50 charges ต่อ request
curl https://api.omise.co/charges?limit=50 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

offset​

ประเภท: integer ค่าเริ่มต้น: 0 วัตถุประสงค์: จำนวนรายการที่ข้ามก่อนส่งคืนผลลัพธ์

# ข้าม 20 charges แรกและส่งคืน 20 ถัดไป
curl https://api.omise.co/charges?offset=20&limit=20 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

from​

ประเภท: ISO 8601 datetime ค่าเริ่มต้น: 1970-01-01T00:00:00Z วัตถุประสงค์: วันที่และเวลา UTC ที่จำกัดจุดเริ่มต้นของระเบียนที่ส่งคืน

# ดึง charges ที่สร้างหลังจากวันที่ 1 มกราคม 2025
curl "https://api.omise.co/charges?from=2025-01-01T00:00:00Z" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

to​

ประเภท: ISO 8601 datetime ค่าเริ่มต้น: เวลา UTC ปัจจุบัน วัตถุประสงค์: วันที่และเวลา UTC ที่จำกัดจุดสิ้นสุดของระเบียนที่ส่งคืน

# ดึง charges ที่สร้างก่อนวันที่ 1 กุมภาพันธ์ 2025
curl "https://api.omise.co/charges?to=2025-02-01T00:00:00Z" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

order​

ประเภท: String ค่าเริ่มต้น: reverse_chronological ตัวเลือก: chronological, reverse_chronological วัตถุประสงค์: ลำดับการเรียงของระเบียนที่ส่งคืน

# ดึง charges ตามลำดับเวลา (เก่าที่สุดก่อน)
curl "https://api.omise.co/charges?order=chronological" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

# ดึง charges ตามลำดับเวลาย้อนกลับ (ใหม่ที่สุดก่อน, ค่าเริ่มต้น)
curl "https://api.omise.co/charges?order=reverse_chronological" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

ตัวอย่างการรวมกัน​

# ดึงรายการ 41-60 (หน้าที่ 3 ที่หน้าละ 20)
curl https://api.omise.co/charges?offset=40&limit=20 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

ตัวอย่างแบบเต็มพร้อมพารามิเตอร์ทั้งหมด​

# ดึง charges จากเดือนมกราคม 2025 เก่าที่สุดก่อน หน้าที่ 2
curl "https://api.omise.co/charges?from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&order=chronological&limit=20&offset=20" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

รูปแบบ List Response​

endpoints ที่ใช้ pagination ทั้งหมดส่งคืนโครงสร้าง list ที่สอดคล้องกัน:

{
  "object": "list",
  "data": [
    {
      "object": "charge",
      "id": "chrg_test_5xuy4w91xqz7d1w9u0t",
      "amount": 100000,
      ...
    },
    {
      "object": "charge",
      "id": "chrg_test_5xuy4w91xqz7d1w9u0a",
      "amount": 50000,
      ...
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 142,
  "from": "2025-01-01T00:00:00Z",
  "to": "2025-02-07T23:59:59Z",
  "order": "chronological",
  "location": "/charges"
}

ฟิลด์ List Object​

ฟิลด์ประเภทคำอธิบาย
objectstringค่า "list" เสมอสำหรับ pagination responses
dataarrayอาร์เรย์ของ resource objects (charges, customers ฯลฯ)
limitintegerจำนวนรายการต่อหน้า (จาก request)
offsetintegerจำนวนรายการที่ข้าม (จาก request)
totalintegerจำนวนรายการทั้งหมดในทุกหน้า
fromstring (ISO 8601)วันที่เริ่มต้นของช่วง query (ไม่บังคับ)
tostring (ISO 8601)วันที่สิ้นสุดของช่วง query (ไม่บังคับ)
orderstringลำดับการเรียง: "chronological" หรือ "reverse_chronological"
locationstringเส้นทาง API endpoint

Endpoints ที่รองรับ Pagination​

endpoints ต่อไปนี้รองรับ pagination:

ทรัพยากรหลัก​

Endpointลำดับเริ่มต้นคำอธิบาย
GET /chargesย้อนกลับตามเวลาแสดงรายการ charges ทั้งหมด
GET /customersย้อนกลับตามเวลาแสดงรายการ customers ทั้งหมด
GET /transfersย้อนกลับตามเวลาแสดงรายการ transfers ทั้งหมด
GET /refundsย้อนกลับตามเวลาแสดงรายการ refunds ทั้งหมด
GET /transactionsย้อนกลับตามเวลาแสดงรายการ transactions ทั้งหมด
GET /disputesย้อนกลับตามเวลาแสดงรายการ disputes ทั้งหมด
GET /recipientsย้อนกลับตามเวลาแสดงรายการ recipients ทั้งหมด
GET /eventsย้อนกลับตามเวลาแสดงรายการ events ทั้งหมด
GET /schedulesย้อนกลับตามเวลาแสดงรายการ schedules ทั้งหมด
GET /linksย้อนกลับตามเวลาแสดงรายการ payment links ทั้งหมด

ทรัพยากรที่ซ้อนอยู่​

Endpointคำอธิบาย
GET /customers/:id/cardsแสดงรายการบัตรของลูกค้า
GET /charges/:id/refundsแสดงรายการ refunds ของ charge
GET /customers/:id/chargesแสดงรายการ charges ของลูกค้า

ตัวอย่าง Pagination พื้นฐาน​

Pagination เริ่มต้น​

ดึง 20 รายการแรก (พฤติกรรมเริ่มต้น):

curl https://api.omise.co/charges \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

Response:

{
  "object": "list",
  "data": [...],
  "limit": 20,
  "offset": 0,
  "total": 142
}

ขนาดหน้าที่กำหนดเอง​

ดึง 50 รายการต่อหน้า:

curl https://api.omise.co/charges?limit=50 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

นำทางไปหน้าที่ 2​

ข้าม 20 รายการแรกและดึง 20 รายการถัดไป:

curl https://api.omise.co/charges?offset=20&limit=20 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

ดึงจำนวนรายการสูงสุด​

ดึง 100 รายการ (สูงสุดที่อนุญาต):

curl https://api.omise.co/charges?limit=100 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

แนวทางปฏิบัติที่ดีที่สุด​

1. ใช้ขนาดหน้าที่เหมาะสม​

// ✅ ดี - เลือกขนาดตาม use case

// สำหรับแสดงใน UI (ไม่ให้มากเกินไปสำหรับผู้ใช้)
const charges = await omise.charges.list({ limit: 20 });

// สำหรับการประมวลผลเป็นชุด (เพิ่มประสิทธิภาพสูงสุด)
const chargesForExport = await omise.charges.list({ limit: 100 });

// สำหรับการอัปเดตแบบ real-time (ลด latency ให้น้อยที่สุด)
const recentCharges = await omise.charges.list({ limit: 10 });

2. จัดการข้อผิดพลาด Pagination​

# ✅ ดี - จัดการข้อผิดพลาด pagination
import omise

def safe_list_charges(offset=0, limit=20, max_retries=3):
    for attempt in range(max_retries):
        try:
            return omise.Charge.list(offset=offset, limit=limit)

        except omise.errors.BaseError as e:
            if attempt == max_retries - 1:
                raise

            if e.http_status >= 500:
                # Server error - retry
                time.sleep(2 ** attempt)
                continue
            else:
                # Client error - อย่า retry
                raise

charges = safe_list_charges(offset=0, limit=50)

3. คำนวณหมายเลขหน้าอย่างถูกต้อง​

// ✅ ดี - การคำนวณหน้าที่แม่นยำ

function calculatePageInfo(offset, limit, total) {
  const currentPage = Math.floor(offset / limit) + 1;
  const totalPages = Math.ceil(total / limit);
  const itemsOnPage = Math.min(limit, total - offset);

  return {
    currentPage,
    totalPages,
    itemsOnPage,
    firstItemNum: offset + 1,
    lastItemNum: offset + itemsOnPage,
    hasNextPage: offset + limit < total,
    hasPrevPage: offset > 0
  };
}

// ตัวอย่าง
const info = calculatePageInfo(40, 20, 142);
console.log(info);
// {
//   currentPage: 3,
//   totalPages: 8,
//   itemsOnPage: 20,
//   firstItemNum: 41,
//   lastItemNum: 60,
//   hasNextPage: true,
//   hasPrevPage: true
// }

อ้างอิงด่วน​

พารามิเตอร์ Pagination​

พารามิเตอร์ประเภทค่าเริ่มต้นช่วงคำอธิบาย
limitinteger201-100รายการต่อหน้า
offsetinteger00-∞รายการที่ข้าม

ฟิลด์ List Response​

{
  "object": "list",
  "data": [...],       // อาร์เรย์ของรายการ
  "limit": 20,         // รายการต่อหน้า
  "offset": 0,         // รายการที่ข้าม
  "total": 142,        // รายการทั้งหมด
  "from": "...",       // วันที่เริ่มต้น (ไม่บังคับ)
  "to": "...",         // วันที่สิ้นสุด (ไม่บังคับ)
  "order": "...",      // ลำดับการเรียง
  "location": "..."    // เส้นทาง endpoint
}

การคำนวณหน้า​

// หมายเลขหน้าปัจจุบัน
const currentPage = Math.floor(offset / limit) + 1;

// จำนวนหน้าทั้งหมด
const totalPages = Math.ceil(total / limit);

// มีหน้าถัดไปหรือไม่
const hasNextPage = offset + limit < total;

// มีหน้าก่อนหน้าหรือไม่
const hasPrevPage = offset > 0;

// offset สำหรับหน้าถัดไป
const nextOffset = offset + limit;

// offset สำหรับหน้าก่อนหน้า
const prevOffset = Math.max(0, offset - limit);

ทรัพยากรที่เกี่ยวข้อง​

ถัดไป: เรียนรู้วิธีลอง requests ซ้ำได้อย่างปลอดภัยโดยไม่มีการดำเนินการซ้ำซ้อนใน Idempotency

FAQ​

จำนวนรายการสูงสุดที่สามารถดึงได้ต่อคำขอคือเท่าใด?

ค่า limit สูงสุดคือ 100 รายการต่อคำขอ หากคุณต้องการรายการเพิ่มเติม ให้ใช้การแบ่งหน้าด้วยคำขอหลายครั้งโดยปรับพารามิเตอร์ offset

จำนวนรวมมีการเปลี่ยนแปลงระหว่างคำขอหรือไม่?

ใช่ จำนวน total สะท้อนสถานะปัจจุบันของข้อมูลของคุณ หากมีการสร้างหรือลบรายการใหม่ระหว่างคำขอ จำนวนรวมจะเปลี่ยนแปลง ควรตรวจสอบจำนวนรวมในการตอบกลับแต่ละครั้งเพื่อการแบ่งหน้าที่ถูกต้อง

สามารถเรียงลำดับผลลัพธ์จากเก่าไปใหม่ได้หรือไม่?

ได้ ใช้พารามิเตอร์ order ตั้งค่า order=chronological เพื่อให้ได้ผลลัพธ์จากเก่าที่สุดไปใหม่ที่สุด หรือ order=reverse_chronological (ค่าเริ่มต้น) สำหรับใหม่ที่สุดไปเก่าที่สุด

จะส่งออกข้อมูลทั้งหมดอย่างมีประสิทธิภาพได้อย่างไร?

ใช้ค่า limit สูงสุด 100 และวนซ้ำผ่านหน้าต่างๆ เพิ่มความล่าช้าเล็กน้อยระหว่างคำขอเพื่อเคารพขีดจำกัดอัตราการเรียกใช้ สำหรับชุดข้อมูลขนาดใหญ่มาก ให้พิจารณาสตรีมผลลัพธ์ไปยังไฟล์แทนที่จะโหลดทุกอย่างเข้าหน่วยความจำ

มีวิธีดึงผลลัพธ์หลังจาก ID เฉพาะแทนการใช้ offset หรือไม่?

Omise ใช้การแบ่งหน้าแบบ offset ไม่มีการแบ่งหน้าแบบ cursor หรือแบบ ID ใช้ offset ร่วมกับ limit เพื่อนำทางผ่านผลลัพธ์

จะเกิดอะไรขึ้นถ้าร้องขอ offset ที่มากกว่าจำนวนรวม?

API จะส่งคืนอาร์เรย์ data ว่างเปล่าพร้อมกับจำนวน total ที่ถูกต้อง นี่ไม่ใช่ข้อผิดพลาด เพียงแค่บ่งชี้ว่าไม่มีรายการเพิ่มเติมให้ดึงที่ offset นั้น