共通クエリパラメータ

最終更新: 2026年6月25日

WEEGLOO のリスト取得エンドポイント(GET /spaces/{spaceId}/contents のようにコレクションを返す GET)は、共通のクエリパラメータを受け取ります。これらのパラメータで、1 ページに取得する件数を制限し、ソート基準を指定し、関連リソースをまとめて取得し、必要な Field だけを選んで受け取り、条件でリストを絞り込み、次・前のページへ移動します。

これらのパラメータはリソースの種類に関係なく同じ方法で動作します。個々のリソースリファレンスはそのリソース固有の条件のみを個別に説明し、ここで扱う共通パラメータについてはこのページを参照します。

パラメータ

パラメータ型説明
limitinteger1 ページに返す項目数。1-100。デフォルト値 15。
skipintegerスキップする項目数。デフォルト値 0。ページ移動には skip ではなくカーソル(next・prev)を使います。下記の ページネーション (カーソル) を参照してください。
nextstring次のページのカーソル。前のレスポンスの links.next から取得します。
prevstring前のページのカーソル。前のレスポンスの links.prev から取得します。
orderstringソート基準。カンマで複数の基準をつなげて多段ソートを行います(例: sys.createdAt,sys.id)。デフォルト値 sys.createdAt,sys.id。fields. で始まる Field は Locale を含みます(例: fields.title.en-US)。
includeinteger関連リソースをまとめて展開して取得するレベル。0=デフォルト、1=関連リソース、2=ネストした関係、3=全体。デフォルト値 0。
selectstring結果に含める Field(例: sys.id,sys.createdAt)または除外する Field(例: -sys.id)をカンマで列挙します。含めることと除外することを 1 回のリクエストで混在させません。
filter(条件)条件でリストを絞り込みます。形式は下記の フィルター を参照してください。

order・select に使う sys Field の種類は システムプロパティ (sys) で確認できます。

フィルター

フィルター条件は filter[] で包まず、クエリパラメータとして直接送信します。形式は {フィールド}[{演算子}]={値} で、演算子を省略すると eq として解釈します。使用できる演算子の一覧は下記の 演算子 を参照してください。

{フィールド}[{演算子}]={値}

たとえば name が タンブラー で始まる項目だけを取得するには、name[prefix]=タンブラー と送信します。ルールと注意事項は次のとおりです。

  • filter[] で包みません。 filter[name[prefix]]=タンブラー のように包むと動作しません。
  • 複数の条件は AND で結合されます。 すべてを満たす項目だけが残り、いずれか一つを満たせばよい OR 検索はサポートしていません。一つの Field で複数の値のいずれかに一致させるには in を使います。
  • fields. 条件は Locale を含みます。 たとえば fields.file.ko-KR.mimeGroups=Image は Media リストから画像ファイルだけを、sys.createdAt[gte]=2026-06-01T00:00:00Z はその時点以降に作成された項目だけを取得します。
  • fields. で Content リストをフィルター・ソートするときは Content Type も指定する必要があります。 sys.contentType.sys.id を合わせて送る必要があり(/contents リスト限定)、contentType= だけでは代用できません。詳しくは Content リファレンスを参照してください。

演算子

演算子意味値
eq等しい。演算子を省略するとこれとして解釈します。単一の値
ne等しくない単一の値
in列挙した値のいずれかと等しい値のリスト
nin列挙した値のいずれとも等しくない値のリスト
all配列 Field が列挙した値をすべて含む値のリスト
exists値が存在するかどうかtrue または false
prefix前方一致単一の値
gt / gteより大きい / 以上単一の値
lt / lteより小さい / 以下単一の値
regex正規表現一致。高度な検索専用(下記の 高度な検索)。正規表現
nearLocation Field が一点から一定の距離内。高度な検索専用。緯度,経度,距離(距離の単位はキロメートル)
withinLocation Field が多角形の内側。高度な検索専用。緯度,経度 の座標を三組以上つなげた値

RichText・Json Field は検索の対象ではないため、フィルター条件に使えません。

regex・near・within 演算子とテキストの 全文検索は、高度な検索でのみ動作します。高度な検索は、リスト取得リクエストにヘッダー X-Weegloo-Advanced-Search: true を加えて有効にし、レスポンスにも同じヘッダーが付いて返ってきます。

  • 全文検索: 全文検索が有効なテキスト Field(LongText)に eq を使うと、完全に等しい値ではなく、その値を含む項目まで部分・類似マッチで探します。高度な検索を有効にしていない場合や、料金プランが高度な検索を提供していない場合は、同じ eq が完全一致として動作します。
  • Location 検索: near(半径)・within(多角形)は Location Field にのみ使い、高度な検索でのみ動作します。
  • 高度な検索を使えないリクエストで regex・near・within を送信すると、受け付けられません。

ページネーション (カーソル)

リストレスポンスの本文には links オブジェクトが含まれ、その中に next・prev があります。links.next は次のページへ向かう完全なパスです。

/v1/spaces/HnQ32YiH/contents?limit=15&next=<カーソル>

次のページを取得する方法は 2 つあります。links.next のパスをそのまま呼び出すか、links.next から next カーソル値を取り出して次のリクエストの next パラメータとして渡します。links.next がなければ最後のページです。前のページは links.prev で同じ方法で移動します。

ページをめくるときに skip を増やして使わないでください。リストの間で項目が追加・削除されると、skip の位置がずれて項目が抜けたり重複したりすることがあります。カーソル(next・prev)にはこの問題がありません。

次はリストレスポンスの構造の例です。ラッパーの sys.type は TotalPageResponse で、items に項目の配列が、links に移動パスが入ります。

{
  "sys": { "type": "TotalPageResponse" },
  "limit": 15,
  "totalCount": 42,
  "items": [
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7PUl8DzDgDzP",
        "type": "Content",
        "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
        "createdAt": "2026-06-18T09:51:14.597Z",
        "updatedAt": "2026-06-18T09:51:44.128Z",
        "version": 2,
        "status": "Published"
      }
    }
  ],
  "links": {
    "self": "/v1/spaces/HnQ32YiH/contents?limit=15",
    "next": "/v1/spaces/HnQ32YiH/contents?limit=15&next=Q3Vyc29yVmFsdWU"
  }
}

totalCount は条件に一致する項目の総数で、limit はこのレスポンスに適用された 1 ページのサイズです。items にはそのページに該当する項目だけが入ります。