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

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_...'
});

// メタデータの注文IDで課金を検索
const results = await omise.search.list({
  scope: 'charge',
  query: 'order_id:ORD-12345',
  limit: 10
});

console.log(`${results.total}件の課金が見つかりました`);
results.data.forEach(charge => {
  console.log(`課金: ${charge.id}, 金額: ${charge.amount}`);
});

顧客のすべての課金を検索​

import omise

omise.api_secret = 'skey_test_...'

# 顧客メールで検索
results = omise.Search.execute(
    scope='charge',
    query='customer@example.com',
    limit=50
)

print(f'{results["total"]}件の課金が見つかりました')
for charge in results['data']:
    print(f'課金 {charge["id"]}: {charge["amount"]} {charge["currency"]}')

日付フィルター付き検索​

# "subscription"を含む2月の課金を検索
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
}

ページネーション​

検索結果はページネーションされます:

# 最初のページ
GET /search?query=order&limit=20&page=1

# 2ページ目
GET /search?query=order&limit=20&page=2

総ページ数を計算:

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

ベストプラクティス​

推奨事項​

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

非推奨事項​

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

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

メタデータをインデックス化​

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

// 良い - 検索可能な構造
metadata: {
  order_id: 'ORD-12345',
  customer_email: 'john@example.com',
  product_sku: 'TSHIRT-BLUE-L'
}

// 効率が悪い - ネストされた構造は検索しにくい
metadata: {
  order: {
    id: '12345',
    customer: { email: 'john@example.com' }
  }
}

適切な制限を使用​

// UI表示用
const results = await omise.search.list({
  query: 'keyword',
  limit: 20  // 初期表示に適切
});

// エクスポート用
const results = await omise.search.list({
  query: 'keyword',
  limit: 100  // 大量エクスポートのためのAPI呼び出し削減
});

よくある質問​

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

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

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

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

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

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

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

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

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

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

関連リソース​

関連項目​

お困りですか？ support@omise.coまでお問い合わせください