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

Search API

ภาพรวม

Search API ให้วิธีที่ทรงพลังในการค้นหาในทรัพยากร Omise ทั้งหมดของคุณโดยใช้ความสามารถในการค้นหาข้อความเต็ม ค้นหา charges, customers, disputes, recipients และอื่นๆ โดยใช้คำสำคัญ, metadata หรือฟิลด์เฉพาะ

Endpoint ที่มี

สิ่งที่คุณทำได้

  • Full-Text Search - ค้นหาด้วยคำสำคัญในทรัพยากรทั้งหมด
  • Scope-Based Search - จำกัดการค้นหาเฉพาะประเภททรัพยากร
  • Metadata Search - ค้นหาทรัพยากรด้วยค่า metadata ที่กำหนดเอง
  • Card Search - ค้นหา charges ด้วยเลข 4 ตัวท้ายของบัตร
  • Customer Search - ค้นหาด้วยอีเมล, ชื่อ หรือคำอธิบาย
  • Date Filtering - รวมการค้นหากับช่วงวันที่
  • Pagination - นำทางผ่านชุดผลลัพธ์ขนาดใหญ่

ทรัพยากรที่ค้นหาได้

Charges

ค้นหา charges ด้วย:

  • คำอธิบาย
  • ค่า metadata
  • เลข 4 ตัวท้ายของบัตร
  • อีเมลลูกค้า
  • หมายเลขอ้างอิง
  • ข้อความความล้มเหลว

Customers

ค้นหา customers ด้วย:

  • ที่อยู่อีเมล
  • คำอธิบาย
  • ค่า metadata
  • ชื่อ (จากบัตร)

Disputes

ค้นหา disputes ด้วย:

  • คำอธิบาย charge
  • รหัสเหตุผล
  • Metadata
  • ข้อมูลลูกค้า

Recipients

ค้นหา recipients ด้วย:

  • ชื่อ
  • อีเมล
  • ชื่อบัญชีธนาคาร
  • คำอธิบาย
  • Metadata

Refunds

ค้นหา refunds ด้วย:

  • คำอธิบาย charge ที่เกี่ยวข้อง
  • ค่า metadata

Search Scopes

ระบุประเภททรัพยากรที่จะค้นหา:

  • charge - ค้นหาเฉพาะ charges
  • customer - ค้นหาเฉพาะ customers
  • dispute - ค้นหาเฉพาะ disputes
  • recipient - ค้นหาเฉพาะ recipients
  • refund - ค้นหาเฉพาะ refunds
  • transfer - ค้นหาเฉพาะ transfers

กรณีการใช้งาน

ค้นหา Charges ด้วยคำอธิบาย

GET /search?scope=charge&query=order+12345

ค้นหา Customer ด้วยอีเมล

GET /search?scope=customer&query=john@example.com

ค้นหา Charges ด้วยเลข 4 ตัวท้ายของบัตร

GET /search?scope=charge&query=4242

ค้นหา Metadata

GET /search?scope=charge&query=order_id:12345

ค้นหาหลายทรัพยากร

GET /search?query=john@example.com
# ส่งคืนทรัพยากรทั้งหมดที่ตรงกับอีเมล

ตัวอย่างการใช้งาน

ค้นหาคำสั่งซื้อเฉพาะ

const omise = require('omise')({
secretKey: 'skey_test_...'
});

// ค้นหา charges ด้วย order ID ใน metadata
const results = await omise.search.list({
scope: 'charge',
query: 'order_id:ORD-12345',
limit: 10
});

console.log(`พบ ${results.total} charges`);
results.data.forEach(charge => {
console.log(`Charge: ${charge.id}, จำนวนเงิน: ${charge.amount}`);
});

ค้นหา Charges ทั้งหมดสำหรับลูกค้า

import omise

omise.api_secret = 'skey_test_...'

# ค้นหาด้วยอีเมลลูกค้า
results = omise.Search.execute(
scope='charge',
query='customer@example.com',
limit=50
)

print(f'พบ {results["total"]} charges')
for charge in results['data']:
print(f'Charge {charge["id"]}: {charge["amount"]} {charge["currency"]}')

ค้นหาพร้อมตัวกรองวันที่

# ค้นหา charges ในเดือนกุมภาพันธ์ที่มี "subscription"
curl "https://api.omise.co/search?scope=charge&query=subscription&from=2025-02-01T00:00:00Z&to=2025-02-28T23:59:59Z" \
-u skey_test_YOUR_SECRET_KEY:

ไวยากรณ์ Search Query

ค้นหาพื้นฐาน

query=keyword

ค้นหาคำสำคัญในทุกฟิลด์

ค้นหาเฉพาะฟิลด์

query=email:john@example.com
query=description:order
query=metadata.order_id:12345

หลายคำสำคัญ

query=john+doe
query=order+12345

ใช้ตรรกะ AND - ค้นหาทรัพยากรที่ตรงกับคำสำคัญทั้งหมด

วลีที่ตรงกันทุกประการ

query="Blue T-Shirt"

ค้นหาวลีที่ตรงกันทุกประการ

รูปแบบ Response

{
"object": "search",
"data": [
{
"object": "charge",
"id": "chrg_test_5xuy4w91xqz7d1w9u0t",
"amount": 100000,
"currency": "thb",
"description": "Order #12345 - Blue T-Shirt",
"metadata": {
"order_id": "12345"
},
...
}
],
"total": 1,
"from": "2025-01-01T00:00:00Z",
"to": "2025-02-07T23:59:59Z",
"limit": 20,
"page": 1
}

Pagination

ผลการค้นหาถูกแบ่งหน้า:

# หน้าแรก
GET /search?query=order&limit=20&page=1

# หน้าที่สอง
GET /search?query=order&limit=20&page=2

คำนวณจำนวนหน้าทั้งหมด:

const totalPages = Math.ceil(results.total / results.limit);

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

ควรทำ

  • ใช้ scopes เฉพาะ - ค้นหาประเภททรัพยากรเดียวเพื่อประสิทธิภาพที่ดีกว่า
  • เพิ่มตัวกรองวันที่ - จำกัดผลลัพธ์ด้วย from/to parameters
  • ใช้ metadata search - จัดโครงสร้างข้อมูลที่ค้นหาได้ใน metadata
  • ใช้งาน pagination - จัดการผลลัพธ์ในชิ้นที่จัดการได้
  • Cache ผลการค้นหา - Cache สำหรับระยะเวลาสั้น (1-5 นาที)
  • Sanitize queries - ตรวจสอบและ escape user input

ไม่ควรทำ

  • อย่าค้นหาโดยไม่มี scope - ระบุ scope เสมอเมื่อเป็นไปได้
  • อย่าใช้สำหรับ real-time lookups - ใช้ GET requests โดยตรงสำหรับ IDs ที่รู้
  • อย่าข้าม pagination - จัดการผลลัพธ์ที่แบ่งหน้าเสมอ
  • อย่าพึ่งพา search มากเกินไป - ใช้สำหรับการค้นหา ไม่ใช่การดึงข้อมูลปกติ
  • อย่าค้นหากว้างเกินไป - ใช้ตัวกรองเพื่อจำกัดผลลัพธ์

เคล็ดลับประสิทธิภาพ

Index Metadata ของคุณ

จัดโครงสร้าง metadata สำหรับการค้นหาที่มีประสิทธิภาพ:

// ดี - โครงสร้างที่ค้นหาได้
metadata: {
order_id: 'ORD-12345',
customer_email: 'john@example.com',
product_sku: 'TSHIRT-BLUE-L'
}

// ไม่ค่อยมีประสิทธิภาพ - โครงสร้างที่ซ้อนกันยากต่อการค้นหา
metadata: {
order: {
id: '12345',
customer: { email: 'john@example.com' }
}
}

ใช้ Limits ที่เหมาะสม

// สำหรับการแสดงผล UI
const results = await omise.search.list({
query: 'keyword',
limit: 20 // ดีสำหรับการแสดงผลเริ่มต้น
});

// สำหรับการ export
const results = await omise.search.list({
query: 'keyword',
limit: 100 // API calls น้อยลงสำหรับ exports ขนาดใหญ่
});

คำถามที่พบบ่อย

ฟิลด์ไหนค้นหาได้?

ฟิลด์ข้อความทั้งหมดรวมถึงคำอธิบาย, ค่า metadata, ที่อยู่อีเมล, เลข 4 ตัวท้ายของบัตร และหมายเลขอ้างอิง

การค้นหาแยกแยะตัวพิมพ์เล็กใหญ่หรือไม่?

ไม่, การค้นหาไม่แยกแยะตัวพิมพ์เล็กใหญ่

ผลลัพธ์ถูกจัดอันดับอย่างไร?

ผลลัพธ์ถูกจัดอันดับตามความเกี่ยวข้อง โดยการจับคู่ที่ตรงกันทุกประการได้รับอันดับสูงกว่า

ฉันสามารถใช้ wildcards ได้หรือไม่?

ไม่, ไม่รองรับการค้นหา wildcard ใช้คำสำคัญบางส่วนแทน

search index อัปเดตล่าสุดแค่ไหน?

Search index ถูกอัปเดตภายใน 1-2 วินาทีหลังการสร้าง/อัปเดตทรัพยากร

แหล่งข้อมูลที่เกี่ยวข้อง

ดูเพิ่มเติม


ต้องการความช่วยเหลือ? ติดต่อ support@omise.co