この Recommendations AI ドキュメントでは、Recommendations コンソールについて説明します。Retail コンソールに切り替え、Retail ドキュメントを使用することをおすすめします。このドキュメントでは、Recommendations AI、Retail コンソール、Retail Search について説明しています。

Recommendations AI の v1beta バージョンを使用している場合は、Retail API バージョンに移行してください。

始める前に

このページでは、Recommendations AI を使用する前に行う必要のある手順の概要を説明します。

プロジェクトを設定する

Recommendations AI にアクセスするには、Google Cloud プロジェクトを作成する必要があります。プロジェクトを設定する手順は次のとおりです。

Cloud Console の [リソースの管理] ページに移動します。

[リソースの管理] ページに移動
ページの上部にあるプルダウンから、プロジェクトを作成する組織を選択します。
[プロジェクトを作成] をクリックします。
表示される [新しいプロジェクト] ウィンドウで、プロジェクト名を入力し、該当する請求先アカウントを選択します。
プロジェクトをフォルダに追加する場合は、[場所] ボックスに該当するフォルダ名を入力します。
新しいプロジェクトの詳細を入力し終えたら、[作成] をクリックします。

ディスカバリサービスのデータ使用条件に同意する

ディスカバリサービスのデータ使用条件が 2022 年 4 月 4 日より前に適用されるように、Google Cloud プロジェクトで Recommendations AI を有効にした場合、そのプロジェクトで Recommendations AI を引き続き使用するには、使用条件に同意する必要があります。

プロジェクトの Discovery Services データ使用条件に同意するには、次の手順を行います。

Recommendations AI ダッシュボードに移動します。

Recommendations AI ダッシュボード
Cloud Console の上部にあるバナーの [条件に移動] をクリックします。
[データ使用条件] ページで、データ使用条件を確認し、同意する場合は [同意する] をクリックします。

重要: プロジェクトの Retail 管理者またはオーナーのロールを持っている場合にのみ、データ使用条件に同意できます。

アプリケーションの認証の設定

Retail API にアクセスするには、次の認証メソッドの両方を設定する必要があります。

サービスアカウント - アプリケーションでサービスアカウントを使用して Product への呼び出しを認証します。
API キー - アプリケーションでユーザーイベントロギング API の呼び出しに API キーを使用します。

サービスアカウントを作成する

Cloud Console の [認証情報] ページに移動します。
認証情報を作成する対象のプロジェクトを選択します（プロジェクトがすでに選択されている場合もあります）。
[認証情報を作成] をクリックして、[サービスアカウントキー] を選択します。

次のフィールドに値を入力します。

項目	値
サービスアカウント	新しいサービスアカウント
サービスアカウント名	`enter a name for your service account`
役割	サービスアカウント > サービスアカウントトークン作成者 Recommendations AI > Recommendations AI 編集者
キーのタイプ	JSON

[作成] をクリックして、サービスアカウントを作成します。

新しいサービスアカウントの公開鍵/秘密鍵を含む JSON ファイルがパソコンに自動でダウンロードされます。この JSON ファイルは、サービスアカウント用の唯一のキーのコピーです。必ず安全な場所に保管してください。JSON キーファイルは、アプリケーションがアクセスできる場所に保存する必要があります（サービスアカウント（OAuth 2.0）で認証するの your-service-account-json-key-file をご覧ください）。

サービスアカウントをローカル環境に追加する

cURL コマンドラインツールを使用して Retail API を呼び出す場合は、ローカル環境でサービスアカウントを使用できるようにする必要があります。cURL は、gcloud auth application-default print-access-token コマンドで Google Cloud Cloud SDK を使用してサービスアカウントのアクセストークンを取得します。SDK をダウンロードしてインストールするには、Cloud SDK をご覧ください。 Cloud Shell を使用している場合、SDK はすでにインストールされています。

コマンドウィンドウを閉じると、GOOGLE_APPLICATION_CREDENTIALS 環境変数は維持されません。新しいコマンドウィンドウを開くときに、変数がサービスアカウントファイルへのパスに設定されていることを確認するには、初期化シェルスクリプトで値を設定します。

  export GOOGLE_APPLICATION_CREDENTIALS=path-to-service-account-json-key-file

API キーを作成する

Cloud Console の [認証情報] ページに移動します。
Google Cloud Console ページの上部にあるプロジェクトのプルダウンで、プロジェクトを選択します（プロジェクトがすでに選択されている可能性もあります）。
[認証情報を作成] をクリックして [API キー] を選択します。リファラー制限を追加しないでください。一部のユーザーのプライバシー設定は、参照 URL を渡さないことがわかっています。
- 生成された API キーをメモします。このキーは、ユーザーイベントロギングを呼び出すときに使用します。
セキュリティを強化するには、API キーに HTTP 制限を追加して、https://retail.googleapis.com/* での Retail サービスへのアクセスを制限します。

例

サービスアカウントを使用する認証（OAuth 2.0）

サービスアカウントを使用した OAuth 2.0 認証の Java の例を以下に示します。詳細な手順については、認証のドキュメントをご覧ください。Google には 7 言語のクライアントライブラリがあり、これを使用してアプリケーションに OAuth2 認証を実装できます。HTTP/REST を直接実装する場合は、REST 認証の手順に従ってください。

この例では、your-service-account-json-key-file をサービスアカウントの JSON キーファイルのパスに置き換えます。

// Simple Java example of using Google Cloud OAuth client library.
//
// Please see here for the list of libraries in different languages:
// https://developers.google.com/identity/protocols/OAuth2#libraries
//
// The following example depends on the google api client library.
//
// Maven:
//    <dependency>
//      <groupId>com.google.api-client</groupId>
//      <artifactId>google-api-client</artifactId>
//      <version>1.22.0</version>
//    </dependency>
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpResponse;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.GenericJson;
import com.google.api.client.json.jackson2.JacksonFactory;
import java.io.FileInputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

public class RetailApiSample {
  public static final String CREATE_PRODUCT_URL =
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products";

  public static GoogleCredential authorize() throws Exception {
    return GoogleCredential.fromStream(new FileInputStream("your-service-account-json-key-file"))
        .createScoped(Collections.singleton("https://www.googleapis.com/auth/cloud-platform"))
        .setExpirationTimeMilliseconds(new Long(3600 * 1000));;
  }

  // Build an example product.
  public static GenericJson getProduct() {
    GenericJson categories = new GenericJson()
        .set("categories", Arrays.asList("Electronics > Computers", "Laptops"));
    GenericJson priceInfo = new GenericJson
        .set("currency_code", "USD")
        .set("price", 800.00)
        .set("original_price", 1000.00);

    return new GenericJson()
        .set("name", "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/[ProductName]")
        .set("title", "Sample Laptop")
        .set("description", "Indisputably the most fantastic laptop ever created.")
        .set("categories", categories)
        .set("price_info", priceInfo)
        .set("availability", "IN_STOCK")
        .set("available_quantity", 1219);
  }

  public static void main(String[] args) {
    try {
      GoogleCredential credential = RetailApiSample.authorize();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      HttpRequestFactory requestFactory = httpTransport.createRequestFactory();
      HttpRequest request = requestFactory.buildPostRequest(new GenericUrl(CREATE_PRODUCT_URL),
          new JsonHttpContent(new JacksonFactory(), RetailApiSample.getProduct()));
      credential.initialize(request);
      HttpResponse response = request.execute();
      System.out.println("Response content: " + response.parseAsString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

API キーを使用する認証

次は、コマンドラインから curl コマンドを実行して API キーによる認証を行う例です。api-key は、前のセクションで作成した API キーに置き換えます。

URL="https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:write?key=api-key"

DATA='{
  "user_attributes": {
    ...
  },
  "user_event_detail": {
    ...
  }
}'

echo $URL
curl -H 'Content-Type: application/json' -X POST -d "${DATA}"  $URL