Zenn
🧑‍💻

【Shopify.dev和訳】Ajax API/Reference/Predictive search

2021/09/12に公開・約22,500字
API
Shopify
#
Ajax
tech

この記事について

この記事は、Ajax API/Reference/Predictive searchの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定｜リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Predictive Search API reference

予測検索 API は、製品、コレクション、ページ、および記事の予測検索結果を表示するために使用できます。

テーマで予測検索を使用する方法については、「テーマに予測検索を追加する」を参照してください。

GET /search/suggest.json

次のリクエスト例は、指定された検索クエリの予測結果を取得します。

GET /search/suggest.json?q={query}&resources[type]=product

クエリパラメーター

Query parameter Required Description
q Yes 検索クエリ。
resources Yes 与えられたクエリに対して、以下の属性に基づいて resources の結果を要求します。。
・type
・limit
・options
type Yes 要求された結果のタイプを指定します。
受け入れられる値は以下のとおりで、コンマ区切りのリストで組み合わせることができます。
・product
・page
・article
・collection
例えば、product,collection,articleなどです。
limit No タイプごとに返される結果の数を制限します。
値の範囲は 1 〜 10 で、デフォルトは 10 です。
options No 要求されたリソースのオプションを、以下の属性に基づいて指定します。
・unavailable_products
・fields
unavailable_products No 利用できない製品の検索結果を表示するかどうかを指定します。
使える値は以下のとおりです。
・show: 利用できない製品を表示します。
・hide：入手不可能な製品を非表示にします。
・last: 利用できない製品を他のマッチング結果の下に表示します。
デフォルト値は last です。
fields No 検索するリソースフィールドのリストを指定します。
受け入れられる値は以下の通りです。
・author
・body
・product_type
・tag
・title
・variants.barcode
・variants.sku
・variants.title
・vendor
検索されるデフォルトのフィールドは title, product_type, variants.title, vendor です。最高の検索結果を得るためには、デフォルトのフィールドセット、またはできるだけ少ないフィールドで検索することをお勧めします。
Example request object
{
  "q": "bag",
  "resources": {
    "type": "product",
    "options": {
      "unavailable_products": "hide",
      "fields": "title,product_type,variants.title"
    }
  }
}
Example request using Fetch
fetch("/search/suggest.json?q=bag&resources[type]=product&resources[options][unavailable_products]=hide&resources[options][fields]=title,product_type,variants.title")
  .then((response) => response.json())
  .then((suggestions) => {
    const productSuggestions = suggestions.resources.results.products;

    if (productSuggestions.length > 0) {
      const firstProductSuggestion = productSuggestions[0];

      alert(`The title of the first product suggestion is: ${
        firstProductSuggestion.title}`
      );
    }
  }
);

Resources response

次の例は、指定されたクエリに関連付けられたリソースオブジェクトを含む/search/suggest.json エンドポイントへの成功したリクエストへの応答です。

Example resources response
{
  "resources": {
    "results": {
      "products": ARRAY OF MATCHING product_object,
      "collections": ARRAY OF MATCHING collection_object,
      "pages": ARRAY OF MATCHING page_object,
      "articles": ARRAY OF MATCHING article_object
    }
  }
}
Example product_object
{
  "available": BOOLEAN,
  "body": STRING w/HTML,
  "compare_at_price_max": DECIMAL ("0.00" when the product has no variants with a "compare_at_price"),
  "compare_at_price_min": DECIMAL ("0.00" when the product has no variants with a "compare_at_price"),
  "handle": STRING,
  "id": INTEGER,
  "image": STRING e.g, "https://cdn.shopify.com/s/...",
  "price": DECIMAL,
  "price_max": DECIMAL,
  "price_min": DECIMAL,
  "tags" : ARRAY OF STRING,
  "title": STRING,
  "type" : STRING,
  "url": STRING e.g, "/products/fast-snowboard?_pos=1&_psq=snowb&_ss=e&_v=1.0",
  "variants": [{
    "available": BOOLEAN,
    "compare_at_price": DECIMAL (nullable),
    "id": INTEGER,
    "image": STRING e.g, "https://cdn.shopify.com/s/...",
    "price": DECIMAL,
    "title": STRING,
    "url": STRING e.g, "/products/fast-snowboard?_pos=1&_psq=snowb&_ss=e&_v=1.0",
    "featured_image": { // (If a variant doesn't have an associated featured_image, then all of the properties of featured_image are set to null.)
      "alt": STRING,
      "aspect_ratio": DECIMAL,
      "height": INTEGER,
      "url": STRING e.g, "https://cdn.shopify.com/s/...",
      "width": INTEGER
    }
  }],
  "vendor": STRING,
  "featured_image": { // (If a product doesn't have an associated featured_image, then all of the properties of featured_image are set to null.)
    "alt": STRING,
    "aspect_ratio": DECIMAL,
    "height": INTEGER,
    "url": STRING e.g, "https://cdn.shopify.com/s/...",
    "width": INTEGER
  }
}

Error responses

search/suggest.json エンドポイントへのリクエストに失敗した場合は、以下のいずれかのエラーレスポンスが返されます。

リストにないその他のエラーは、5xx ステータスコードを返します。

無効なパラメータのエラー

リクエストパラメーターに関連するすべてのエラーは、ステータスコード 422 と関連するエラーメッセージで返されます。説明欄にはリクエストエラーの内容が記載されます。

Invalid parameter example
{
  "status": "422",
  "message": "Invalid parameter error",
  "description": "Invalid option for `unavailable_products` parameter"
}

Expectation failed

テーマがサポートされている言語のいずれかを使用していない場合、API は次のようなエラーを返します。

Expectation failed example
{
  "status": "417",
  "message": "Expectation Failed",
  "description": "Unsupported shop primary locale"
}

Too many requests

リクエストスロットルの制限を超えると、関連するエラーメッセージとともに 429 のステータスコードが返されます。

Example
{
  "status": "429",
  "message": "Too many requests",
  "description": "Throttled"
}

この場合、応答には、秒単位の Retry-After 値を持つ HTTP ヘッダーも含まれます。

Retry-After example
Retry-After: 1

GET /search/suggest

以下のリクエスト例では、指定した検索クエリの予測結果を表示したセクションの HTML を取得しています。

GET /search/suggest?q={query}&resources[type]=product&section_id={section_id}

クエリパラメーター

Query parameter Required Description
q Yes 検索クエリです。
resources Yes 次の属性に基づいて、指定されたクエリのresources結果を要求します。
・type
・limit
・options
type Yes 要求される結果のタイプを指定します。
受け入れられる値は次のとおりです。コンマ区切りのリストに組み合わせることができます。
・product
・page
・article
・collectio
例えば、product,collection,article。
limit No タイプごとに返される結果の数を制限します。
値の範囲は 1 〜 10 で、デフォルトは 10 です。
options No 次の属性に基づいて、要求されたリソースのoptionsを指定します。
・unavailable_products
・fields
unavailable_products No 利用できない製品の検索結果を表示するかどうかを指定します。
使える値は以下のとおりです。
・show: 利用できない製品を表示します。
・hide：入手不可能な製品を非表示にします。
・last: 利用できない製品を他のマッチング結果の下に表示します。
デフォルト値は last です。
fields No 検索するリソースフィールドのリストを指定します。
受け入れられる値は以下の通りです。
・author
・body
・product_type
・tag
・title
・variants.barcode
・variants.sku
・variants.title
・vendor
検索されるデフォルトのフィールドは title, product_type, variants.title, vendor です。最高の検索結果を得るためには、デフォルトのフィールドセット、またはできるだけ少ないフィールドで検索することをお勧めします。
section_id Yes 予測検索クエリでレンダリングするセクションファイルの一意のセクション ID。
Example request object
{
  "q": "bag",
  "resources": {
    "type": "product",
    "options": {
      "unavailable_products": "hide",
      "fields": "title, product_type, variants.title"
    }
  },
  "section_id": "predictive-search"
}
Example request using Fetch
const predictiveSearchSection = document.querySelector('.predictive-search-results');
var requestResponse;

fetch("/search/suggest?q=bag&resources[type]=product&resources[options][unavailable_products]=hide&resources[options][fields]=title,product_type,variants.title&section_id=predictive-search")
  .then((response) => {
    requestResponse = response;
    return response.text();
   })
  .then((text) => {
    if (!requestResponse.ok) {
      throw new Error(`${requestResponse.status}: ${text}`);
    }

    const resultsMarkup = new DOMParser()
      .parseFromString(text, 'text/html')
      .querySelector('#shopify-section-predictive-search').innerHTML;

    predictiveSearchSection.innerHTML = resultsMarkup;
  })
  .catch((error) => {
    console.error(error);
  });

Section response

search/suggest エンドポイントへのリクエストが成功したときのレスポンスです。

セクション・レスポンスには、指定されたセクションの HTML が、指定されたクエリの結果を含む Predictive_search オブジェクトとともにレンダリングされます。

例えば、以下のセクションでは、以下のセクション・レスポンスが生成されます。

Example section
{%- if predictive_search.performed -%}
  <div id="predictive-search-results">
    {%- if predictive_search.resources.products.size > 0 -%}
      <h3>Products</h3>
      <ul>
        {%- for product in predictive_search.resources.products -%}
          <li><a href="{{ product.url }}">{{ product.title }}</a></li>
        {%- endfor -%}
      </ul>
    {%- endif -%}
  </div>
{%- endif -%}
Example section response


Copy
<div id="shopify-section-predictive-search">
  <div id="predictive-search-results">
    <h3>Products</h3>
    <ul>
      <li><a href="/products/running-shoes">Running Shoes</a></li>
      <li><a href="/products/tennis-shoes">Tennis Shoes</a></li>
    </ul>
  </div>
</div>
Example collection_object
{
  "body": STRING w/HTML,
  "handle": STRING,
  "id": INTEGER,
  "featured_image": { // (If a collection doesn't have an associated featured_image, then all of the properties of featured_image are set to null.)
    "alt": STRING,
    "width": INTEGER,
    "height": INTEGER,
    "aspect_ratio": DECIMAL,
    "url": STRING e.g, "https://cdn.shopify.com/s/..."
  },
  "published_at": STRING DATE,
  "title": STRING,
  "url": STRING e.g, "/collections/snowboards?_pos=1&_psq=sno&_ss=e&_v=1.0"
}
Example page_object
{
  "author": STRING,
  "body": STRING w/HTML,
  "handle":STRING,
  "id": INTEGER,
  "published_at": STRING DATE,
  "title": STRING,
  "url": STRING e.g, "/pages/my-page?_pos=1&_psq=my&_ss=e&_v=1.0"
}
Example article_object
{
  "author": STRING,
  "body": STRING w/HTML,
  "handle": STRING,
  "id": INTEGER,
  "image": STRING e.g, "https://cdn.shopify.com/s/...",
  "published_at": STRING DATE,
  "summary_html": STRING w/HTML,
  "tags": ARRAY OF STRING,
  "title": STRING,
  "url": STRING e.g, "/blogs/news/my-article?_pos=1&_psq=my&_ss=e&_v=1.0"
}

Error responses

search/suggest エンドポイントへのリクエストが失敗した場合は、以下のエラーステータスコードのいずれかが返されます。

Status code Description
404 Section not found - 指定されたセクション ID がテーマ内で見つかりませんでした。
417 Expectation failed - テーマがサポートされている言語のいずれかを使用していません。
422 Invalid parameter error - クエリ・パラメータに使用された値が無効でした。
429 Too many requests - リクエストスロットルの制限を超えています。

応答テキストを出力して、エラーの詳細を取得できます。詳細については、フェッチを使用したリクエストの例を参照してください。

Searchable properties

検索結果は、クエリに含まれるリソース type に応じて、異なる検索可能なプロパティに基づいて表示されます。

Resource type Searchable properties
Products body
・product_type
・tag
・title
・variants.barcode
・variants.sku
・variants.title
・vendor
Pages ・author
・body
・title
Articles ・author
・body
・tag
・title
Collections ・title

誤字脱字の許容範囲

予測検索には、タイプミスを含む検索語が正しい一致した検索結果を返すようにするタイポトレランスがあります。

タイポトレランスが 1 に設定されている場合、検索語と 1 文字異なる検索結果や、2 文字の順序が異なる検索結果が表示されます。タイポトレランスを有効にするには、検索語の最初の 4 文字が正しく入力されている必要があります。

以下のフィールドがタイポトレランスに対応しています。

Resource type Searchable properties
Products ・product_type
・title
・variants.title
・vendor
Pages ・author
・title
Articles ・author
・title
Collections ・title

部分的な単語の一致

予測検索は、単語の部分一致をサポートしています。つまり、入力した単語がまだ不完全であっても、検索結果が表示されます。たとえば、「sweate」と入力すると、「sweater」の検索結果が表示される場合があります。

予測検索では、単語の部分一致を適用する際に以下のような制限があります。

検索クエリが複数の単語を含む場合、部分的な単語の一致はクエリの最後の単語にのみ適用されます。
部分的な単語の一致は、検索用語の最後にのみ適用されます。例えば、book と入力した場合、ebook の検索結果は表示されません。
部分的な単語の一致は、特定の言語を使用するテーマでのみサポートされています。詳細については、「要件と制限」を参照してください。

予測検索は、ストアフロント検索とは異なる検索エンジンを使用します。そのため、部分的な単語の一致は同じようには処理されません。予測検索では単語の部分一致がサポートされていますが、ストアフロント検索では、prefix オプションパラメータが last に設定されている場合のみサポートされます。

要件と制限

このセクションでは、予測検索がどのようにサポートされているか、また現在の制限事項について説明します。

サポートされている言語

予測検索は、以下のテーマ言語を使用するテーマでのみサポートされています。

  • English
  • French
  • Spanish
  • Portuguese (Brazil)
  • German
  • Dutch
  • Italian
  • Danish
  • Swedish
  • Portuguese (Portugal)
  • Finnish
  • Norwegian (Bokml)
  • Turkish
  • Romanian
  • Hungarian
  • Russian
  • Polish
  • Czech
  • Greek
  • Icelandic
  • Lithuanian
  • Slovenian
  • Slovak
  • Bulgarian
  • Vietnamese
  • Croatian
  • Indonesian
  • Latvian
  • Estonian
  • Serbian
  • Ukrainian
  • Catalan
  • Norwegian (Nynorsk)
  • Faroese
  • Portuguese
  • Albanian
  • Bosnian
  • Afrikaans
  • Macedonian
  • Armenian
  • Serbo-Croatian
  • Latin
  • Welsh
  • Gaelic
  • Moldovan

<head> セクションの script タグは、テーマの言語で予測検索がサポートされているかどうかを示します: <script id="shopify-features"></script>。このスクリプト タグには、JSON エンコードされた predictiveSearch キーとブール値が含まれています。このキーが true に設定されている場合、そのテーマ言語がサポートされており、予測検索が有効になります。そうでない場合は、false に設定されます。

制限事項

  • 個々の製品を予測検索結果から除外することはできません。メタフィールドオブジェクトを使用して製品が SEO から隠されている場合、その製品は予測検索結果に表示されません。詳しくは、「メタフィールドオブジェクト」を参照してください。
  • API は、リクエストタイプごとに 10 件以下の予測候補を返します。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定｜リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Discussion

ログインするとコメントできます