メインコンテンツへスキップ
バージョン: 最新版

Search API

概要​

Search APIは、全文検索機能を使用してすべてのOmiseリソースを検索する強力な方法を提供します。キーワード、メタデータ、または特定のフィールドを使用して、チャージ、顧客、紛争、受取人などを検索します。

利用可能なエンドポイント​

できること​

  • 全文検索 - すべてのリソース全体でキーワードで検索
  • スコープベースの検索 - 特定のリソースタイプに検索を制限
  • メタデータ検索 - カスタムメタデータ値でリソースを検索
  • カード検索 - カードの末尾4桁でチャージを検索
  • 顧客検索 - メール、名前、または説明で検索
  • 日付フィルタリング - 検索を日付範囲と組み合わせる
  • ページネーション - 大きな結果セットをナビゲート

検索可能なリソース​

チャージ​

以下でチャージを検索:

  • 説明
  • メタデータ値
  • カードの末尾4桁
  • 顧客メール
  • 参照番号
  • 失敗メッセージ

顧客​

以下で顧客を検索:

  • メールアドレス
  • 説明
  • メタデータ値
  • 名前(カードから)

紛争​

以下で紛争を検索:

  • チャージの説明
  • 理由コード
  • メタデータ
  • 顧客情報

受取人​

以下で受取人を検索:

  • 名前
  • メール
  • 銀行口座名
  • 説明
  • メタデータ

返金​

以下で返金を検索:

  • 関連するチャージの説明
  • メタデータ値

検索スコープ​

検索するリソースタイプを指定します:

  • charge - チャージのみを検索
  • customer - 顧客のみを検索
  • dispute - 紛争のみを検索
  • recipient - 受取人のみを検索
  • refund - 返金のみを検索
  • transfer - 送金のみを検索

ユースケース​

説明でチャージを検索​

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

メールで顧客を検索​

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

カードの末尾4桁でチャージを検索​

GET /search?scope=charge&query=4242

メタデータを検索​

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

マルチリソース検索​

GET /search?query=john@example.com
# メールに一致するすべてのリソースを返します

使用例​

特定の注文を検索​

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

// Search charges by order ID in metadata
const results = await omise.search.list({
  scope: 'charge',
  query: 'order_id:ORD-12345',
  limit: 10
});

console.log(`Found ${results.total} charges`);
results.data.forEach(charge => {
  console.log(`Charge: ${charge.id}, Amount: ${charge.amount}`);
});

顧客のすべてのチャージを検索​

import omise

omise.api_secret = 'skey_test_...'

# Search by customer email
results = omise.Search.execute(
    scope='charge',
    query='customer@example.com',
    limit=50
)

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

日付フィルターを使用した検索​

# Find charges in February containing "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:

検索クエリ構文​

基本検索​

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"

完全一致フレーズを検索します。

レスポンス形式​

{
  "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
}

ページネーション​

検索結果はページ分割されます:

# First page
GET /search?query=order&limit=20&page=1

# Second page
GET /search?query=order&limit=20&page=2

合計ページ数を計算:

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

ベストプラクティス​

✅ 推奨事項​

  • 特定のスコープを使用 - パフォーマンス向上のために単一のリソースタイプを検索
  • 日付フィルターを追加 - from/toパラメータで結果を絞り込む
  • メタデータ検索を使用 - メタデータで検索可能なデータを構造化
  • ページネーションを実装 - 管理可能なチャンクで結果を処理
  • 検索結果をキャッシュ - 短期間(1〜5分)キャッシュ
  • クエリをサニタイズ - ユーザー入力を検証してエスケープ

❌ 避けるべきこと​

  • スコープなしで検索しない - 可能な限り常にスコープを指定
  • リアルタイムルックアップに使用しない - 既知のIDには直接GETリクエストを使用
  • ページネーションをスキップしない - 常にページ分割された結果を処理
  • 検索に過度に依存しない - 検索は検索用、定期的な取得には使用しない
  • 広範囲に検索しすぎない - フィルターを使用して結果を絞り込む

パフォーマンスのヒント​

メタデータにインデックスを付ける​

効率的な検索のためにメタデータを構造化します:

// Good - searchable structure
metadata: {
  order_id: 'ORD-12345',
  customer_email: 'john@example.com',
  product_sku: 'TSHIRT-BLUE-L'
}

// Less efficient - nested structures harder to search
metadata: {
  order: {
    id: '12345',
    customer: { email: 'john@example.com' }
  }
}

適切な制限を使用​

// For UI display
const results = await omise.search.list({
  query: 'keyword',
  limit: 20  // Good for initial display
});

// For exports
const results = await omise.search.list({
  query: 'keyword',
  limit: 100  // Fewer API calls for large exports
});

よくある質問​

どのフィールドが検索可能ですか？​

説明、メタデータ値、メールアドレス、カードの末尾4桁、参照番号を含むすべてのテキストフィールド。

検索は大文字と小文字を区別しますか？​

いいえ、検索は大文字と小文字を区別しません。

結果はどのようにランク付けされますか？​

結果は関連性でランク付けされ、完全一致が高くランク付けされます。

ワイルドカードを使用できますか？​

いいえ、ワイルドカード検索はサポートされていません。代わりに部分キーワードを使用してください。

検索インデックスはどのくらい最新ですか？​

検索インデックスは、リソースの作成/更新から1〜2秒以内に更新されます。

関連リソース​

関連情報​

サポートが必要ですか？ support@omise.coまでお問い合わせください