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

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

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

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

おすすめの方法

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

ドキュメントの変更

Retail コンソールに切り替えた後は、この Retail ドキュメント（https://cloud.google.com/retail/docs）のみを使用することをおすすめします。

Recommendations Engine API のベータ版ドキュメント セットは引き続き利用できますが、更新は行われません。

コンソールの変更

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

Retail Google Cloud コンソール は 2022 年 1 月 20 日から公開されています。レコメンデーション コンソールを使用している場合は、推奨事項プロジェクトを Retail コンソールにアクセスすることをおすすめします。

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

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

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

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

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

サービス提供構成は、Retail API を使用して Recommendations 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 の権限が削除されました。