このページは Cloud Translation API によって翻訳されました。

レコメンデーションを表示する

このページでは、Google Cloud コンソールを使用してレコメンデーションをプレビューし、API を使用してレコメンデーションの結果を取得する方法について説明します。レコメンデーションをアプリに統合するのに役立つ API 呼び出しの例については、[REST] タブをご覧ください。

使用する手順は、必要なレコメンデーションのタイプと、レコメンデーションアプリが接続されているデータストアのタイプによって異なります。

メディアレコメンデーションを取得する
構造化データを含むアプリの汎用レコメンデーションを取得する
非構造化データを含むアプリの汎用レコメンデーションを取得する
ウェブサイトデータを含むアプリの汎用レコメンデーションを取得する

メディアレコメンデーションを取得する

Console

Google Cloud コンソールを使用してメディアレコメンデーションをプレビューする手順は次のとおりです。

Google Cloud コンソールで、[Agent Builder] ページに移動します。

Agent Builder
レコメンデーションをプレビューするアプリの名前をクリックします。
[構成] > [トレーニング] をクリックします。[クエリの準備ができました] が [OK] の場合、アプリはプレビューの準備が整っています。
[プレビュー] をクリックします。
[ドキュメント ID] フィールドをクリックします。ドキュメント ID のリストが表示されます。
レコメンデーションの対象となるドキュメントのドキュメント ID をクリックします。または、ドキュメント ID を [ドキュメント ID] フィールドに入力します。
[サービス提供構成を選択] をクリックし、プレビューするサービス提供構成を選択します。
省略可: ユーザーイベントを収集したユーザーの訪問者 ID（疑似ユーザー ID）を入力します。このフィールドを空白のままにするか、存在しない訪問者 ID を入力すると、新規ユーザーとしてレコメンデーションをプレビューします。
[レコメンデーションを表示] をクリックします。おすすめのドキュメントのリストが表示されます。
ドキュメントをクリックすると、ドキュメントの詳細が表示されます。

REST

API を使用してメディアレコメンデーションを取得するには、servingConfigs.recommend メソッドを使用します。

エンジン ID とサービス提供構成 ID を確認します。エンジン ID とサービス提供構成 ID がすでにある場合は、ステップ 2 に進みます。
1. Google Cloud コンソールで、[Agent Builder] ページに移動します。
  
  Agent Builder
2. アプリの名前をクリックします。
3. ナビゲーションパネルで [構成] をクリックします。
4. アプリの作成時に自動的に作成されたサービス提供構成のみがある場合、サービス提供構成 ID とエンジン ID は同じです。次のステップに進みます。
  
  [サービス提供構成] タブに複数のサービス提供構成が表示されている場合は、レコメンデーションを取得するサービス提供構成を見つけます。サービス提供構成 ID は、[ID] 列の値です。
  
  アプリの作成時に自動的に作成されたサービス提供構成を削除し、現在手動で作成したサービス提供構成が 1 つしかない場合は、[プレビュー] ページに移動し、[サービス提供構成を選択] をクリックしてサービス提供構成 ID を表示します。
5. トレーニング タブをクリックします。エンジン ID は、[アプリ ID] 行の値です。
アプリがプレビューの準備ができていることを確認します。
1. Google Cloud コンソールで、[Agent Builder] ページに移動します。
  
  Agent Builder
2. アプリの名前をクリックします。
3. [構成] > [トレーニング] をクリックします。[クエリの準備ができました] が OK の場合、アプリはプレビューの準備が整っています。
レコメンデーションを取得します。

注: レコメンデーションがまだアクティブでない場合、またはメソッド呼び出しをテストするには、validateOnly フラグを true に設定してこのメソッドを呼び出すことができます。この呼び出しはプレースホルダの結果を返します。また、料金は発生しません。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d  '{
        "validateOnly": false,
        "userEvent": {
            "eventType": "view-item",
            "userPseudoId": "USER_PSEUDO_ID",
            "documents": [{
              "id": "DOCUMENT_ID"
            }],
        "filter": "FILTER_STRING"            }
    }' \
  "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/SERVING_CONFIG_ID:recommend"
```
- PROJECT_ID: プロジェクトの ID。
- DATA_STORE_ID: データストアの ID。
- DOCUMENT_ID: レコメンデーションをプレビューするドキュメントの ID。データを取り込む際にこのドキュメントに使用した ID を使用します。
- USER_PSEUDO_ID: ユーザーの仮名化 ID。このフィールドには HTTP Cookie を使用できます。これにより、1 つのデバイス上の訪問者を一意に識別できます。このフィールドを複数のユーザーに対して同じ ID に設定しないでください。そうすると、イベント履歴が統合され、モデルの品質が低下します。このフィールドには個人を特定できる情報（PII）を含めないでください。
- SERVING_CONFIG_ID: サービス提供構成の ID。
- FILTER: 省略可。フィルタ式の構文を使用して、指定したフィールドセットでフィルタリングできるテキストフィールド。デフォルト値は空の文字列です。つまり、フィルタは適用されません。詳細については、レコメンデーションをフィルタリングするをご覧ください。

次のような結果が表示されます。

{
  "results": [{"id": "sample-id-1"}, {"id": "sample-id-2"}],
  "attributionToken": "abc123"
}

各検索レスポンスとレコメンデーションに含まれるアトリビューショントークンは、ユーザーがそれらの検索レスポンスとレコメンデーションに応じて行ったアクションに関連付けることをおすすめします。これにより、検索レスポンスとレコメンデーションの品質が向上します。これを行うには、検索レスポンスやレコメンデーションとしてウェブサイトに表示するリンクの URL に attributionToken 値を追加します（例: https://www.example.com/54321/?rtoken=abc123）。ユーザーがこれらのリンクのいずれかをクリックすると、記録するユーザーイベントに attributionToken 値を含めます。

構造化データを含むアプリの汎用レコメンデーションを取得する

Console

Google Cloud コンソールを使用して構造化アプリの汎用レコメンデーションをプレビューする手順は次のとおりです。

Google Cloud コンソールで、[Agent Builder] ページに移動します。

Agent Builder
レコメンデーションをプレビューするアプリの名前をクリックします。
[プレビュー] をクリックします。
[ドキュメント ID] フィールドをクリックします。ドキュメント ID のリストが表示されます。
レコメンデーションの対象となるドキュメントのドキュメント ID をクリックします。または、ドキュメント ID を [ドキュメント ID] フィールドに入力します。
[レコメンデーションを表示] をクリックします。おすすめのドキュメントのリストが表示されます。
ドキュメントをクリックすると、ドキュメントの詳細が表示されます。

REST

API を使用して、構造化データを含むアプリの汎用レコメンデーションを取得するには、servingConfigs.recommend メソッドを使用します。

エンジン ID を確認します。エンジン ID がすでにある場合は、ステップ 2 に進みます。
1. Google Cloud コンソールで、[Agent Builder] ページに移動します。
  
  Agent Builder
2. アプリの名前をクリックします。
3. Google Cloud コンソールの URL からエンジン ID を取得します。engines/ と /data の間にあるテキストです。たとえば、URL に
```
gen-app-builder/engines/demo_1234567890123/data/records
```
  エンジン ID は demo_1234567890123 です。
データストア ID を確認します。データストア ID がすでにある場合は、次のステップに進みます。
1. Google Cloud コンソールで [Agent Builder] ページに移動し、ナビゲーションメニューで [データストア] をクリックします。
  
  [データストア] ページに移動
2. データストアの名前をクリックします。
3. データストアの [データ] ページで、データストア ID を取得します。
"servingState":"ACTIVE" が返されるまで GetEngine メソッドをポーリングして、エンジンがプレビューの準備ができていることを確認します。この時点で、エンジンはプレビューの準備が整います。
```
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/ENGINE_ID
```
- PROJECT_ID: プロジェクトの ID。
- ENGINE_ID: エンジンの ID。
レコメンデーションを取得します。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
  "userEvent": { "eventType":"view-item", "userPseudoId":"USER_PSEUDO_ID", "documents":[{"id":"DOCUMENT_ID"}]}}' \
  "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/SERVING_CONFIG_ID:recommend"
```
- PROJECT_ID: プロジェクトの ID。
- DATA_STORE_ID: データストアの ID。
- DOCUMENT_ID: レコメンデーションをプレビューするドキュメントの ID。データを取り込む際にこのドキュメントに使用した ID を使用します。
- USER_PSEUDO_ID: ユーザーの仮名化 ID。このフィールドには HTTP Cookie を使用できます。これにより、1 つのデバイス上の訪問者を一意に識別できます。このフィールドを複数のユーザーに対して同じ ID に設定しないでください。そうすると、イベント履歴が統合され、モデルの品質が低下します。このフィールドには個人を特定できる情報（PII）を含めないでください。
- SERVING_CONFIG_ID: サービス提供構成の ID。サービス提供構成 ID はエンジン ID と同じであるため、ここではエンジン ID を使用します。

C#

詳細については、Vertex AI Agent Builder C# API のリファレンスドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

using Google.Cloud.DiscoveryEngine.V1Beta;
using Google.Protobuf.WellKnownTypes;

public sealed partial class GeneratedRecommendationServiceClientSnippets
{
    /// <summary>Snippet for Recommend</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void RecommendRequestObject()
    {
        // Create client
        RecommendationServiceClient recommendationServiceClient = RecommendationServiceClient.Create();
        // Initialize request argument(s)
        RecommendRequest request = new RecommendRequest
        {
            ServingConfigAsServingConfigName = ServingConfigName.FromProjectLocationDataStoreServingConfig("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]"),
            UserEvent = new UserEvent(),
            PageSize = 0,
            Filter = "",
            ValidateOnly = false,
            Params = { { "", new Value() }, },
            UserLabels = { { "", "" }, },
        };
        // Make the request
        RecommendResponse response = recommendationServiceClient.Recommend(request);
    }
}

Go

詳細については、Vertex AI Agent Builder Go API のリファレンスドキュメントをご覧ください。


package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1beta"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewRecommendationClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.RecommendRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb#RecommendRequest.
	}
	resp, err := c.Recommend(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

詳細については、Vertex AI Agent Builder Java API のリファレンスドキュメントをご覧ください。

import com.google.cloud.discoveryengine.v1beta.RecommendRequest;
import com.google.cloud.discoveryengine.v1beta.RecommendResponse;
import com.google.cloud.discoveryengine.v1beta.RecommendationServiceClient;
import com.google.cloud.discoveryengine.v1beta.ServingConfigName;
import com.google.cloud.discoveryengine.v1beta.UserEvent;
import com.google.protobuf.Value;
import java.util.HashMap;

public class SyncRecommend {

  public static void main(String[] args) throws Exception {
    syncRecommend();
  }

  public static void syncRecommend() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (RecommendationServiceClient recommendationServiceClient =
        RecommendationServiceClient.create()) {
      RecommendRequest request =
          RecommendRequest.newBuilder()
              .setServingConfig(
                  ServingConfigName.ofProjectLocationDataStoreServingConfigName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]")
                      .toString())
              .setUserEvent(UserEvent.newBuilder().build())
              .setPageSize(883849137)
              .setFilter("filter-1274492040")
              .setValidateOnly(true)
              .putAllParams(new HashMap<String, Value>())
              .putAllUserLabels(new HashMap<String, String>())
              .build();
      RecommendResponse response = recommendationServiceClient.recommend(request);
    }
  }
}

Node.js

詳細については、Vertex AI Agent Builder Node.js API のリファレンスドキュメントをご覧ください。

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Full resource name of a
 *  ServingConfig google.cloud.discoveryengine.v1beta.ServingConfig:
 *  `projects/* /locations/global/collections/* /engines/* /servingConfigs/*`, or
 *  `projects/* /locations/global/collections/* /dataStores/* /servingConfigs/*`
 *  One default serving config is created along with your recommendation engine
 *  creation. The engine ID is used as the ID of the default serving
 *  config. For example, for Engine
 *  `projects/* /locations/global/collections/* /engines/my-engine`, you can use
 *  `projects/* /locations/global/collections/* /engines/my-engine/servingConfigs/my-engine`
 *  for your
 *  RecommendationService.Recommend google.cloud.discoveryengine.v1beta.RecommendationService.Recommend 
 *  requests.
 */
// const servingConfig = 'abc123'
/**
 *  Required. Context about the user, what they are looking at and what action
 *  they took to trigger the Recommend request. Note that this user event
 *  detail won't be ingested to userEvent logs. Thus, a separate userEvent
 *  write request is required for event logging.
 *  Don't set
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id 
 *  or
 *  UserEvent.user_info.user_id google.cloud.discoveryengine.v1beta.UserInfo.user_id 
 *  to the same fixed ID for different users. If you are trying to receive
 *  non-personalized recommendations (not recommended; this can negatively
 *  impact model performance), instead set
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id 
 *  to a random unique ID and leave
 *  UserEvent.user_info.user_id google.cloud.discoveryengine.v1beta.UserInfo.user_id 
 *  unset.
 */
// const userEvent = {}
/**
 *  Maximum number of results to return. Set this property
 *  to the number of recommendation results needed. If zero, the service
 *  chooses a reasonable default. The maximum allowed value is 100. Values
 *  above 100 are set to 100.
 */
// const pageSize = 1234
/**
 *  Filter for restricting recommendation results with a length limit of 5,000
 *  characters. Currently, only filter expressions on the `filter_tags`
 *  attribute is supported.
 *  Examples:
 *   * `(filter_tags: ANY("Red", "Blue") OR filter_tags: ANY("Hot", "Cold"))`
 *   * `(filter_tags: ANY("Red", "Blue")) AND NOT (filter_tags: ANY("Green"))`
 *  If `attributeFilteringSyntax` is set to true under the `params` field, then
 *  attribute-based expressions are expected instead of the above described
 *  tag-based syntax. Examples:
 *   * (launguage: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
 *   * (available: true) AND
 *     (launguage: ANY("en", "es")) OR (categories: ANY("Movie"))
 *  If your filter blocks all results, the API returns generic
 *  (unfiltered) popular Documents. If you only want results strictly matching
 *  the filters, set `strictFiltering` to `true` in
 *  RecommendRequest.params google.cloud.discoveryengine.v1beta.RecommendRequest.params 
 *  to receive empty results instead.
 *  Note that the API never returns
 *  Document google.cloud.discoveryengine.v1beta.Document s with
 *  `storageStatus` as `EXPIRED` or `DELETED` regardless of filter choices.
 */
// const filter = 'abc123'
/**
 *  Use validate only mode for this recommendation query. If set to `true`, a
 *  fake model is used that returns arbitrary Document IDs.
 *  Note that the validate only mode should only be used for testing the API,
 *  or if the model is not ready.
 */
// const validateOnly = true
/**
 *  Additional domain specific parameters for the recommendations.
 *  Allowed values:
 *  * `returnDocument`: Boolean. If set to `true`, the associated Document
 *     object is returned in
 *     RecommendResponse.RecommendationResult.document google.cloud.discoveryengine.v1beta.RecommendResponse.RecommendationResult.document.
 *  * `returnScore`: Boolean. If set to true, the recommendation score
 *     corresponding to each returned Document is set in
 *     RecommendResponse.RecommendationResult.metadata google.cloud.discoveryengine.v1beta.RecommendResponse.RecommendationResult.metadata.
 *     The given score indicates the probability of a Document conversion given
 *     the user's context and history.
 *  * `strictFiltering`: Boolean. True by default. If set to `false`, the
 *  service
 *     returns generic (unfiltered) popular Documents instead of empty if
 *     your filter blocks all recommendation results.
 *  * `diversityLevel`: String. Default empty. If set to be non-empty, then
 *     it needs to be one of:
 *      *  `no-diversity`
 *      *  `low-diversity`
 *      *  `medium-diversity`
 *      *  `high-diversity`
 *      *  `auto-diversity`
 *     This gives request-level control and adjusts recommendation results
 *     based on Document category.
 *  * `attributeFilteringSyntax`: Boolean. False by default. If set to true,
 *     the `filter` field is interpreted according to the new,
 *     attribute-based syntax.
 */
// const params = [1,2,3,4]
/**
 *  The user labels applied to a resource must meet the following requirements:
 *  * Each resource can have multiple labels, up to a maximum of 64.
 *  * Each label must be a key-value pair.
 *  * Keys have a minimum length of 1 character and a maximum length of 63
 *    characters and cannot be empty. Values can be empty and have a maximum
 *    length of 63 characters.
 *  * Keys and values can contain only lowercase letters, numeric characters,
 *    underscores, and dashes. All characters must use UTF-8 encoding, and
 *    international characters are allowed.
 *  * The key portion of a label must be unique. However, you can use the same
 *    key with multiple resources.
 *  * Keys must start with a lowercase letter or international character.
 *  See Requirements for
 *  labels (https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements)
 *  for more details.
 */
// const userLabels = [1,2,3,4]

// Imports the Discoveryengine library
const {RecommendationServiceClient} = require('@google-cloud/discoveryengine').v1beta;

// Instantiates a client
const discoveryengineClient = new RecommendationServiceClient();

async function callRecommend() {
  // Construct request
  const request = {
    servingConfig,
    userEvent,
  };

  // Run request
  const response = await discoveryengineClient.recommend(request);
  console.log(response);
}

callRecommend();

PHP

詳細については、Vertex AI Agent Builder PHP API のリファレンスドキュメントをご覧ください。

use Google\ApiCore\ApiException;
use Google\Cloud\DiscoveryEngine\V1beta\Client\RecommendationServiceClient;
use Google\Cloud\DiscoveryEngine\V1beta\RecommendRequest;
use Google\Cloud\DiscoveryEngine\V1beta\RecommendResponse;
use Google\Cloud\DiscoveryEngine\V1beta\UserEvent;

/**
 * Makes a recommendation, which requires a contextual user event.
 *
 * @param string $formattedServingConfig Full resource name of a
 *                                       [ServingConfig][google.cloud.discoveryengine.v1beta.ServingConfig]:
 *                                       `projects/&#42;/locations/global/collections/&#42;/engines/&#42;/servingConfigs/*`, or
 *                                       `projects/&#42;/locations/global/collections/&#42;/dataStores/&#42;/servingConfigs/*`
 *
 *                                       One default serving config is created along with your recommendation engine
 *                                       creation. The engine ID is used as the ID of the default serving
 *                                       config. For example, for Engine
 *                                       `projects/&#42;/locations/global/collections/&#42;/engines/my-engine`, you can use
 *                                       `projects/&#42;/locations/global/collections/&#42;/engines/my-engine/servingConfigs/my-engine`
 *                                       for your
 *                                       [RecommendationService.Recommend][google.cloud.discoveryengine.v1beta.RecommendationService.Recommend]
 *                                       requests. Please see
 *                                       {@see RecommendationServiceClient::servingConfigName()} for help formatting this field.
 * @param string $userEventEventType     User event type. Allowed values are:
 *
 *                                       Generic values:
 *
 *                                       * `search`: Search for Documents.
 *                                       * `view-item`: Detailed page view of a Document.
 *                                       * `view-item-list`: View of a panel or ordered list of Documents.
 *                                       * `view-home-page`: View of the home page.
 *                                       * `view-category-page`: View of a category page, e.g. Home > Men > Jeans
 *
 *                                       Retail-related values:
 *
 *                                       * `add-to-cart`: Add an item(s) to cart, e.g. in Retail online shopping
 *                                       * `purchase`: Purchase an item(s)
 *
 *                                       Media-related values:
 *
 *                                       * `media-play`: Start/resume watching a video, playing a song, etc.
 *                                       * `media-complete`: Finished or stopped midway through a video, song, etc.
 * @param string $userEventUserPseudoId  A unique identifier for tracking visitors.
 *
 *                                       For example, this could be implemented with an HTTP cookie, which should be
 *                                       able to uniquely identify a visitor on a single device. This unique
 *                                       identifier should not change if the visitor log in/out of the website.
 *
 *                                       Do not set the field to the same fixed ID for different users. This mixes
 *                                       the event history of those users together, which results in degraded model
 *                                       quality.
 *
 *                                       The field must be a UTF-8 encoded string with a length limit of 128
 *                                       characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
 *
 *                                       The field should not contain PII or user-data. We recommend to use Google
 *                                       Analytics [Client
 *                                       ID](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#clientId)
 *                                       for this field.
 */
function recommend_sample(
    string $formattedServingConfig,
    string $userEventEventType,
    string $userEventUserPseudoId
): void {
    // Create a client.
    $recommendationServiceClient = new RecommendationServiceClient();

    // Prepare the request message.
    $userEvent = (new UserEvent())
        ->setEventType($userEventEventType)
        ->setUserPseudoId($userEventUserPseudoId);
    $request = (new RecommendRequest())
        ->setServingConfig($formattedServingConfig)
        ->setUserEvent($userEvent);

    // Call the API and handle any network failures.
    try {
        /** @var RecommendResponse $response */
        $response = $recommendationServiceClient->recommend($request);
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $formattedServingConfig = RecommendationServiceClient::servingConfigName(
        '[PROJECT]',
        '[LOCATION]',
        '[DATA_STORE]',
        '[SERVING_CONFIG]'
    );
    $userEventEventType = '[EVENT_TYPE]';
    $userEventUserPseudoId = '[USER_PSEUDO_ID]';

    recommend_sample($formattedServingConfig, $userEventEventType, $userEventUserPseudoId);
}

Python

詳細については、Vertex AI Agent Builder Python API のリファレンスドキュメントをご覧ください。

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1beta


def sample_recommend():
    # Create a client
    client = discoveryengine_v1beta.RecommendationServiceClient()

    # Initialize request argument(s)
    user_event = discoveryengine_v1beta.UserEvent()
    user_event.event_type = "event_type_value"
    user_event.user_pseudo_id = "user_pseudo_id_value"

    request = discoveryengine_v1beta.RecommendRequest(
        serving_config="serving_config_value",
        user_event=user_event,
    )

    # Make the request
    response = client.recommend(request=request)

    # Handle the response
    print(response)

Ruby

詳細については、Vertex AI Agent Builder Ruby API のリファレンスドキュメントをご覧ください。

require "google/cloud/discovery_engine/v1beta"

##
# Snippet for the recommend call in the RecommendationService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client#recommend.
#
def recommend
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1beta::RecommendRequest.new

  # Call the recommend method.
  result = client.recommend request

  # The returned object is of type Google::Cloud::DiscoveryEngine::V1beta::RecommendResponse.
  p result
end

非構造化データを含むアプリの汎用レコメンデーションを取得する

Console

Google Cloud コンソールを使用して汎用レコメンデーションをプレビューする手順は次のとおりです。

Google Cloud コンソールで、[Agent Builder] ページに移動します。

Agent Builder
レコメンデーションをプレビューするアプリの名前をクリックします。
[プレビュー] をクリックします。
[URI] フィールドをクリックします。URI のリストが表示されます。
レコメンデーションの対象となるドキュメントの URI をクリックします。または、[URI] フィールドに URI を入力します。
[レコメンデーションを表示] をクリックします。推奨ドキュメントの URI のリストが表示されます。
URI をクリックしてドキュメントを表示します。

REST

API を使用して、非構造化データを含むアプリの汎用レコメンデーションを取得する手順は次のとおりです。

エンジン ID を確認します。エンジン ID がすでにある場合は、ステップ 2 に進みます。
1. Google Cloud コンソールで、[Agent Builder] ページに移動します。
  
  Agent Builder
2. アプリの名前をクリックします。
3. Google Cloud コンソールの URL からエンジン ID を取得します。engines/ と /data の間にあるテキストです。たとえば、URL に
```
gen-app-builder/engines/demo_1234567890123/data/records
```
  エンジン ID は demo_1234567890123 です。
データストア ID を確認します。データストア ID がすでにある場合は、次のステップに進みます。
1. Google Cloud コンソールで [Agent Builder] ページに移動し、ナビゲーションメニューで [データストア] をクリックします。
  
  [データストア] ページに移動
2. データストアの名前をクリックします。
3. データストアの [データ] ページで、データストア ID を取得します。
"servingState":"ACTIVE" が返されるまで GetEngine メソッドをポーリングして、エンジンがプレビューの準備ができていることを確認します。この時点で、エンジンはプレビューの準備が整います。
```
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/ENGINE_ID
```
- PROJECT_ID: プロジェクトの ID。
- ENGINE_ID: エンジンの ID。
レコメンデーションを取得します。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
  "userEvent": { "eventType":"view-item", "userPseudoId":"USER_PSEUDO_ID", "documents":[{"id":"DOCUMENT_ID"}]}}' \
  "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/SERVING_CONFIG_ID:recommend"
```
- PROJECT_ID: プロジェクトの ID。
- DATA_STORE_ID: エンジンに関連付けられたデータストアの ID。
- DOCUMENT_ID: レコメンデーションをプレビューするドキュメントの ID。データを取り込む際に指定したドキュメント ID を使用します。
- USER_PSEUDO_ID: ユーザーの仮名化 ID。このフィールドには HTTP Cookie を使用できます。これにより、1 つのデバイス上の訪問者を一意に識別できます。このフィールドを複数のユーザーに対して同じ ID に設定しないでください。そうすると、イベント履歴が統合され、モデルの品質が低下します。このフィールドには個人を特定できる情報（PII）を含めないでください。
- SERVING_CONFIG_ID: サービス提供構成の ID。サービス提供構成 ID はエンジン ID と同じであるため、ここではエンジン ID を使用します。

C#

詳細については、Vertex AI Agent Builder C# API のリファレンスドキュメントをご覧ください。

using Google.Cloud.DiscoveryEngine.V1Beta;
using Google.Protobuf.WellKnownTypes;

public sealed partial class GeneratedRecommendationServiceClientSnippets
{
    /// <summary>Snippet for Recommend</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void RecommendRequestObject()
    {
        // Create client
        RecommendationServiceClient recommendationServiceClient = RecommendationServiceClient.Create();
        // Initialize request argument(s)
        RecommendRequest request = new RecommendRequest
        {
            ServingConfigAsServingConfigName = ServingConfigName.FromProjectLocationDataStoreServingConfig("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]"),
            UserEvent = new UserEvent(),
            PageSize = 0,
            Filter = "",
            ValidateOnly = false,
            Params = { { "", new Value() }, },
            UserLabels = { { "", "" }, },
        };
        // Make the request
        RecommendResponse response = recommendationServiceClient.Recommend(request);
    }
}

Go

詳細については、Vertex AI Agent Builder Go API のリファレンスドキュメントをご覧ください。


package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1beta"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewRecommendationClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.RecommendRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb#RecommendRequest.
	}
	resp, err := c.Recommend(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

詳細については、Vertex AI Agent Builder Java API のリファレンスドキュメントをご覧ください。

import com.google.cloud.discoveryengine.v1beta.RecommendRequest;
import com.google.cloud.discoveryengine.v1beta.RecommendResponse;
import com.google.cloud.discoveryengine.v1beta.RecommendationServiceClient;
import com.google.cloud.discoveryengine.v1beta.ServingConfigName;
import com.google.cloud.discoveryengine.v1beta.UserEvent;
import com.google.protobuf.Value;
import java.util.HashMap;

public class SyncRecommend {

  public static void main(String[] args) throws Exception {
    syncRecommend();
  }

  public static void syncRecommend() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (RecommendationServiceClient recommendationServiceClient =
        RecommendationServiceClient.create()) {
      RecommendRequest request =
          RecommendRequest.newBuilder()
              .setServingConfig(
                  ServingConfigName.ofProjectLocationDataStoreServingConfigName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]")
                      .toString())
              .setUserEvent(UserEvent.newBuilder().build())
              .setPageSize(883849137)
              .setFilter("filter-1274492040")
              .setValidateOnly(true)
              .putAllParams(new HashMap<String, Value>())
              .putAllUserLabels(new HashMap<String, String>())
              .build();
      RecommendResponse response = recommendationServiceClient.recommend(request);
    }
  }
}

Node.js

詳細については、Vertex AI Agent Builder Node.js API のリファレンスドキュメントをご覧ください。

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Full resource name of a
 *  ServingConfig google.cloud.discoveryengine.v1beta.ServingConfig:
 *  `projects/* /locations/global/collections/* /engines/* /servingConfigs/*`, or
 *  `projects/* /locations/global/collections/* /dataStores/* /servingConfigs/*`
 *  One default serving config is created along with your recommendation engine
 *  creation. The engine ID is used as the ID of the default serving
 *  config. For example, for Engine
 *  `projects/* /locations/global/collections/* /engines/my-engine`, you can use
 *  `projects/* /locations/global/collections/* /engines/my-engine/servingConfigs/my-engine`
 *  for your
 *  RecommendationService.Recommend google.cloud.discoveryengine.v1beta.RecommendationService.Recommend 
 *  requests.
 */
// const servingConfig = 'abc123'
/**
 *  Required. Context about the user, what they are looking at and what action
 *  they took to trigger the Recommend request. Note that this user event
 *  detail won't be ingested to userEvent logs. Thus, a separate userEvent
 *  write request is required for event logging.
 *  Don't set
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id 
 *  or
 *  UserEvent.user_info.user_id google.cloud.discoveryengine.v1beta.UserInfo.user_id 
 *  to the same fixed ID for different users. If you are trying to receive
 *  non-personalized recommendations (not recommended; this can negatively
 *  impact model performance), instead set
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id 
 *  to a random unique ID and leave
 *  UserEvent.user_info.user_id google.cloud.discoveryengine.v1beta.UserInfo.user_id 
 *  unset.
 */
// const userEvent = {}
/**
 *  Maximum number of results to return. Set this property
 *  to the number of recommendation results needed. If zero, the service
 *  chooses a reasonable default. The maximum allowed value is 100. Values
 *  above 100 are set to 100.
 */
// const pageSize = 1234
/**
 *  Filter for restricting recommendation results with a length limit of 5,000
 *  characters. Currently, only filter expressions on the `filter_tags`
 *  attribute is supported.
 *  Examples:
 *   * `(filter_tags: ANY("Red", "Blue") OR filter_tags: ANY("Hot", "Cold"))`
 *   * `(filter_tags: ANY("Red", "Blue")) AND NOT (filter_tags: ANY("Green"))`
 *  If `attributeFilteringSyntax` is set to true under the `params` field, then
 *  attribute-based expressions are expected instead of the above described
 *  tag-based syntax. Examples:
 *   * (launguage: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
 *   * (available: true) AND
 *     (launguage: ANY("en", "es")) OR (categories: ANY("Movie"))
 *  If your filter blocks all results, the API returns generic
 *  (unfiltered) popular Documents. If you only want results strictly matching
 *  the filters, set `strictFiltering` to `true` in
 *  RecommendRequest.params google.cloud.discoveryengine.v1beta.RecommendRequest.params 
 *  to receive empty results instead.
 *  Note that the API never returns
 *  Document google.cloud.discoveryengine.v1beta.Document s with
 *  `storageStatus` as `EXPIRED` or `DELETED` regardless of filter choices.
 */
// const filter = 'abc123'
/**
 *  Use validate only mode for this recommendation query. If set to `true`, a
 *  fake model is used that returns arbitrary Document IDs.
 *  Note that the validate only mode should only be used for testing the API,
 *  or if the model is not ready.
 */
// const validateOnly = true
/**
 *  Additional domain specific parameters for the recommendations.
 *  Allowed values:
 *  * `returnDocument`: Boolean. If set to `true`, the associated Document
 *     object is returned in
 *     RecommendResponse.RecommendationResult.document google.cloud.discoveryengine.v1beta.RecommendResponse.RecommendationResult.document.
 *  * `returnScore`: Boolean. If set to true, the recommendation score
 *     corresponding to each returned Document is set in
 *     RecommendResponse.RecommendationResult.metadata google.cloud.discoveryengine.v1beta.RecommendResponse.RecommendationResult.metadata.
 *     The given score indicates the probability of a Document conversion given
 *     the user's context and history.
 *  * `strictFiltering`: Boolean. True by default. If set to `false`, the
 *  service
 *     returns generic (unfiltered) popular Documents instead of empty if
 *     your filter blocks all recommendation results.
 *  * `diversityLevel`: String. Default empty. If set to be non-empty, then
 *     it needs to be one of:
 *      *  `no-diversity`
 *      *  `low-diversity`
 *      *  `medium-diversity`
 *      *  `high-diversity`
 *      *  `auto-diversity`
 *     This gives request-level control and adjusts recommendation results
 *     based on Document category.
 *  * `attributeFilteringSyntax`: Boolean. False by default. If set to true,
 *     the `filter` field is interpreted according to the new,
 *     attribute-based syntax.
 */
// const params = [1,2,3,4]
/**
 *  The user labels applied to a resource must meet the following requirements:
 *  * Each resource can have multiple labels, up to a maximum of 64.
 *  * Each label must be a key-value pair.
 *  * Keys have a minimum length of 1 character and a maximum length of 63
 *    characters and cannot be empty. Values can be empty and have a maximum
 *    length of 63 characters.
 *  * Keys and values can contain only lowercase letters, numeric characters,
 *    underscores, and dashes. All characters must use UTF-8 encoding, and
 *    international characters are allowed.
 *  * The key portion of a label must be unique. However, you can use the same
 *    key with multiple resources.
 *  * Keys must start with a lowercase letter or international character.
 *  See Requirements for
 *  labels (https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements)
 *  for more details.
 */
// const userLabels = [1,2,3,4]

// Imports the Discoveryengine library
const {RecommendationServiceClient} = require('@google-cloud/discoveryengine').v1beta;

// Instantiates a client
const discoveryengineClient = new RecommendationServiceClient();

async function callRecommend() {
  // Construct request
  const request = {
    servingConfig,
    userEvent,
  };

  // Run request
  const response = await discoveryengineClient.recommend(request);
  console.log(response);
}

callRecommend();

PHP

詳細については、Vertex AI Agent Builder PHP API のリファレンスドキュメントをご覧ください。

use Google\ApiCore\ApiException;
use Google\Cloud\DiscoveryEngine\V1beta\Client\RecommendationServiceClient;
use Google\Cloud\DiscoveryEngine\V1beta\RecommendRequest;
use Google\Cloud\DiscoveryEngine\V1beta\RecommendResponse;
use Google\Cloud\DiscoveryEngine\V1beta\UserEvent;

/**
 * Makes a recommendation, which requires a contextual user event.
 *
 * @param string $formattedServingConfig Full resource name of a
 *                                       [ServingConfig][google.cloud.discoveryengine.v1beta.ServingConfig]:
 *                                       `projects/&#42;/locations/global/collections/&#42;/engines/&#42;/servingConfigs/*`, or
 *                                       `projects/&#42;/locations/global/collections/&#42;/dataStores/&#42;/servingConfigs/*`
 *
 *                                       One default serving config is created along with your recommendation engine
 *                                       creation. The engine ID is used as the ID of the default serving
 *                                       config. For example, for Engine
 *                                       `projects/&#42;/locations/global/collections/&#42;/engines/my-engine`, you can use
 *                                       `projects/&#42;/locations/global/collections/&#42;/engines/my-engine/servingConfigs/my-engine`
 *                                       for your
 *                                       [RecommendationService.Recommend][google.cloud.discoveryengine.v1beta.RecommendationService.Recommend]
 *                                       requests. Please see
 *                                       {@see RecommendationServiceClient::servingConfigName()} for help formatting this field.
 * @param string $userEventEventType     User event type. Allowed values are:
 *
 *                                       Generic values:
 *
 *                                       * `search`: Search for Documents.
 *                                       * `view-item`: Detailed page view of a Document.
 *                                       * `view-item-list`: View of a panel or ordered list of Documents.
 *                                       * `view-home-page`: View of the home page.
 *                                       * `view-category-page`: View of a category page, e.g. Home > Men > Jeans
 *
 *                                       Retail-related values:
 *
 *                                       * `add-to-cart`: Add an item(s) to cart, e.g. in Retail online shopping
 *                                       * `purchase`: Purchase an item(s)
 *
 *                                       Media-related values:
 *
 *                                       * `media-play`: Start/resume watching a video, playing a song, etc.
 *                                       * `media-complete`: Finished or stopped midway through a video, song, etc.
 * @param string $userEventUserPseudoId  A unique identifier for tracking visitors.
 *
 *                                       For example, this could be implemented with an HTTP cookie, which should be
 *                                       able to uniquely identify a visitor on a single device. This unique
 *                                       identifier should not change if the visitor log in/out of the website.
 *
 *                                       Do not set the field to the same fixed ID for different users. This mixes
 *                                       the event history of those users together, which results in degraded model
 *                                       quality.
 *
 *                                       The field must be a UTF-8 encoded string with a length limit of 128
 *                                       characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
 *
 *                                       The field should not contain PII or user-data. We recommend to use Google
 *                                       Analytics [Client
 *                                       ID](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#clientId)
 *                                       for this field.
 */
function recommend_sample(
    string $formattedServingConfig,
    string $userEventEventType,
    string $userEventUserPseudoId
): void {
    // Create a client.
    $recommendationServiceClient = new RecommendationServiceClient();

    // Prepare the request message.
    $userEvent = (new UserEvent())
        ->setEventType($userEventEventType)
        ->setUserPseudoId($userEventUserPseudoId);
    $request = (new RecommendRequest())
        ->setServingConfig($formattedServingConfig)
        ->setUserEvent($userEvent);

    // Call the API and handle any network failures.
    try {
        /** @var RecommendResponse $response */
        $response = $recommendationServiceClient->recommend($request);
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $formattedServingConfig = RecommendationServiceClient::servingConfigName(
        '[PROJECT]',
        '[LOCATION]',
        '[DATA_STORE]',
        '[SERVING_CONFIG]'
    );
    $userEventEventType = '[EVENT_TYPE]';
    $userEventUserPseudoId = '[USER_PSEUDO_ID]';

    recommend_sample($formattedServingConfig, $userEventEventType, $userEventUserPseudoId);
}

Python

詳細については、Vertex AI Agent Builder Python API のリファレンスドキュメントをご覧ください。

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1beta


def sample_recommend():
    # Create a client
    client = discoveryengine_v1beta.RecommendationServiceClient()

    # Initialize request argument(s)
    user_event = discoveryengine_v1beta.UserEvent()
    user_event.event_type = "event_type_value"
    user_event.user_pseudo_id = "user_pseudo_id_value"

    request = discoveryengine_v1beta.RecommendRequest(
        serving_config="serving_config_value",
        user_event=user_event,
    )

    # Make the request
    response = client.recommend(request=request)

    # Handle the response
    print(response)

Ruby

詳細については、Vertex AI Agent Builder Ruby API のリファレンスドキュメントをご覧ください。

require "google/cloud/discovery_engine/v1beta"

##
# Snippet for the recommend call in the RecommendationService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client#recommend.
#
def recommend
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1beta::RecommendRequest.new

  # Call the recommend method.
  result = client.recommend request

  # The returned object is of type Google::Cloud::DiscoveryEngine::V1beta::RecommendResponse.
  p result
end

ウェブサイトデータを含むアプリの汎用レコメンデーションを取得する

Console

Google Cloud コンソールを使用してウェブサイトアプリの汎用レコメンデーションをプレビューする手順は次のとおりです。

Google Cloud コンソールで、[Agent Builder] ページに移動します。

Agent Builder
レコメンデーションをプレビューするアプリの名前をクリックします。
ナビゲーションメニューで [プレビュー] をクリックします。
[URI] フィールドをクリックします。ウェブサイトの URL のリストが表示されます。
おすすめを表示するウェブページの URL をクリックします。または、[URL] フィールドにウェブサイトの URL を入力します。
[レコメンデーションを表示] をクリックします。おすすめのウェブページの URL リストが表示されます。
URL をクリックすると、ウェブページが表示されます。

REST

API を使用して、ウェブサイトデータを含むアプリの汎用レコメンデーションを取得するには、servingConfigs.recommend メソッドを使用します。

エンジン ID を確認します。エンジン ID がすでにある場合は、ステップ 2 に進みます。
1. Google Cloud コンソールで、[Agent Builder] ページに移動します。
  
  Agent Builder
2. アプリの名前をクリックします。
3. Google Cloud コンソールの URL からエンジン ID を取得します。engines/ と /data の間にあるテキストです。たとえば、URL に
```
gen-app-builder/engines/demo_1234567890123/data/records
```
  エンジン ID は demo_1234567890123 です。
データストア ID を確認します。データストア ID がすでにある場合は、次のステップに進みます。
1. Google Cloud コンソールで [Agent Builder] ページに移動し、ナビゲーションメニューで [データストア] をクリックします。
  
  [データストア] ページに移動
2. データストアの名前をクリックします。
3. データストアの [データ] ページで、データストア ID を取得します。
"servingState":"ACTIVE" が返されるまで GetEngine メソッドをポーリングして、エンジンがプレビューの準備ができていることを確認します。この時点で、エンジンはプレビューの準備が整います。
```
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/ENGINE_ID
```
- PROJECT_ID: プロジェクトの ID。
- ENGINE_ID: エンジンの ID。
レコメンデーションを取得します。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
  "userEvent": { "eventType":"view-item", "userPseudoId":"USER_PSEUDO_ID", "documents":[{"uri":"WEBSITE_URL"}]}}' \
  "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/SERVING_CONFIG_ID:recommend"
```
- PROJECT_ID: プロジェクトの ID。
- DATA_STORE_ID: データストアの ID。
- WEBSITE_URL: レコメンデーションをプレビューするウェブサイトの URL。
- USER_PSEUDO_ID: ユーザーの仮名化 ID。このフィールドには HTTP Cookie を使用できます。これにより、1 つのデバイス上の訪問者を一意に識別できます。このフィールドを複数のユーザーに対して同じ ID に設定しないでください。イベント履歴が統合され、モデルの品質が低下します。このフィールドには、個人を特定できる情報（PII）は含めないでください。
- SERVING_CONFIG_ID: サービス提供構成の ID。サービス提供構成 ID はエンジン ID と同じであるため、ここではエンジン ID を使用します。

C#

詳細については、Vertex AI Agent Builder C# API のリファレンスドキュメントをご覧ください。

using Google.Cloud.DiscoveryEngine.V1Beta;
using Google.Protobuf.WellKnownTypes;

public sealed partial class GeneratedRecommendationServiceClientSnippets
{
    /// <summary>Snippet for Recommend</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void RecommendRequestObject()
    {
        // Create client
        RecommendationServiceClient recommendationServiceClient = RecommendationServiceClient.Create();
        // Initialize request argument(s)
        RecommendRequest request = new RecommendRequest
        {
            ServingConfigAsServingConfigName = ServingConfigName.FromProjectLocationDataStoreServingConfig("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]"),
            UserEvent = new UserEvent(),
            PageSize = 0,
            Filter = "",
            ValidateOnly = false,
            Params = { { "", new Value() }, },
            UserLabels = { { "", "" }, },
        };
        // Make the request
        RecommendResponse response = recommendationServiceClient.Recommend(request);
    }
}

Go

詳細については、Vertex AI Agent Builder Go API のリファレンスドキュメントをご覧ください。


package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1beta"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewRecommendationClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.RecommendRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb#RecommendRequest.
	}
	resp, err := c.Recommend(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

詳細については、Vertex AI Agent Builder Java API のリファレンスドキュメントをご覧ください。

import com.google.cloud.discoveryengine.v1beta.RecommendRequest;
import com.google.cloud.discoveryengine.v1beta.RecommendResponse;
import com.google.cloud.discoveryengine.v1beta.RecommendationServiceClient;
import com.google.cloud.discoveryengine.v1beta.ServingConfigName;
import com.google.cloud.discoveryengine.v1beta.UserEvent;
import com.google.protobuf.Value;
import java.util.HashMap;

public class SyncRecommend {

  public static void main(String[] args) throws Exception {
    syncRecommend();
  }

  public static void syncRecommend() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (RecommendationServiceClient recommendationServiceClient =
        RecommendationServiceClient.create()) {
      RecommendRequest request =
          RecommendRequest.newBuilder()
              .setServingConfig(
                  ServingConfigName.ofProjectLocationDataStoreServingConfigName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]")
                      .toString())
              .setUserEvent(UserEvent.newBuilder().build())
              .setPageSize(883849137)
              .setFilter("filter-1274492040")
              .setValidateOnly(true)
              .putAllParams(new HashMap<String, Value>())
              .putAllUserLabels(new HashMap<String, String>())
              .build();
      RecommendResponse response = recommendationServiceClient.recommend(request);
    }
  }
}

Node.js

詳細については、Vertex AI Agent Builder Node.js API のリファレンスドキュメントをご覧ください。

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Full resource name of a
 *  ServingConfig google.cloud.discoveryengine.v1beta.ServingConfig:
 *  `projects/* /locations/global/collections/* /engines/* /servingConfigs/*`, or
 *  `projects/* /locations/global/collections/* /dataStores/* /servingConfigs/*`
 *  One default serving config is created along with your recommendation engine
 *  creation. The engine ID is used as the ID of the default serving
 *  config. For example, for Engine
 *  `projects/* /locations/global/collections/* /engines/my-engine`, you can use
 *  `projects/* /locations/global/collections/* /engines/my-engine/servingConfigs/my-engine`
 *  for your
 *  RecommendationService.Recommend google.cloud.discoveryengine.v1beta.RecommendationService.Recommend 
 *  requests.
 */
// const servingConfig = 'abc123'
/**
 *  Required. Context about the user, what they are looking at and what action
 *  they took to trigger the Recommend request. Note that this user event
 *  detail won't be ingested to userEvent logs. Thus, a separate userEvent
 *  write request is required for event logging.
 *  Don't set
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id 
 *  or
 *  UserEvent.user_info.user_id google.cloud.discoveryengine.v1beta.UserInfo.user_id 
 *  to the same fixed ID for different users. If you are trying to receive
 *  non-personalized recommendations (not recommended; this can negatively
 *  impact model performance), instead set
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id 
 *  to a random unique ID and leave
 *  UserEvent.user_info.user_id google.cloud.discoveryengine.v1beta.UserInfo.user_id 
 *  unset.
 */
// const userEvent = {}
/**
 *  Maximum number of results to return. Set this property
 *  to the number of recommendation results needed. If zero, the service
 *  chooses a reasonable default. The maximum allowed value is 100. Values
 *  above 100 are set to 100.
 */
// const pageSize = 1234
/**
 *  Filter for restricting recommendation results with a length limit of 5,000
 *  characters. Currently, only filter expressions on the `filter_tags`
 *  attribute is supported.
 *  Examples:
 *   * `(filter_tags: ANY("Red", "Blue") OR filter_tags: ANY("Hot", "Cold"))`
 *   * `(filter_tags: ANY("Red", "Blue")) AND NOT (filter_tags: ANY("Green"))`
 *  If `attributeFilteringSyntax` is set to true under the `params` field, then
 *  attribute-based expressions are expected instead of the above described
 *  tag-based syntax. Examples:
 *   * (launguage: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
 *   * (available: true) AND
 *     (launguage: ANY("en", "es")) OR (categories: ANY("Movie"))
 *  If your filter blocks all results, the API returns generic
 *  (unfiltered) popular Documents. If you only want results strictly matching
 *  the filters, set `strictFiltering` to `true` in
 *  RecommendRequest.params google.cloud.discoveryengine.v1beta.RecommendRequest.params 
 *  to receive empty results instead.
 *  Note that the API never returns
 *  Document google.cloud.discoveryengine.v1beta.Document s with
 *  `storageStatus` as `EXPIRED` or `DELETED` regardless of filter choices.
 */
// const filter = 'abc123'
/**
 *  Use validate only mode for this recommendation query. If set to `true`, a
 *  fake model is used that returns arbitrary Document IDs.
 *  Note that the validate only mode should only be used for testing the API,
 *  or if the model is not ready.
 */
// const validateOnly = true
/**
 *  Additional domain specific parameters for the recommendations.
 *  Allowed values:
 *  * `returnDocument`: Boolean. If set to `true`, the associated Document
 *     object is returned in
 *     RecommendResponse.RecommendationResult.document google.cloud.discoveryengine.v1beta.RecommendResponse.RecommendationResult.document.
 *  * `returnScore`: Boolean. If set to true, the recommendation score
 *     corresponding to each returned Document is set in
 *     RecommendResponse.RecommendationResult.metadata google.cloud.discoveryengine.v1beta.RecommendResponse.RecommendationResult.metadata.
 *     The given score indicates the probability of a Document conversion given
 *     the user's context and history.
 *  * `strictFiltering`: Boolean. True by default. If set to `false`, the
 *  service
 *     returns generic (unfiltered) popular Documents instead of empty if
 *     your filter blocks all recommendation results.
 *  * `diversityLevel`: String. Default empty. If set to be non-empty, then
 *     it needs to be one of:
 *      *  `no-diversity`
 *      *  `low-diversity`
 *      *  `medium-diversity`
 *      *  `high-diversity`
 *      *  `auto-diversity`
 *     This gives request-level control and adjusts recommendation results
 *     based on Document category.
 *  * `attributeFilteringSyntax`: Boolean. False by default. If set to true,
 *     the `filter` field is interpreted according to the new,
 *     attribute-based syntax.
 */
// const params = [1,2,3,4]
/**
 *  The user labels applied to a resource must meet the following requirements:
 *  * Each resource can have multiple labels, up to a maximum of 64.
 *  * Each label must be a key-value pair.
 *  * Keys have a minimum length of 1 character and a maximum length of 63
 *    characters and cannot be empty. Values can be empty and have a maximum
 *    length of 63 characters.
 *  * Keys and values can contain only lowercase letters, numeric characters,
 *    underscores, and dashes. All characters must use UTF-8 encoding, and
 *    international characters are allowed.
 *  * The key portion of a label must be unique. However, you can use the same
 *    key with multiple resources.
 *  * Keys must start with a lowercase letter or international character.
 *  See Requirements for
 *  labels (https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements)
 *  for more details.
 */
// const userLabels = [1,2,3,4]

// Imports the Discoveryengine library
const {RecommendationServiceClient} = require('@google-cloud/discoveryengine').v1beta;

// Instantiates a client
const discoveryengineClient = new RecommendationServiceClient();

async function callRecommend() {
  // Construct request
  const request = {
    servingConfig,
    userEvent,
  };

  // Run request
  const response = await discoveryengineClient.recommend(request);
  console.log(response);
}

callRecommend();

PHP

詳細については、Vertex AI Agent Builder PHP API のリファレンスドキュメントをご覧ください。

use Google\ApiCore\ApiException;
use Google\Cloud\DiscoveryEngine\V1beta\Client\RecommendationServiceClient;
use Google\Cloud\DiscoveryEngine\V1beta\RecommendRequest;
use Google\Cloud\DiscoveryEngine\V1beta\RecommendResponse;
use Google\Cloud\DiscoveryEngine\V1beta\UserEvent;

/**
 * Makes a recommendation, which requires a contextual user event.
 *
 * @param string $formattedServingConfig Full resource name of a
 *                                       [ServingConfig][google.cloud.discoveryengine.v1beta.ServingConfig]:
 *                                       `projects/&#42;/locations/global/collections/&#42;/engines/&#42;/servingConfigs/*`, or
 *                                       `projects/&#42;/locations/global/collections/&#42;/dataStores/&#42;/servingConfigs/*`
 *
 *                                       One default serving config is created along with your recommendation engine
 *                                       creation. The engine ID is used as the ID of the default serving
 *                                       config. For example, for Engine
 *                                       `projects/&#42;/locations/global/collections/&#42;/engines/my-engine`, you can use
 *                                       `projects/&#42;/locations/global/collections/&#42;/engines/my-engine/servingConfigs/my-engine`
 *                                       for your
 *                                       [RecommendationService.Recommend][google.cloud.discoveryengine.v1beta.RecommendationService.Recommend]
 *                                       requests. Please see
 *                                       {@see RecommendationServiceClient::servingConfigName()} for help formatting this field.
 * @param string $userEventEventType     User event type. Allowed values are:
 *
 *                                       Generic values:
 *
 *                                       * `search`: Search for Documents.
 *                                       * `view-item`: Detailed page view of a Document.
 *                                       * `view-item-list`: View of a panel or ordered list of Documents.
 *                                       * `view-home-page`: View of the home page.
 *                                       * `view-category-page`: View of a category page, e.g. Home > Men > Jeans
 *
 *                                       Retail-related values:
 *
 *                                       * `add-to-cart`: Add an item(s) to cart, e.g. in Retail online shopping
 *                                       * `purchase`: Purchase an item(s)
 *
 *                                       Media-related values:
 *
 *                                       * `media-play`: Start/resume watching a video, playing a song, etc.
 *                                       * `media-complete`: Finished or stopped midway through a video, song, etc.
 * @param string $userEventUserPseudoId  A unique identifier for tracking visitors.
 *
 *                                       For example, this could be implemented with an HTTP cookie, which should be
 *                                       able to uniquely identify a visitor on a single device. This unique
 *                                       identifier should not change if the visitor log in/out of the website.
 *
 *                                       Do not set the field to the same fixed ID for different users. This mixes
 *                                       the event history of those users together, which results in degraded model
 *                                       quality.
 *
 *                                       The field must be a UTF-8 encoded string with a length limit of 128
 *                                       characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
 *
 *                                       The field should not contain PII or user-data. We recommend to use Google
 *                                       Analytics [Client
 *                                       ID](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#clientId)
 *                                       for this field.
 */
function recommend_sample(
    string $formattedServingConfig,
    string $userEventEventType,
    string $userEventUserPseudoId
): void {
    // Create a client.
    $recommendationServiceClient = new RecommendationServiceClient();

    // Prepare the request message.
    $userEvent = (new UserEvent())
        ->setEventType($userEventEventType)
        ->setUserPseudoId($userEventUserPseudoId);
    $request = (new RecommendRequest())
        ->setServingConfig($formattedServingConfig)
        ->setUserEvent($userEvent);

    // Call the API and handle any network failures.
    try {
        /** @var RecommendResponse $response */
        $response = $recommendationServiceClient->recommend($request);
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $formattedServingConfig = RecommendationServiceClient::servingConfigName(
        '[PROJECT]',
        '[LOCATION]',
        '[DATA_STORE]',
        '[SERVING_CONFIG]'
    );
    $userEventEventType = '[EVENT_TYPE]';
    $userEventUserPseudoId = '[USER_PSEUDO_ID]';

    recommend_sample($formattedServingConfig, $userEventEventType, $userEventUserPseudoId);
}

Python

詳細については、Vertex AI Agent Builder Python API のリファレンスドキュメントをご覧ください。

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1beta


def sample_recommend():
    # Create a client
    client = discoveryengine_v1beta.RecommendationServiceClient()

    # Initialize request argument(s)
    user_event = discoveryengine_v1beta.UserEvent()
    user_event.event_type = "event_type_value"
    user_event.user_pseudo_id = "user_pseudo_id_value"

    request = discoveryengine_v1beta.RecommendRequest(
        serving_config="serving_config_value",
        user_event=user_event,
    )

    # Make the request
    response = client.recommend(request=request)

    # Handle the response
    print(response)

Ruby

詳細については、Vertex AI Agent Builder Ruby API のリファレンスドキュメントをご覧ください。

require "google/cloud/discovery_engine/v1beta"

##
# Snippet for the recommend call in the RecommendationService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client#recommend.
#
def recommend
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1beta::RecommendationService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1beta::RecommendRequest.new

  # Call the recommend method.
  result = client.recommend request

  # The returned object is of type Google::Cloud::DiscoveryEngine::V1beta::RecommendResponse.
  p result
end

レコメンデーションを表示する

メディア レコメンデーションを取得する

Console

REST

構造化データを含むアプリの汎用レコメンデーションを取得する

Console

REST

C#

Go

Java

Node.js

PHP

Python

Ruby

非構造化データを含むアプリの汎用レコメンデーションを取得する

Console

REST

C#

Go

Java

Node.js

PHP

Python

Ruby

ウェブサイト データを含むアプリの汎用レコメンデーションを取得する

Console

REST

C#

Go

Java

Node.js

PHP

Python

Ruby

メディアレコメンデーションを取得する

ウェブサイトデータを含むアプリの汎用レコメンデーションを取得する