これは、Recommendations AI、Retail Search、新しい Retail コンソールに関するドキュメントです。

ベータ版から Retail API に移行する

Recommendations AI で Retail API を使用することになりました。このページでは、v1beta1 バージョンの Recommendations Engine API(サービス エンドポイント https://recommendationengine.googleapis.com)から、一般提供された Retail API(サービス エンドポイント https://retail.googleapis.com)に移行する際の変更内容と移行のベスト プラクティスについて説明します。

Recommendations Engine API とそのドキュメント セットは引き続き使用できますが、更新はされません。

このドキュメントは、Recommendations AI の使用をベータ版のときに開始した方のみを対象としています。

おすすめの方法

  • 移行を完了する前に、検証専用トラフィックを送信します。
  • トラフィックを段階的に移行するほうが、すべてを一度に移行する場合よりも優れています。可能であれば、トラフィックを v1beta1 から v2 に段階的に移行します。
  • 複数のリージョンでサービスを実行している場合は、グローバルのサービス停止を避けるため、リージョンを 1 つずつ移行することをおすすめします。

ドキュメントの変更

このドキュメント セットは、一般提供版の Retail API 用です。

Recommendations Engine API 用のベータ版ドキュメント セットとそのドキュメント セットは引き続き使用できますが、更新はされません。次のベータ版ドキュメントをご覧ください。

コンソールの変更

Retail コンソールはレコメンデーション コンソールに置き換わるものです。

Retail Cloud コンソール は 2022 年 1 月 20 日から公開されています。Recommendations コンソールを使用している場合は、Retail コンソールから Recommendations AI プロジェクトにアクセスすることをおすすめします。

Recommendations コンソールと比較した Retail コンソールの機能と用語の変更については、Retail コンソールへの移行をご覧ください。

サービス提供構成とプレースメント

Retail API は、Recommendations Engine API で使用されるプレースメントのコンセプトに代わるサービス提供構成を提供します。

サービス提供構成は、Retail API を使用して Recommendations AI v2 と Retail Search v2alpha の時点で利用できます。

servingConfig リソースは、Retail API バージョン v2beta と v2alpha で使用できます。このリソースを使用して、サービス提供構成を作成、表示、編集、削除できます。

既存のプレースメントがある場合や新しいプレースメントを作成する場合、Retail API は各プレースメントに関連付けられたサービス提供構成を自動的に作成します。サービス提供構成を作成しても、対応するプレースメントは作成されません。

サービス提供構成を削除すると、対応するプレースメントが削除されます。プレースメントを削除すると、対応するサービス提供構成が削除されます。

サービス提供構成を使用すると、多様性オプションと価格の再ランキング オプションを編集して、ほぼリアルタイムで有効にできます。プレースメントを使用する場合、多様性と料金の設定はプレースメントが指すレコメンデーション モデルからのみ変更できます。

プレースメントは引き続きサポートされますが、代わりにサービス提供構成を使用することをおすすめします。

サービス提供構成の使用の詳細については、サービス提供構成サービス提供構成の作成をご覧ください。

REST と RPC のパス

REST と RPC のパスには、多くの変更が行われています。Retail API の API ドキュメントを必ず確認し、Retail API を正しく呼び出していることを確認してください。

すべてのパスで recommendationengine.googleapis.com ではなく retail.googleapis.com を使用するようになりました。

次に例を示します。

v1beta1 Recommendations Engine API:

GET https://recommendationengine.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/OPERATION_ID

v2 Retail API:

GET https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/OPERATION_ID

一部のリソースとメソッドの名前が変更されたか、削除されたか、新しく追加されました。以下のテーブルは、v1beta1 と v2 のリソースおよびそれらに関連するメソッドを並べて比較しています。

たとえば、v1beta1 リソース catalogs.catalogItems は v2 リソース catalogs.branches.products と同等です。v1beta1 の catalogs.catalogItems で利用可能であった list メソッドは、v2 の catalogs.branches.products では使用できないため、「削除済み」と示されています。

v1beta1 リソースへのリンクは、v1beta1 の API ドキュメントに移動することに留意してください。

v1beta1 リソース メソッド v2 リソース メソッド
catalogs list catalogs list
patch patch
該当なし catalogs.branches.operations get
catalogs.catalogItems create catalogs.branches.products create
delete delete
get get
import import
list 削除済み
patch patch
catalogs.operations get catalogs.operations get
list list
catalogs.eventStores.operations get 削除済み
list
catalogs.eventStores.placements predict catalogs.placements predict
catalogs.eventStores.predictionApiKeyRegistrations create 削除済み
delete
list
catalogs.eventStores.userEvents collect catalogs.userEvents collect
import import
list 削除済み
purge purge
rejoin rejoin
write write
該当なし operations get
list

IAM の変更

Retail Identity and Access Management(IAM)のロールと権限に以下の変更が行われました。

  • Retail は、Recommendations Engine v1beta1 で使用されていた automlrecommendations 名前空間ではなく、retail 名前空間の IAM ロールと権限を使用します。
  • ロールAdmin Viewer を削除しました。
  • predict メソッドはこの後独自の API キーを必要としないため、apiKeys の権限が削除されました。

カタログとユーザー イベントのスキーマ

カタログとユーザー イベントのスキーマが Retail API で変更されました。