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

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

カタログ情報の管理

このページでは、Retail API にカタログをインポートした後に商品情報を管理する方法について説明します。カタログ内の商品の読み取り、書き込み、削除を行うことができます。

商品情報が変更されたときにカタログを最新に保つには、初回と同じ方法でカタログをインポートします。カタログのインポートについては、カタログの情報のインポートをご覧ください。

商品のアップロード

curl

products.create REST メソッドを使用して、単一の商品アイテムを作成します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
      "title": "PRODUCT_TITLE",
      "categories": "Shoes & Accessories > Shoes"
    }' \
    "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products?productID=PRODUCT_ID"

リクエストが成功すると、以下の例のように商品オブジェクトが返されます。

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID",
  "id": "PRODUCT_ID",
  "primaryProductId": "PRODUCT_ID",
  "type": "PRIMARY",
  "categories": [
    "Shoes & Accessories \u003e Shoes"
  ],
  "title": "product title",
  "availability": "IN_STOCK"
}

Java

public static Product createProduct(Product productToCreate, String productId)
    throws IOException {
  return getProductServiceClient().createProduct(
      DEFAULT_BRANCH_NAME, productToCreate, productId
  );
}

商品情報の更新

商品カタログの変更に合わせて、新しい商品、価格、在庫状況などの商品の変更をリアルタイムでアップロードすることでカタログを更新できます。追加または変更された商品だけをアップロードできます。カタログ全体を再読み込みする必要はありません。

curl

products.patch メソッドを使用して、商品情報を更新します。

次の例では、特定の商品のタイトルを更新します。

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
       "title": "new-title-value"
    }" \
    "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID?updateMask=title"

リクエストが成功すると、以下の例のように商品オブジェクトが返されます。

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID",
  "id": "PRODUCT_ID",
  "primaryProductId": "PRODUCT_ID",
  "type": "PRIMARY",
  "categories": [
    "Shoes & Accessories > Shoes"
  ],
  "title": "new product title",
  "availability": "IN_STOCK"
}

Java

public static Product updateProduct(Product productToUpdate) throws IOException {
  return getProductServiceClient().updateProduct(productToUpdate, FieldMask.getDefaultInstance());
}

商品情報の削除

Retail API にはカタログから商品を削除する方法がありますが、削除された商品に関連するユーザー イベントを記録する場合、Retail API でユーザーを適切に処理できず、削除される可能性があることに注意してください。さらに、履歴カタログ データを含めると、モデルの品質が向上します。これはレコメンデーションや検索結果の向上に不可欠です。

古い商品の availability は、削除するのではなく OUT_OF_STOCK に設定する必要があります。

curl

delete メソッドを使用して商品を削除し、PRODUCT_ID を、削除する商品の ID に置き換えます。

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID"

Java

public static void deleteProduct(String productName) throws IOException {
  getProductServiceClient().deleteProduct(productName);
}

商品アイテムの取得

curl

GET リクエストを products エンドポイントに送信して商品アイテムを取得し、PRODUCT_ID を、取得する商品の ID に置き換えます。

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"  \
    "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID"

出力は次のようになります。

{
    "name": "projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID"
    "id": "PRODUCT_ID",
    "primaryProductId": "PRODUCT_ID",
    "type": "PRIMARY",
    "categories": [
      "Shoes & Accessories \u003e Shoes"
    ],
    "title": "product title",
    "availability": "IN_STOCK"
}

Java

public static Product getProduct(String productName) throws IOException {
  return getProductServiceClient().getProduct(productName);
}

カタログに関する集計情報の表示

[Retail Data] ページの [Catalog] タブで、カタログの集計情報を表示して、アップロードされた商品アイテムをプレビューできます。

カタログ イベントの再結合

カタログ イベントを再結合するには、POST リクエストを userEvents:rejoin エンドポイントに送信します。

Retail AI 管理者 IAM ロールが必要です。

curl

再結合するイベントの種類に応じて userEventRejoinScope を設定します。

  • USER_EVENT_REJOIN_SCOPE_UNSPECIFIED: デフォルト。結合イベントと結合されていないイベントの両方の再結合をトリガーします。
  • JOINED_EVENTS: 結合されたイベントにのみ再結合をトリガーします。
  • UNJOINED_EVENTS: 結合されていないイベントにのみ再結合をトリガーします。

次の例は、結合されていないイベントのみの再結合をトリガーします。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
     'userEventRejoinScope': 'UNJOINED_EVENTS'
     }" \
    "https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/userEvents:rejoin"

次のようなレスポンス オブジェクトが返されます。

{
  "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/OPERATION_ID"
}

再結合のステータスを確認できます。OPERATION_ID を、再結合メソッドによって返されたオペレーション ID に置き換えます。

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

オペレーションが完了すると、オペレーションのステータスは done として返されます。

{
  "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/OPERATION_ID",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2.RejoinUserEventsResponse",
    "rejoinedUserEventsCount": "1"
  }
}

Java

public static String rejoinUserEvents(UserEventRejoinScope scope)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  RejoinUserEventsRequest request = RejoinUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setUserEventRejoinScope(scope)
      .build();

  String operationName = userEventsClient
      .rejoinUserEventsAsync(request).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

商品タイプの変更

商品をインポートする場合は、商品のタイプ(プライマリ、バリアント、コレクション)を指定できます。アイテムのタイプが変更された場合や、タイプが誤って指定された場合は、アイテムを削除し、作成して、指定したタイプで更新する必要があります。

商品のタイプは、TYPE_UNSPECIFIEDPRIMARYVARIANT、または COLLECTION に設定できます。詳しくは、リファレンス ドキュメントの [product.Type][product-type] をご覧ください。

商品レベルの構成の変更

Merchant Center でカタログをインポートするときは、商品がプライマリかバリアントかを指定する必要があります。商品レベルが変更された場合や、正しく指定されていなかった場合は、次の手順に沿って構成を修正します。Retail 管理者 IAM ロールが必要です。

  1. 商品レベルを再構成している間にインポートが発生していないことを確認してください。これにより、間違ったレベルでデータがアップロードされることがなくなります。

  2. すべての商品アイテムを削除します。詳細については、products.delete をご覧ください。 次のステップに進む前に、カタログを完全に空にする必要があります。

  3. 商品を再インポートして、商品レベルの構成を変更します。

    この手順は、インポート方法によって異なります。カタログ情報のインポートの適切な手順に従って、商品レベルを新しい構成に設定します。

  4. カタログ情報のインポートで選択した手順を使用して、変更したレベル構成の新しいカタログのインポートを終了します。

  5. 既存のモデルをすべて調整します。

    モデルを調整するには、[Models] ページに移動し、モデル名をクリックして詳細ページを表示して、ボタンバーの [Manual Tune] をクリックします。

    [Retail Models] ページに移動

    調整の費用の詳細については、料金をご覧ください。