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

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