クエリ・パラメータの設定方法
  • 04 Nov 2023
  • 1 読む分
  • 寄稿者

クエリ・パラメータの設定方法


Article Summary

API ドキュメントに従って、HTTP Connector Function でクエリパラメータを使用する基本を学びます。

クエリパラメータにより、Connector Function の結果を絞り込み、調整することができます。パラメータを使用して、並べ替え、フィルタリング、制限の設定、インデックスのオフセットなどを行います。この記事では Tulip Table API のパラメータを使用していますが、他の API ではパラメータ要件が異なる場合があります。ドキュメントを確認して、正しい構文と仕様を使用していることを確認してください。

クエリ・パラメータの探し方

リクエストで使用可能なクエリパラメータを見つけるには、APIドキュメントに移動します。Tulip Table APIを使用している場合は、your-instance.tulip.co/apiDocsでドキュメントを見つけることができます。 使用したいリクエストを選択し、Parametersタブまでスクロールダウンします。

Parameters in API Docs.png

各メソッドにはパラメータが設定されていますが、すべてのリクエストにパラメータが設定されているわけではありません。事前にドキュメントで利用可能なものを確認しておきましょう。

クエリパラメータの構文

パラメータ構文のクエリは、クエリストリングフォーマットに依存しています。この形式は、クエリ文字列自体を URL の一部として、指定されたパラメータに値を割り当てます。

Connector Function Editor で、Add Parameterをクリックして新しいクエリパラメータを作成します。

Query Parameters - Add Parameter.png

クエリパラメータには、キーと 値の 2 つの部分があります。キーはパラメータの名前で、値は結果のパラメータを設定する情報です。

クエリパラメータの構文には Dot Notation を使用します。大文字と小文字が相手システムの API 標準と一致していることを確認してください。

コネクタ関数への共通パラメータの適用

コネクタ関数にパラメータを設定するには、まず API ドキュメントで使用するパラメータを特定します。パラメータはそれぞれ要件が異なるので、どのようなものかを確認しましょう。

:::(Info) (注)連続性を持たせるため、以下の各例では同じリクエスト API Call を使用します。これは、チューリップテーブルAPI経由でチューリップテーブルのレコード一覧を取得するGETリクエストです。他のAPIを使用する場合は、パラメータの仕様が異なりますので、APIドキュメントの要件を確認してください:

リミット

リミットは返される結果の上限を設定します。制限値には初期値が設定されているものもあるので、必ずAPIドキュメントで初期値を確認してください。

コネクタ関数の実行時に 70 レコードを超えないようにしたい。幸運なことに、このリクエストにおける制限のデフォルト値は 10 で、最高値は 100 です。クエリパラメータの構文は以下のようになります:

Query Parameters - Limits.png

フィルタ

フィルタは、パラメータに指定された情報に基づいて結果を分離し、絞り込みます。

フィルターには3つの部分があり、個別のパラメーターに記述する必要があります:

  • フィールド - テーブルのカラム名。
  • Function Type - 比較関数のタイプ。
  • 引数 - 結果を比較する値

各フィルターは3つの部分を持ち、各フィルターはオブジェクトです。ドット記法を使用して各キーを記述し、パラメータのタイプ('filter')、フィルタ番号(0からn)、フィルタの部分('field'、'functionType'、'arg')を指定します。フィルタの3つの部分すべてに対応するパラメータが必要です。

コネクタ関数の結果が、関数の指定された入力値(consumable)に等しい特定のフィールド(eubmc_value)の値のみを表示するようにしたい。これは関数のパラメータの最初のフィルタなので、フィルタ番号は 0 です。つまり、このフィルタのすべてのキーは 'filter.0' で始まります。このフィルターの構文は以下のようになります:

Query Parameters - Filters.png

ソート

結果の並べ替えは、パラメータの情報に基づいてビューに優先順位を付けます。ソートされた結果は、集計に含まれるものを決定します。複数のソート関数を持つことができますが、オプションの順序によってソートの優先順位が決まります。

ソート関数には2つの部分があります:

  • sortBy - 結果を並べ替えたいフィールド。
  • sortDir - 昇順(asc)または降順(desc)のソート方向。

各ソート関数には3つの部分があります。ドット記法を使ってそれぞれのキーを記述し、パラメータの種類('sortOptions')、ソート番号(0からn)、ソートの引数('sortBy'または'sortDir')を指定します。ソート関数が動作するためには、3つの部分すべてにパラメータが必要です。

コネクタ関数の結果を、最も新しく更新されたフィールドで昇順にソートしたい。これは最初のソート関数なので、ソート番号は0です。これは、このソートのキーが両方とも'sortOptions.0'で始まることを意味します。sortByキーには、更新されたフィールドをソートするためにAPIドキュメントから派生した特別な値('_updatedAt')を指定します。これらのパラメータの構文は以下のようになります:

Query Parameters - Sorting.png

オフセット

Offsetsは、返される結果のインデックスを決定します。このパラメータはページネーションに使用され、ソートパラメータで決定されるレコードの順番には使用されません。パラメータの値は0以上の整数でなければなりません。

上位5位までの結果を表示しないように、5位以降のレコードのみを表示したい。クエリパラメータの構文は以下のようになります:

Query Parameters - Offset.png

フィルタアグリゲータ

フィルタアグリゲータは、パラメータ内のフィルタをどのように組み合わせるかを決定します。指定できる値は 'any' と 'all' の2つです。値 'all' は、レコードを結果に含めるためには、すべてのフィルターにレコードがなければならないことを意味します。any'の値は、少なくとも1つのフィルターがレコードにマッチしなければ結果に含まれないことを意味します。パラメータを設定するかどうかにかかわらず、デフォルト値は 'all' です。

一連のフィルタをクエリパラメータに設定していますが、 リクエストにマッチするレコードを取得するためには、 そのうちのひとつだけが真である必要があります。クエリパラメータの構文は次のようになります:

Query Parameter - Filter Aggregators.png

参考文献


この記事は役に立ちましたか?