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

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

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

フィルタを使ったクエリ

フィルターは、興味のあるデータだけを抽出するのに非常に便利です。これらのフィルターは、構文が少し難しいことがあります。以下では、レコードの GET リクエストの例で、それぞれがどのように形成されるかを概説し、その後に完全な例を示します。

カスタムフィールドのフィールド名には、常に5桁の文字列識別子が先頭に付きます。これらは、GET allリクエストでフィールドの本当の名前を確認した後に最も簡単に見つけることができます。

• 例"field"="maytq_scrap_count"

引数値は多くの場合、単純明快である。テキスト値の場合は、必ず引用符で囲んでください。

• 例"arg":15

使用したい関数型に合わせる。

• 例"functionType": "greaterThan"

完全なリクエストは以下のようになる：

https://brian.tulip.co/api/v3/tables/W2HPvyCZrjMMHTiip/records?limit=100&sortBy=_sequenceNumber&sortDir=asc&filters=[{"field": "maytq_scrap_count", "arg": 15, "functionType": "greaterThan"}]&filterAggregator=any

ドキュメントのクエリ・パラメータを見つける方法

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

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

クエリパラメータの構文

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

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

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

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

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

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

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

リミット

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

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

フィルタ

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

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

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

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

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

ソート

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

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

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

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

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

オフセット

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

例5番目以降のレコードだけを表示したい。クエリパラメータの構文は以下のようになります：

フィルタアグリゲータ

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

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

複数のフィルター

場合によっては、テーブル内で複数のフィルタをチェックすることがあります。この場合は、filters オブジェクトに複数のフィルタを追加します。次のようになります：

filters=[{"field": "maytq_scrap_count", "arg": 15, "functionType": "greaterThan"},{"field": "maytq_scrap_reason", "arg": "scratch", "functionType": "equal"}].

さらなる読み物

• HTTPコネクターの概要
• HTTP コネクタ関数の作成と設定方法
• テーブルAPIの使用方法