1. REST APIを使用した統合

チュートリアル: APIを使用して検索エクスペリエンスを作成し、イベントを送信する

日本語翻訳に関する免責事項

このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。

管理者が 属性、 ソース、検索機能を設定した後、Sitecore Searchと統合して、訪問者向けの検索エクスペリエンスを作成できます。

APIを使用してこれを行うには、Search and Recommendation APIを呼び出してコンテンツをリクエストし、その応答を使用して必要なエクスペリエンスを作成します。同時に、該当するすべてのイベント データをEvents APIを使用してSearchに送信することもおすすめします。

大事な

このチュートリアルには、特定の検索エクスペリエンスを作成するために必要なAPI要求が含まれています。実装には他の機能が必要な場合がありますが、このチュートリアルは、以前の要求の上に要求を構築する方法のガイドラインとして使用してください。

さまざまなエクスペリエンスを作成するには、Search and Recommendation APIを調べて必要なオブジェクトを見つけ、そのオブジェクトを使用して、このチュートリアルの例に基づいて要求を作成します。同様に、Events APIのオブジェクトを調べて、該当するすべてのイベントをSearchに送信します。

このチュートリアルは、サイトへの訪問者が検索結果ページにアクセスし、facetsを表示するシナリオに基づいています。次に、訪問者は検索バーにキーワードを入力すると、preview searchウィジェットに候補が表示されます。訪問者が提案をクリックすると、新しい結果を含む結果ページが表示され、ファセット値を選択して結果をフィルター処理します。次に、結果をコンテンツタイトルの降順に並べ替え、content itemをクリックします。

このチュートリアルでは、次のAPI要求を作成する方法について説明します。

  • facetsを使用した検索結果ページの作成

  • preview searchに表示するrecommendationsを取得する

  • キーワードに基づいて検索結果ページを作成する

  • ファセット値でフィルター処理された検索結果ページを作成する

  • 並べ替えを適用した検索結果ページを作成する

  • 訪問者をコンテンツページにリダイレクトする

  • SearchするSendイベント

メモ

preview searchウィジェットに候補を表示するAPIリクエストを除き、次の各リクエストは前のリクエストに基づいて構築されていることがわかります。

facetsを使用した検索結果ページの作成

訪問者が最初に検索ページにアクセスしたときに、検索結果とfacetsを表示する必要があります。

facetsを含む検索結果ページを作成するには:

  • context、content、およびファセット オブジェクトを追加し、検索結果ページのIDをrfk_idの値として渡します。

facetsを含む検索結果ページを表示するためのデータを取得するためのCURLリクエストの例を次に示します。

curl --location 'https://discover.sitecorecloud.io/discover/v2/159871551' \
--header 'Authorization: 01-22977f73-b96bm327df2ffc7ip16d4c030a201240ced2487n' \
--data '{
    "context": {
        "user": {
            "UUID": "159828561-m7-17-44-1p-c0ya4nb69t8o0iho2eia-1667926756187"
        },
        "locale": {
            "country": "us",
            "language": "en"
        }
    },
    "widget": {
        "items": [
            {
                "entity": "content",
                "rfk_id": "rfkid_7",
                "search": {
                    "content": {},
                    "facet": {
                        "all": true,
                        "max": 100
                    }
                }
            }
        ]
    }
}'

応答の例を次に示します。

{
    "widgets": [
        {
            "rfk_id": "rfkid_7",
            "type": "content_grid",
            "entity": "content",
            "facet": [
                {
                    "name": "type",
                    "label": "Type",
                    "value": [
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoidHlwZSIsInZhbHVlIjoiTmV3cyJ9",
                            "text": "News",
                            "count": 688
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoidHlwZSIsInZhbHVlIjoiQ3VzdG9tZXJzIn0=",
                            "text": "Customers",
                            "count": 576
                        },
                        ...
                    ]
                },
                {
                    "name": "review_rating",
                    "label": "Rating",
                    "value": [
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoidHlwZSIsInZhbHVlIjoiTmV3cyJ9",
                            "text": "5",
                            "count": 310
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoidHlwZSIsInZhbHVlIjoiQ3VzdG9tZXJzIn0=",
                            "text": "4",
                            "count": 780
                        },
                        ...
                    ]
                }
            ],
            "content": [
                {
                    "description": null,
                    "id": "https___www_sitecore_com_company_newsroom_news_2023_03_sitecore-named-a-leader-for-dxp",
                    "review_rating": "5",
                    "image_url": "https://wwwsitecorecom.azureedge.net/-/media/sitecoresite/2023-gartner-magic-quadrant-for-digital-experience-platforms-dt-3.png?md=20230316T153407Z",
                    "source_id": "730959",
                    "title": "Sitecore named a Leader for DXP",
                    "keywords": ["DXP","gartner"],
                    "type": "News",
                    "url": "https://www.sitecore.com/company/newsroom/news/2023/03/sitecore-named-a-leader-for-dxp"
                },
                {
                    "description": " active and real-time content integration framework for consistent and continuous data synchronization of product content and assets across Sitecore Content Hub and OrderCloud....",
                    "review_rating": "4",
                    "image_url": "https://wwwsitecorecom.azureedge.net/-/media/sitecoresite/images/home/marketplace/appmarketplace.svg?md=20220328T214947Z",
                    "source_id": "730959",
                    "title": "Connector & App Marketplace",
                    "keywords": ["connector","content hub", "data synchronization"],
                    "type": "Others",
                    "url": "https://www.sitecore.com/products/marketplace"
                }
                ...
            ],
            "total_item": 3443,
            "limit": 10,
            "offset": 1
        }
    ],
    "dt": 45,
    "ts": 1680573661787
}

応答を使用して検索エクスペリエンスを作成するには:

  1. ページ上のcontent itemsのリストを表示するには、応答のwidgets.contentオブジェクトを参照してください。各content itemについて、タイトル、説明、画像、URLをtitle、description、image_url、およびurlフィールドから取得します。

  2. facetsを表示するには、応答のwidgets.facetオブジェクトを参照してから、次のようにします。

    • facet.labelフィールドからファセットの名前を取得します。ここには、TypeとRatingの2つのfacetsがあります。

    • facet.valueオブジェクトから各ファセットのファセット値を取得します。textキーの値を、ページに表示するファセット値の名前として使用します。countの値を、そのファセット値のcontent items数として使用します。

      たとえば、typeファセットの場合、Newsというファセット値を688 content itemsとともに使用できます。同様に、review_ratingファセットの場合、5というファセット値を310 content itemsで使用できます。

preview searchに表示するrecommendationsを取得する

訪問者が検索バーにキーワードを入力したら、候補を表示します。

recommendations to show in a preview search widgetを取得するには:

この例では、訪問者がキーワードclouを入力し、Keyword属性に基づいて候補を表示します。

以下は、preview searchウィジェットのkeyword属性に基づいてrecommendationsを表示するデータを取得するためのCURLリクエストの例です。

curl --location 'https://discover.sitecorecloud.io/discover/v2/159871551' \
--header 'Authorization: 01-21667f73-b96bn327df2ffc7ab16d4c030a201240ced2490a' \
--data '{
    "context": {
        "user": {
            "UUID": "159828561-m7-17-44-1p-c0ya4nb69t8o0iho2eia-1667926756187"
        },
        "locale": {
            "country": "us",
            "language": "en"
        }
    },
    "widget": {
        "items": [
            {
                "entity": "content",
                "rfk_id": "rfkid_6",
                "search": {
                    "content": {},
                    "query": {
                        "keyphrase": "clou"
                    },
                    "suggestion": [
                        {
                            "name": "keyword_suggester"
                        }
                    ]
                }
            }
        ]
    }
}'

次のことがわかります。

  • suggestionオブジェクトに渡す値は、Searchで設定されたsuggestion blockおよび管理者のAPI名です。

  • rfk_idに渡す値は、Searchのデフォルトのpreview searchウィジェットのIDです。

この要求に対する応答の例を次に示します。

{
    "widgets": [
        {
            "rfk_id": "rfkid_7",
            "type": "content_grid",
            "entity": "content",
            "suggestion": {
                "keyword_suggester": [
                    {
                        "text": "cloud faq",
                        "freq": 14
                    },
                    {
                        "text": "cloud addendum",
                        "freq": 3
                    },
                    {
                        "text": "cloud portal",
                        "freq": 3
                    }
                    ...
                ]
            },
            "total_item": 0,
            "limit": 10,
            "offset": 0
        }
    ],
    "dt": 13,
    "ts": 1680632333374
}

応答を使用してこの検索エクスペリエンスを作成するには:

  1. 提案を表示するには、応答のwidgets.suggestion.name_suggestor配列を参照してください。この配列には提案のリストがあり、それぞれにtextとfreqが付いています。

  2. preview searchウィジェットに1つの提案を表示するには、textの値 .

freqキーの値は、この要求に関連するコンテンツ コレクションのその部分にフレーズが表示される頻度を示します。たとえば、cloud faqは、このクエリに関連する検索結果のプールに14回表示されます。

キーワードに基づいて検索結果ページを作成する

訪問者が候補をクリックすると、キーワードに基づいて変更された検索結果ページが表示されます。

キーワードに基づいて検索結果ページを作成するには:

この例では、訪問者は提案cloud portalをクリックします。

キーワードに基づいて検索結果ページを表示するためのデータを取得するリクエストのサンプルを次に示します。

{
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        },
        "user": {
            "uuid": "43533744-1y-6i-4j-1p-nn0if7kfzq8kw3am4i17-1664982959269"
        }
    },
    "widget": {
        "items": [
            {
                "entity": "content",
                "rfk_id": "rfkid_7",
                "search": {
                    "content": {},
                    "facet": {
                        "all": true,
                        "max": 100
                    },
                    "query": {
                        "keyphrase": "cloud portal"
                    }
                }
            }
        ]
    }
}

ファセット値でフィルター処理された検索結果ページを作成する

訪問者がファセット値を選択して結果をフィルタリングすると、そのファセット値に従ってフィルタリングされた結果が表示されます。

ファセット値でフィルター処理された検索結果ページを作成するには"

この例では、訪問者はTypeファセットでBlogsを選択します。

ファセット値でフィルター処理された検索結果ページを表示するためのデータを取得するサンプル要求facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiRGlzY292ZXIifQ次に示します。

手記

facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiRGlzY292ZXIifQは、Blogsファセット値のIDです。この値は、前の要求への応答、Create a search results page based on a keyword、またはfacetsを要求する任意の要求から取得できます。

{
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        },
        "user": {
            "uuid": "43533744-1y-6i-4j-1p-nn0if7kfzq8kw3am4i17-1664982959269"
        }
    },
    "widget": {
        "items": [
            {
                "entity": "content",
                "rfk_id": "rfkid_7",
                "search": {
                    "content": {},
                    "suggestion": [
                        {
                            "name": "title_context_aware"
                        }
                    ],
                    "facet": {
                        "all": true,
                        "max": 100,
                        "types": [
                            {
                                "name": "type",
                                "filter": {
                                    "values": [
                                        "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiRGlzY292ZXIifQ=="
                                    ],
                                    "type": "or"
                                }
                            }
                        ]
                    },
                    "query": {
                        "keyphrase": "cloud portal"
                    }
                }
            }
        ]
    }
}

並べ替えを適用した検索結果ページを作成する

訪問者がタイトルの降順で結果を並べ替えると、並べ替えられた順序で検索結果が表示されます。

並べ替えを適用した検索結果ページを作成するには:

  • Create a search results page filtered by a facet valueに送信した以前の要求を変更して、ソートオブジェクトを追加します。

この例では、訪問者はタイトルの降順で並べ替えます。

コンテンツ タイトルの降順で並べ替えられた検索結果ページを表示するためのデータを取得するためのサンプル要求を次に示します。

{
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        },
        "user": {
            "uuid": "43533744-1y-6i-4j-1p-nn0if7kfzq8kw3am4i17-1664982959269"
        }
    },
    "widget": {
        "items": [
            {
                "entity": "content",
                "rfk_id": "rfkid_7",
                "search": {
                    "content": {},
                    "facet": {
                        "all": true,
                        "max": 100,
                        "types": [
                            {
                                "name": "type",
                                "filter": {
                                    "values": [
                                        "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiRGlzY292ZXIifQ=="
                                    ],
                                    "type": "or"
                                }
                            }
                        ]
                    },
                    "query": {
                        "keyphrase": "cloud portal"
                    },
                    "sort": {
                        "choices": true,
                        "value": [
                            {
                                "order": "asc",
                                "name": "desc_name"
                            }
                        ]
                    }
                }
            }
        ]
    }
}

sortオブジェクトで、管理者が並べ替えを構成するときに作成した並べ替えオプションのAPI名を渡します。ここでは、desc_nameという並べ替えオプションを使用します。

訪問者をコンテンツページにリダイレクトする

訪問者はコンテンツを並べ替えた後、content itemをクリックします。これを処理するには、訪問者がcontent item内の任意の場所をクリックしたときに、content itemのURLへのリダイレクトを作成します。

SearchするSendイベント

訪問者がウィジェットをクリックしたり、ログインしたり、記事に賛成票を投じたりしてページを操作したら、それらの操作を追跡し、イベントAPIを使用してSitecore Searchに送信する必要があります。

Sitecore Searchは、イベントを使用してサイト全体の訪問者データを追跡します。このデータは、検索ランキング、分析の生成、検索結果とrecommendationsのパーソナライズに使用されます。イベントREST APIを使用してイベントを送信できます。

このチュートリアルでは、訪問者が実行するアクションごとに次の イベント を送信します。

訪問者のアクション

送信するイベント

検索結果ページにアクセスし、content itemsとfacetsを表示する

viewwidget

viewentity_page

検索バーにキーワードを入力すると、preview searchウィジェットで候補が表示されます

viewwidget

候補Clickをクリックすると、新しい結果を含む検索結果ページが表示されます

clickwidget

リクエストでは、action_causeの値としてsuggestionを渡します。

viewwidget

結果をフィルタリングするファセット値を選択します

viewwidget

clickwidget

リクエストでは、action_causeの値としてfilterを渡します。

コンテンツタイトルの降順で結果を並べ替える

viewwidget

Click a content itemをクリックし、そのコンテンツのページに移動します。

clickwidget。

リクエストでは、action_causeの値としてentityを渡します。

viewentity_page

この記事を改善するための提案がある場合は、 お知らせください!