クエリパラメータの概要

エンドポイントのみを使用して（GET /activities のように）、Cloud API の呼び出しを実行すると、応答ペイロードにはリソースのデフォルトセットとデフォルト構造が含まれます。

デフォルトの動作は、以下の方法でカスタマイズできます。

  • プロパティのカスタムセットの指定
  • 一定の条件を満たさないリソースをフィルタで除外
  • リソースの並べ替え
  • 各ペイロードで返される要素の数の制限
  • クエリの条件を満たすデータベースリソースの合計数の取得

応答ペイロードはクエリパラメータを使用してカスタマイズできます。クエリパラメータは、HTTP 要求に追加される式です。これによって、デフォルトの応答ペイロードを変更します。

Cloud API の呼び出しには、クエリパラメータをいくつでも含めることができます。クエリパラメータのリストの先頭には、疑問符（?）が付きます。クエリパラメータが複数ある場合は、それぞれがアンパサンド（&）で区切られます。例：

  • GET /activities?fields=*all
  • GET /activities?filter=escalated:eq:false
  • GET /activities?fields=*all&filter=escalated:eq:false

包含リソース

include クエリパラメータを使用して、応答の主要リソースに関連するリソースを含めることができます。また、クエリパラメータを使用して、包含リソースのプロパティのカスタムセットを指定したり、一定の条件を満たさない包含リソースをフィルタで除外したり、包含リソースを並べ替えることなどもできます。詳細については、包含リソースでのクエリパラメータの使用を参照してください。

クエリパラメータ定義の表示

各エンドポイントについて、API 定義にはそのエンドポイントがサポートするクエリパラメータの詳細があります。

Swagger UI のクエリパラメータ

Swagger UI では、クエリパラメータ情報はデフォルトで非表示になっています。詳細を表示するには、エンドポイントの操作ボタン（GET /activities の［GET］ボタンなど）をクリックします。クエリパラメータの詳細が、エンドポイントの下に表示されます。

パラメータの定義

［パラメータ］セクションには、各クエリパラメータの説明があります。

サポート対象のパラメータ

［応答］セクションには［モデル］タブが含まれています。このタブには、特定のクエリパラメータをサポートするフィールドについての情報があります。例えば、一部のフィールドでは結果の並べ替えができますが、すべてのフィールドで可能なわけではありません。並べ替えをサポートするフィールドは、モデルに "sortable": true のテキストが表示されます。

クエリパラメータのエラーメッセージ

クエリパラメータをサポートしないフィールドで当該パラメータの使用を試みると、Cloud API では不正要求のエラー（エラーコードは 400）とエラーメッセージを返します。例えば、GET /activities?sort=escalationDate を実行すると、Cloud API では以下のようなエラーメッセージを返します。

"message": "The sort column 'escalationDate' is not a valid option. The valid 
      sort options are [assignedUser, dueDate, escalated, priority, status, subject], 
      optionally prefixed with '-' to indicate a descending sort."
Java