これは、Recommendations AI、Retail Search、新しい Retail コンソールに関するドキュメントです。制限付き一般提供フェーズで Retail Search を使用するには、Cloud 営業担当者にお問い合わせください

Recommendations AI のみを使用している場合は、Recommendations コンソールを引き続き使用し、Recommendations AI のドキュメントをご覧ください。

オートコンプリート データのインポート

オートコンプリートは、ユーザーが入力した語句の残りを予測する機能であり、ユーザーの検索エクスペリエンスが向上します。提供されたデータセットまたは提供されたユーザー イベントに基づいて、先行入力候補を提供できます。

このページでは、オートコンプリート データセットを Retail にインポートする方法について説明します。ここでは、独自のオートコンプリート データをアップロードする手順を示します。オートコンプリート データセットを常に使用する予定の場合は、データを最新の状態に保ちます。オートコンプリートの取得について詳しくは、CompletionService.CompleteQuery をご覧ください。オートコンプリート データは Retail Search でのみ使用されます。このデータは Recommendations AI では使用されません。

始める前に

オートコンプリート情報を読み込むには、事前に始める前にの手順、特にプロジェクトの設定サービス アカウントの作成ローカル環境へのサービス アカウントの追加を完了しておく必要があります。

インポートを行うには、Retail 管理者の IAM ロールが必要です。

オートコンプリートのインポートに関するベスト プラクティス

オートコンプリート データをインポートするときは、次のベスト プラクティスを実施するようにしてください。

  • 次のセクションのリストにあるスキーマ ファイルと API ドキュメントを確認する。

    ダミーやプレースホルダの値は使用しないでください。

  • できるだけ多くのフィールドを指定します。

  • 独自のアップロード済みデータセットを使用する場合は、独自のオートコンプリート データセットを最新の状態に保ちます。

オートコンプリート データをインポートする

BigQuery からオートコンプリート データをインポートする

オートコンプリート データを BigQuery から正しい形式でインポートするには、Retail オートコンプリート スキーマを使用して正しい形式で BigQuery テーブルを作成し、オートコンプリート データでテーブルの読み込みを行います。次に、データを Retail にアップロードします。

BigQuery テーブルの詳細については、テーブルの概要をご覧ください。BigQuery クエリについては、BigQuery データのクエリの概要をご覧ください。

BigQuery へデータを入力する

Retail オートコンプリート スキーマを使用して、オートコンプリート データを BigQuery にアップロードします。

BigQuery は、このスキーマを使用して、JSON 形式のデータに正しいフィールド名と型(STRINGINTEGERRECORD など)があるかどうかを確認できます。ただし、次のような判定の確認を行うことはできません。

  • 文字列フィールドが認識可能な列挙値にマッピングされているかどうか
  • 文字列フィールドが正しい形式を使用しているかどうか
  • 整数フィールドまたは浮動小数点フィールドに有効な範囲内の値があるかどうか
  • 欠落しているフィールドが必須フィールドであるかどうか

データの品質とエンドユーザーの検索エクスペリエンスを確保するために、値と形式に関する詳細について、スキーマとリファレンスのドキュメントを参照してください。

オートコンプリート データを Retail にインポートする

curl

  1. BigQuery データセットが別のプロジェクトにある場合、Retail が BigQuery データセットにアクセスできるように、必要な権限を構成します。詳細

  2. インポートの入力パラメータのデータファイルを作成します。入力パラメータ値は、Cloud Storage または BigQuery のどちらからインポートするかによって異なります。

    BigQuery データセットを指定するには、BigQuerySource オブジェクトを使用します。

    • dataset-id: BigQuery データセットの ID。
    • table-id: データを保持する BigQuery テーブルの ID。
    • data-schema: dataSchema プロパティには、suggestions(デフォルト)、allowlistdenylist の値を使用します。Retail オートコンプリート スキーマを使用します。
    {
      "inputConfig":{
        "bigQuerySource": {
          "datasetId":"dataset-id",
          "tableId":"table-id",
          "dataSchema":"data-schema"
        }
      }
    }
    
  3. CompletionData:import REST メソッドに POST リクエストを行い、データファイルの名前(この例ではinput.json)を指定して、オート コンプリート情報を Retail にインポートします。

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" -d @./input.json
    "https://retail.googleapis.com/v2alpha/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/completionData:import"
    

    API を使用して、プログラムでステータスを確認できます。次のようなレスポンス オブジェクトが返されます。

    {
      "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/123456",
      "done": false
    }
    

    名前の項目は、オペレーション オブジェクトの ID です。このオブジェクトのステータスをリクエストするには、done 項目が true として返されるまで、名前の項目を import メソッドで返される値に置き換えます。

    curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://retail.googleapis.com/v2alpha/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/123456"
    

    オペレーションが完了すると、返されたオブジェクトは truedone 値を持ち、次の例のような Status オブジェクトが含まれます。

    {
      "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportMetadata",
        "createTime": "2020-01-01T03:33:33.000001Z",
        "updateTime": "2020-01-01T03:34:33.000001Z",
        "successCount": "2",
        "failureCount": "1"
      },
      "done": true
      "response": {
        "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportCompletionDataResponse",
      }
    }
    

BigQuery データセットへのアクセス権の設定

BigQuery データセットが Retail サービスとは異なるプロジェクトにある場合にアクセスを設定するには、次の手順を行います。

  1. Cloud Console で IAM ページを開きます。

    [IAM] ページを開く

  2. Retail プロジェクトを選択します。

  3. Retail サービス アカウントという名前のサービス アカウントを探します。

    以前に Retail でインポート オペレーションを開始していない場合、このサービス アカウントは表示されない可能性があります。このサービス アカウントが表示されない場合は、インポート タスクに戻ってインポートを開始します。権限エラーで失敗した場合は、ここに戻ってこのタスクを完了してください。

  4. メールアドレスのようなサービス アカウントの ID(例: cloud-retail-customer-data-access@system.gserviceaccount.com)をコピーします。

  5. [IAM と管理] で [追加] をクリックします。

  6. Retail サービス アカウントの ID を入力し、[BigQuery] > [BigQuery データ閲覧者] のロールを選択します。

    プロジェクト全体でデータ閲覧者のロールを指定したくない場合は、このロールをデータセットに直接追加できます。詳細

  7. [保存] をクリックします。

オートコンプリート データの形式

JSON ファイルは次の例のようになります。改行は読みやすくするためのものです。提案全体を 1 行で入力する必要があります。 各提案は 1 行に 1 つずつ記述します。

候補の最低限の必須項目は、次のとおりです。

{
  "suggestion": "ABC",
  "globalScore": "0.5"
}

または

{
  "suggestion": "ABC",
  "frequency": "100"
}

オートコンプリート データのインポート期間

BigQuery から 1 つのインポートを行うには通常約 10 時間かかります。この長時間実行オペレーションにより、本番環境のサービスにデータセットが push されます。データセットのインポート準備ができると、オペレーション オブジェクトdone フィールドが true とマークされます。オペレーションが done になる前は、インポート データセットからの最新候補の取得が保証されません。

オートコンプリート データセットを最新の状態に保つ

独自のアップロード済みデータセットを使用する場合は、アップロード済みデータセットを、定期的に最新の状態に保つことをおすすめします。

一括更新

インポート メソッドを使用すると、オートコンプリートを一括更新できます。これは最初のインポートと同じ方法で行います。オートコンプリート データのインポートの手順に従います。これにより、インポートされたデータセット全体が置き換えられます。

インポート状態のモニタリング

独自のデータセットを最新の状態に保つことは、使用時に高品質の提案結果を得るうえで重要です。インポートのエラー率をモニタリングし、必要に応じて対処してください。

Retail のオートコンプリート スキーマ

オートコンプリートのデータセットを BigQuery からインポートする場合は、以下の Retail スキーマを使用して、正しい形式で BigQuery テーブルを作成し、オートコンプリート データを含むテーブルを読み込みます。

提案のスキーマ

このデータセットは、予測入力による候補のフレーズに使用されます。

拒否リストのスキーマ

このデータセットは、フレーズを提案しないように拒否リストとして使用します。

許可リストのスキーマ

このデータセットは、この許可リストに含まれているフレーズの後処理(スペル修正など)をスキップするために使用されます。