検索
一部の上位の API リソースでは、検索 API メソッドを使用した取得がサポートされています。検索 API を使用すると、Stripe オブジェクトを柔軟に取得できます。検索は、すべてのリソースでページ分割を行うよりも迅速な方法です。検索クエリを作成するには、検索クエリ言語を確認して、リソースのクエリフィールドを参照してください。
例
Search charges API と Search PaymentIntents API で実行できることの例をいくつか紹介します。
支払いメタデータで検索
カスタムメタデータの値に一致する支払いを検索します。
支払い last4 で検索
決済に使用されたカードの末尾 4 桁に一致する支払いを検索します。
顧客のメールアドレスで検索
メールアドレスが一致する顧客を検索します。
否定語フィルター
USD 通貨以外の PaymentIntents を検索します。
数値フィルター
total
が 1000 を上回るインボイスのオブジェクトをフィルターにかけます。
複数のフィルターを組み合わせる
メタデータと通貨の組み合わせが一致する支払いを検索します。
検索クエリー言語
クエリーの構造と用語
クエリ clause
は、field
、それに続く operator
、それに続く value
で構成されています。
句 | email:"amy@rocketrides.io" |
フィールド | email |
演算子 | : |
値 | amy@rocketrides.io |
You can combine multiple query clauses in a search by either separating them with a space, or using the AND
or OR
keywords (case insensitive). You can’t combine AND
and OR
in the same query. Furthermore, there’s no option to use parentheses to give priority to certain logic operators. By default, the API combines clauses with AND
logic.
クエリ例 email:"amy@rocketrides.io" metadata["key"]:"value"
は、メールアドレスが amy@rocketrides.io で、レコードのメタデータに key
と value
という値が含まれているレコードに一致します。
除外する句のクエリーを作成する
クエリの句は -
文字を使用して否定できます。たとえば、以下の検索では、メールアドレス amy@rocketrides.io
に一致しないレコードが返されます。
-email:"amy@rocketrides.io"
フィールドタイプ、部分文字列一致、数値コンパレーター
各検索フィールドでは、:
による完全一致がサポートされます。email
や name
などの一部のフィールドでは部分文字列一致がサポートされます。amount
などの一部のフィールドでは、>
、<
などの数値コンパレーターがサポートされます。
各フィールドには、そのフィールドで使用できる操作を定義するタイプが含まれます。利用できるフィールドのリストについては、リソースごとにサポートされているクエリフィールドをご覧ください。
文字列に「より大きい」(>
) などのサポートされていない演算子を使用すると、エラーが返されます。
タイプ | 演算子 |
---|---|
トークン | 完全一致 (大文字小文字の区別なし) |
文字列 | 完全一致、部分文字列 (大文字小文字の区別なし) 文字列型の完全一致では、そのレコードにクエリのワードが同じ順序ですべて含まれているレコードが返されます。たとえば、クエリ |
数値 | 完全一致、次の値より大きい、次の値より小さい |
引用符
文字列の値は引用符で囲む必要があります。数値の場合、引用符はオプションになります。以下に例を示します。
currency:"usd"
は、引用符は必須であることを意味します。payment_method_details.card.last4:1234
は、引用符はオプションであることを意味します。
引用符内の引用符はバックスラッシュ (\
) でエスケープできます。
description:"the story called \"The Sky and the Sea.\""
メタデータ
メタデータをサポートするオブジェクトに追加したメタデータを検索できます。
メタデータ検索では、形式 metadata["<field>"]:"<value>"
を使用して句を構成します。
次の句は、寄付 ID「asdf-jkl」を含むレコードを照会する句 metadata["donation-id"]:"asdf-jkl"
の作成方法を示しています。
オブジェクト上のメタデータキーの存在に対するクエリを実行できます。次の句は、donation-id
がメタデータキーであるすべてのレコードに一致します。-metadata["donation-id"]:null
検索の構文
以下の表は、クエリーの構築に使用できる構文の一覧です。
構文 | 使用方法 | 説明 | 例 |
---|---|---|---|
: | field:value | 完全一致演算子 (大文字小文字の区別なし) | currency:"eur" では通貨が 「EUR」と完全に一致するレコードが返されます (大文字小文字は区別されません) |
AND 、and | field:value1 AND field:value2 | このクエリーでは、両方の句に一致するレコードのみが返されます (大文字と小文字は区別されません) | status:"active" AND amount:500 |
OR 、or | field:value1 OR field:value2 | このクエリーでは、句のいずれかと一致するレコードが返されます (大文字と小文字は区別されません) | currency:"usd" OR currency:"eur" |
- | -field:value | 句と一致しないレコードが返されます | -currency:"jpy" では、JPY 以外のレコードが返されます |
NULL 、null | field:null | フィールドプレゼンスのために使用される特別なトークン (大文字小文字の区別なし) | url:null では、URL フィールドが空のレコードが返されます |
\ | " \"\"" | 引用符内の引用符をエスケープ | description:"the story called \"The Sky and the Sea.\"" |
~ | field~value | サブストリング一致演算子 (サブストリングは 3 文字以上で指定してください) | email~"amy" は、amy@rocketrides.io および xamy と一致するものが返されます |
> 、< 、= |
| より大きい/より小さい演算子 | amount>"10" では、金額が 10 以上のオブジェクトが抽出されます |
リソースごとにサポートされているクエリフィールド
支払いのクエリフィールド
フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
---|---|---|
金額 | amount>1000 | 数値 |
billing_details.address.postal_code | billing_details.address.postal_code:12345 | トークン |
作成日 | created>1620310503 | 数値 |
通貨 | currency:"usd" | トークン |
顧客 | customer:"cus_123" | トークン |
disputed | disputed:"true" | トークン |
メタデータ | metadata["key"]:"value" | トークン |
payment_method_details.{{SOURCE}}.last4 | payment_method_details.card.last4:1234 | トークン |
payment_method_details.{{SOURCE}}.exp_month | payment_method_details.card_present.exp_month:12 | トークン |
payment_method_details.{{SOURCE}}.exp_year | payment_method_details.interac_present.exp_year:2022 | トークン |
payment_method_details.{{SOURCE}}.brand | payment_method_details.card.brand:"visa" | トークン |
payment_method_details.{{SOURCE}}.fingerprint | payment_method_details.card.fingerprint:"fp" | トークン |
refunded | refunded:"true" | トークン |
ステータス | status:"succeeded" | トークン |
SOURCE
の場合は、card
、card_present
、interac_present
を使用します。オンライン支払いの場合は card
を使用して、Interac ネットワークの Terminal カード提示支払いの場合は interac_present
を使用し、その他の Terminal カード提示支払いの場合は card_present
を使用します。
disputed
フィールドは、不審請求の申請の存在に関する「true」と「false」のトークンのみを受け入れます。
refunded:"true"
は、全額が返金された支払いの絞り込みに、refunded:"false"
は、一部返金された支払いの絞り込みに使用します。refunded:null
は返金が行われていない支払いの絞り込みに使用します。
顧客のクエリフィールド
フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
---|---|---|
作成日 | created>1620310503 | 数値 |
メールアドレス | email~"amyt" | 文字列 |
メタデータ | metadata["key"]:"value" | トークン |
名前 | name~"amy" | 文字列 |
電話 | phone:"+19999999999" | 文字列 |
請求書のクエリフィールド
フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
---|---|---|
作成日 | created>1620310503 | 数値 |
通貨 | currency:"usd" | トークン |
顧客 | customer:"cus_123" | トークン |
メタデータ | metadata["key"]:"value" | トークン |
番号 | number:"MYSHOP-123" | 文字列 |
receipt_number | receipt_number:"RECEIPT-123" | 文字列 |
ステータス | status:"open" | 文字列 |
サブスクリプション | subscription:"SUBS-123" | 文字列 |
合計 | total>1000 | 数値 |
Payment Intents のクエリフィールド
フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
---|---|---|
金額 | amount>1000 | 数値 |
作成日 | created>1620310503 | 数値 |
通貨 | currency:"usd" | トークン |
顧客 | customer:"cus_123" | トークン |
メタデータ | metadata["key"]:"value" | トークン |
ステータス | status:"succeeded" | トークン |
価格のクエリフィールド
フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
---|---|---|
有効 | active:"true" | トークン |
通貨 | currency:"usd" | トークン |
lookup_key | lookup_key:"standard_monthly" | 文字列 |
メタデータ | metadata["key"]:"value" | トークン |
商品 | product:"prod_123" | 文字列 |
タイプ | type:"recurring" | トークン |
商品のクエリフィールド
フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
---|---|---|
有効 | active:"true" | トークン |
説明 | description~"t-shirts" | 文字列 |
メタデータ | metadata["key"]:"value" | トークン |
名前 | name~"amy" | 文字列 |
配送可能 | shippable:"true" | トークン |
url | url~"/dinosaur_swag" | 文字列 |
サブスクリプションのクエリフィールド
フィールド | 使用状況 | タイプ (トークン、文字列、数値) |
---|---|---|
作成日 | created>1620310503 | 数値 |
メタデータ | metadata["key"]:"value" | トークン |
ステータス | status:"active" | トークン |
制限事項
最小 API バージョン
検索を使用するためにサポートされている最小の API バージョンは 2020-08-27
です。アップグレードの詳細については、Stripe の API アップグレードガイドをご覧ください。アカウントの API バージョンをアップグレードせずに検索を使用するには、Stripe-Version
リクエストヘッダーを設定して単一リクエストの API バージョンを上書きします。
-H "Stripe-Version: 2024-04-10"
ライブラリを使用する際に API バージョンを上書きする方法については、サーバー側のライブラリガイドをご覧ください。
データの鮮度
データは即時に検索可能にならないため、read-after-write (書き込み後の読み取り) フローの検索 (支払い実行直後の検索など) は使用しないでください。通常の動作条件では、データは 1 分以内に検索可能になりますが、障害が発生した場合は、新しいデータや更新されたデータが反映されるまでに時間がかかることもあります。
レート制限
Stripe では、1 秒あたり最大 20 件の読み取り操作のレート制限を適用しています。これは本番環境とテスト環境の両方のすべての検索エンドポイントに適用されます。本番環境とテスト環境の制限は別々です。このレート制限を念頭に置くと、1 つ以上の API リソースで分析を実行する必要があるワークロードでは、Sigma の方がはるかに効率的です。大量の API リソースをエクスポートする必要があるワークロードの場合は、Stripe の Data Pipeline プロダクトの方が効率的です。
地域ごとの提供状況
検索は、インドの加盟店にはお使いいただけません。