To advance with the interactive tutorials, use Retail Search step-by-step manuals on the right side of the Cloud Shell IDE:

The interactive tutorial should open by default. If it didn’t, click on the Tutorial symbol in the menu bar to open the step-by-step manual:

For more details about the Cloud Shell environment, refer to the Cloud Shell documentation.

Interactive guides are intended to help you understand the features provided by Google Cloud Retail Search and test the Retail API in action.

To proceed with the tutorial, choose a language you’ll be deploying your project in:

To begin with the tutorial workflow, click the Start button:

Then, you can use Next and Previous buttons to navigate the tutorial pages.

The code here demonstrates how to consume Google Retail Search API in Java

The Retail API provides you with the following possibilities to:

• Create and maintaining the catalog data.
• Fine-tune the search configuration.
• Import and maintain the user events data.

You can find the information about the Retail services in the documentation

If you would like to have a closer look at the Retail API features and try them yourself, the best option is to use the Interactive Tutorials. In the documentation chapters find the "Guide me" button, the tutorials will be launched in the CloudShell environment, and you will be able to request the Retail services and check the response with minimum time and effort.

The code samples in the directory java-docs-samples/retail/interactive-tutorials are explicitly created for use with the Retail Interactive Tutorials.

If, for some reason, you have decided to proceed with these code samples without the tutorial, please go through the following steps and set up the required preconditions.

To prepare the work environment you should perform the following steps:

• Create a service account.
• Create a service account key and set it to authorize your calls to the Retail API.
• Install Google Cloud Retail library.

• If you want to speed up the process of setting up the working environment, run the script java-docs-samples/retail/interactive-tutorials/src/main/java/user_environment_setup.sh and skip the next set up the work environment step-by-step tutorial step:

  bash java-docs-samples/retail/interactive-tutorials/user_environment_setup.sh

• If you want to perform the environment set up step by step along with getting the explanation you should proceed with the next tutorial step.

To access the Retail API, you must create a service account. Check that you are an owner of your Google Cloud project on the IAM page.

1. To create a service account, perform the following command:

   gcloud iam service-accounts create <YOUR_SERVICE_ACCOUNT_ID>

2. Assign the needed roles to your service account:

   for role in {retail.admin,editor,bigquery.admin}
   do gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> --member="serviceAccount:<YOUR_SERVICE_ACCOUNT_ID>@<YOUR_PROJECT_ID>.iam.gserviceaccount.com" --role="roles/${role}"
   done

3. Use the following command to show the service account email:

   gcloud iam service-accounts list|grep <YOUR_SERVICE_ACCOUNT_ID>

   Copy the service account email.

4. Upload your service account key JSON file and use it to activate the service account:

   gcloud iam service-accounts keys create ~/key.json --iam-account <YOUR_SERVICE_ACCOUNT_EMAIL>

   gcloud auth activate-service-account --key-file ~/key.json

5. Set the key as the GOOGLE_APPLICATION_CREDENTIALS environment variable to use it for sending requests to the Retail API.

   export GOOGLE_APPLICATION_CREDENTIALS=~/key.json

Learn more about the Java Google Cloud Retail library.

1. Check that you are in the directory with code samples.

   The code samples for each of the Retail services are stored in different directories.

   Go to the code samples directory, your starting point to run more commands.

   cd java-docs-samples/retail/interactive-tutorials/

This step is required if this is the first Retail API tutorial that you run. Otherwise, you can skip it.

There is a java-docs-samples/retail/interactive-tutorials/src/main/resources/products.json file with valid products prepared in the resources directory.

The other file, java-docs-samples/retail/interactive-tutorials/src/main/resources/products_some_invalid.json, contains both valid and invalid products. You will use it to check the error handling.

• If you want to speed up the process, run the following script in the Terminal directory to import all products to catalog and skip the next Prepare the catalog data step-by-step tutorial step:

  bash java-docs-samples/retail/interactive-tutorials/user_import_data_to_catalog.sh

• If you want to upload products to the catalog step by step along with getting the explanation, you should proceed with the next tutorial step.

In your own project you need to create a Cloud Storage bucket and put the JSON file there. The bucket name must be unique. For convenience, you can name it <YOUR_PROJECT_ID>_<TIMESTAMP>.

1. The code samples for each of the Retail services are stored in different directories.

   Go to the code samples directory, your starting point to run more commands.

   cd java-docs-samples/retail/interactive-tutorials

2. To create the bucket and upload the JSON file, open java-docs-samples/retail/interactive-tutorials/src/main/java/product/setup/ProductsCreateGcsBucket.java file

3. Go to the product directory and run the following command in the Terminal:

   mvn compile exec:java
   -Dexec.mainClass=product.setup.ProductsCreateGcsBucket

   Now you can see the bucket is created in the Cloud Storage, and the files are uploaded.

4. The name of the created Cloud Storage bucket is shown in the Terminal.

   The gcs bucket <YOUR_PROJECT_ID>_<TIMESTAMP> was created
   

   Copy the name and set it as the environment variable BUCKET_NAME:

   export BUCKET_NAME=<YOUR_BUCKET_NAME>

To import the prepared products to a catalog, open java-docs-samples/retail/interactive-tutorials/src/main/java/product/ImportProductsGcs.java file and run the following command in the Terminal:

mvn compile exec:java -Dexec.mainClass=product.ImportProductsGcs

Use maven command to run specific code sample:

mvn compile exec:java -Dexec.mainClass="package.CodeSampleClass"

Use maven command to run specific unit test class:

mvn test -Dtest=TestClassName

Use maven command to run all unit tests:

mvn test