Reactor API での応答のフィルタリング

Reactor API でリスト(GET)エンドポイントを使用する場合、返される結果をレコードのサブセットに制限する必要が生じる場合があります。これを実現するために、API のリストエンドポイントの多くは、特定の属性でフィルタリングする機能をサポートしています。代わりに API に対して構造化されたクエリを作成する場合は、検索に関するガイドを参照してください。

フィルタリング構文

次の例では、GET リクエストにフィルターを実装する方法を説明します。

API 形式

特定のリストエンドポイントの応答をフィルタリングするには、リクエストパスに filter クエリパラメーターを指定する必要があります。

メモ

以下のテンプレートでは、読みやすくするために角括弧([])とスペース文字を使用しています。実際には、RFC 3986 で説明されているように、これらの文字を URI エンコードする必要があります。適切にエンコードされたリクエストパスの例をこのガイドで後述します。

フィルターの構造が正しくない場合、フィルターは適用されず、結果セット全体が返されます。

GET {ENDPOINT}?filter[{ATTRIBUTE_NAME}]={OPERATOR} {VALUE}
プロパティ 説明
{ENDPOINT} フィルターパラメーターをサポートする Reactor API のリストエンドポイント。
{ATTRIBUTE_NAME} 結果をフィルタリングする特定の属性の名前。エンドポイントによってフィルタリングの属性が異なることに注意してください。使用可能なフィルタリング属性のリストについては、使用しているエンドポイントのリファレンスガイドを参照してください。
{OPERATOR} 指定された {VALUE} に対する結果の評価方法を決定する演算子。サポートされる演算子は、付録の節にリストされています。
{VALUE} 返された結果を比較する値。EQ 演算子を使用して等しいかどうかを比較する場合、応答に含めるには、値が大文字と小文字を区別して完全に一致する必要があります。

リクエスト

次のリクエスト例では、ライブラリの state 属性が published と等しいことを要求するフィルターを適用して、公開済みライブラリのリストを取得します。

URI エンコードをおこなう前は、リクエストパスでのこのフィルターの構文は次のようになります。

https://reactor.adobe.io/properties/PR906238a59bbf4262bcedba248f483600/libraries?filter[state]=EQ published

パスパラメーターとクエリパラメーターが URI エンコードされると、次のような API リクエストで使用できるようになります。

curl -X GET \
  https://reactor.adobe.io/properties/PR906238a59bbf4262bcedba248f483600/libraries?filter%5Bstate%5D=EQ%20published \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'

複数の値のフィルタリング

1 つの属性に対して複数の値でフィルタリングするには、値をコンマ区切りリストとして指定します。

GET {ENDPOINT}?filter[{ATTRIBUTE_NAME}]={OPERATOR} {VALUE_1},{VALUE_2}

複数のフィルターの使用

複数の属性に対してフィルターを適用するには、各属性に filter パラメーターを指定します。パラメーターはアンパサンド(&)文字で区切る必要があります。

GET {ENDPOINT}?filter[{ATTRIBUTE_NAME_1}]={OPERATOR} {VALUE}&filter[{ATTRIBUTE_NAME_2}]={OPERATOR} {VALUE}
メモ

同じリクエストに対して複数のフィルターで同じ属性を指定した場合、その属性に対して最後に指定したフィルターのみが適用されます。

付録

次の節では、Reactor API でフィルターを使用するための追加情報を提供します。

サポートされるフィルター演算子

次の表に、フィルターパラメーターでサポートされている演算子の値を示します。フィルタリングする属性によっては、文字列属性に「より小さい」演算子または「より大きい」演算子を使用するなど、使用可能なすべてのフィルター演算子が適用できるわけではないことに注意してください。

演算子 説明
EQ 属性は指定された値と等しい必要があります。
NOT 属性が指定した値と等しくない必要があります。
LT 属性は指定した値より小さい値にする必要があります。
GT 属性は指定された値より大きい値にする必要があります。
BETWEEN 属性は、指定した値の範囲内である必要があります。この演算子を使用する場合は、2 つの値を指定して、目的の範囲の最小値と最大値を示す必要があります。
CONTAINS 属性には、文字列属性内の一連の文字など、指定された値が含まれている必要があります。

このページ