Contentful APIの効率的なクエリを可能にするSelect Operatorの基本と活用パターン

Contentfulを使ったヘッドレスCMS開発において、APIの効率的な利用は非常に重要です。APIレスポンスのサイズやリクエスト数はアプリケーションのパフォーマンスに大きな影響を与えます。

今回は、ContentfulのAPIで利用できる「Select Operator」に焦点を当て、APIレスポンスを最適化する方法を紹介します。必要なデータだけを取得することで、アプリケーションの応答速度向上やネットワーク帯域幅の節約に役立ちます。

Select Operatorとは

Select Operatorは、Contentful APIレスポンスから特定のフィールドのみを選択的に取得できるクエリパラメーター です。

APIのペイロードサイズを削減し、アプリケーションのパフォーマンスを向上させる目的で使用されます。

一般的なAPIリクエストでは エントリーの全データが返され ますが、実際にアプリケーションで必要なのは一部のフィールドだけというケースが多いかと思います。

Select Operatorを使うことで、必要なフィールドだけを指定してデータを取得できます。

基本的な使い方

Select Operatorの基本的な構文は以下の通りです：

https://cdn.contentful.com/spaces/<space_id>/entries/?select=fields.fieldName1,fields.fieldName2&content_type=<content_type_id>

例えば、製品カタログ( product )から製品名と価格だけを取得したい場合：

https://cdn.contentful.com/spaces/<space_id>/entries/?select=fields.productName,fields.price&content_type=product

このリクエストにより、以下のようなコンパクトなレスポンスが返されます：

json
{
  "sys": {
    "type": "Array"
  },
  "total": 4,
  "skip": 0,
  "limit": 100,
  "items": [
    {
      "fields": {
        "productName": "Whisk Beater",
        "price": 22
      }
    },
    {
      "fields": {
        "productName": "SoSo Wall Clock",
        "price": 120
      }
    }
    // 他の製品...
  ]
}

通常のレスポンスと比較すると、"items" > "fields"キー内のデータサイズが大幅に削減されていることがわかります。

オブジェクト全体の選択と除外

Select Operatorでは、sysやfieldsといったオブジェクト全体を選択または除外することも可能です。

fields オブジェクトのみを取得

https://cdn.contentful.com/spaces/<space_id>/entries/?select=fields&content_type=product

上記リクエストでは、メタデータ（sysオブジェクト） を除外し、コンテンツデータ（fieldsオブジェクト）のみを取得します。

sys オブジェクトのみを取得

https://cdn.contentful.com/spaces/<space_id>/entries/?select=sys&content_type=product

このリクエストでは逆に、コンテンツデータを除外し、メタデータのみを取得します。これはデバッグやシステム情報の確認に役立ちます。

注意点: クライアントライブラリを使用している場合、sysプロパティはリンクエントリの解決やリソースの型生成に使用されるため、Select Operatorでsysプロパティを省略できないことがあります。

アセットでの使用

Select Operatorはアセット（画像やファイル） の取得にも適用できます：

https://cdn.contentful.com/spaces/<space_id>/assets/?select=fields.title

このリクエストでは、アセットのタイトルのみが返されます：

json
{
  "sys": {
    "type": "Array"
  },
  "total": 7,
  "skip": 0,
  "limit": 100,
  "items": [
    {
      "fields": {
        "title": "City Street"
      }
    },
    {
      "fields": {
        "title": "Celebration"
      }
    }
    // 他のアセット...
  ]
}

Select Operatorの制限事項

Select Operatorを使用する際には、いくつかの制限事項があります：

• コレクションエンドポイントのみ: Select Operatorは、エントリやアセットの コレクションエンドポイントでのみ使用可能 です。単一のエントリやアセットのエンドポイントでは無視されます。
• content_type パラメーターが必要: エントリに対してSelect Operatorを使用する場合、content_type パラメーターを指定する必要があります。
• プロパティの深さ制限: プロパティの深さは最大2階層までです。例えば、select=fields.productName.en-US は無効です。
  • Locale指定の方法: 特定のロケールを選択する場合は、selectとlocaleパラメーターを組み合わせる必要があります： /assets/?select=fields.productName&locale=en-US
• 最大プロパティ数: 最大100プロパティまで選択可能です。
• リンクフィールドの制限: リンクされたフィールドがある場合、選択したフィールドに関連するコンテンツのみが返されます。
• エラーハンドリング: 無効なプロパティパスを指定すると、400 Bad Requestエラーが返されます。

演算子とパラメーターさらにフィルタリングしてみる

Selectに加え、演算子やパラメーターを活用することで、より柔軟で効率的なAPIリクエストが可能になります。

利用できる演算子の種類

• =（等価演算子）: 完全一致するフィールド値でフィルタリング

  ?fields.title=Hello
  

• [ne]（不等価演算子）: 指定した値と一致しないフィールド

  ?fields.title[ne]=Hello
  

• [in]（含有演算子）: 指定した複数の値のいずれかと一致するフィールド

  ?fields.tags[in]=news,blog
  

• [nin]（非含有演算子）: 指定した複数の値のいずれとも一致しないフィールド

  ?fields.tags[nin]=news,blog
  

• [exists]（存在演算子）: フィールドの存在有無

  ?fields.featuredImage[exists]=true
  

• [match]（部分一致演算子）: テキストフィールドの部分一致

  ?fields.description[match]=product
  

  • 入力した検索語を二重引用符 (") で囲むと、フレーズ検索が有効になり、より効率的なクエリになります
  • 2文字未満の検索トークンは無視されるため、検索語は2文字以上にしてください
  • 大文字と小文字は区別されないため、予想よりも多くの結果が返される場合があります

• [all]（全一致演算子）: 配列フィールドで指定したすべての値を含むエントリ

  ?fields.tags[all]=news,featured
  

一緒に使えるパラメーター

• content_type: 特定のコンテンツタイプのエントリのみを取得

  https://cdn.contentful.com/spaces/<space_id>/entries/?select=fields.title,fields.slug&content_type=blogPost
  

• order: 結果の並び替えを指定

  ?select=fields.title,fields.date&order=-fields.date&content_type=blogPost
  

• limit: 返される結果の最大数を制限（デフォルト=1000）

  ?select=fields.title&limit=5&content_type=article
  

• skip: ページネーション用にスキップする結果数を指定

  ?select=fields.title&skip=10&limit=10&content_type=product
  

• include: リンクされたエントリの解決の深さを指定

  ?select=fields.title,fields.author&include=2&content_type=blogPost
  

• locale: 特定の言語のコンテンツのみ取得

  ?select=fields.title&locale=ja-JP&content_type=blogPost
  

• mimetype_group: 特定のMIMEタイプグループのアセットのみをフィルタリング

  ?select=fields.title,fields.file&mimetype_group=image
  

パフォーマンス最適化のポイント

Select Operatorを活用したパフォーマンス最適化のポイントをいくつか紹介します：

• 必要なフィールドのみを選択: アプリケーションで実際に使用するフィールドのみを選択し、レスポンスサイズを削減する
• 一貫したクエリパターン: CDAのキャッシュヒット率を高めるために、一貫したクエリパターンを使用する
• エントリーIDやSlugの検索: エントリーIDやSlugの検索にはできるだけ等価演算子を使用する
• フレーズ検索の活用: 可能な限りフレーズ検索を使用する

まとめ

APIの効率的な利用はユーザー体験の向上に直結します。必要なデータだけを取得することで、ネットワーク帯域幅の節約、レスポンス時間の短縮、クライアントサイドの処理負荷の軽減が可能になります。

参考リンク

• Contentful Delivery API - Search parameters