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: {ORG_ID}'
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 でのフィルターの使用方法について説明します。
次の表に、フィルターパラメーターでサポートされる演算子の値を示します。フィルターの条件となる属性に応じて、使用可能なすべてのフィルター演算子が適用されるわけではないことに注意してください(文字列属性に対する「less than」や「greater than」演算子の使用など)。
演算子 | 説明 |
---|---|
EQ |
属性は指定された値と等しくする必要があります。 |
NOT |
属性は指定された値と異なる値にする必要があります。 |
LT |
属性は指定した値より小さい値にする必要があります。 |
GT |
属性は指定した値より大きい値にする必要があります。 |
BETWEEN |
属性は指定した値の範囲内にする必要があります。この演算子を使用する場合は、目的の範囲の最小値と最大値を示す 2 つの値を指定する必要があります。 |
CONTAINS |
属性には、文字列属性内の一連の文字など、指定された値を含める必要があります。 |