Skip to content

Commit 4869569

Browse files
ShabirmeanShabirmean
committed
Merge remote-tracking branch 'migration/main' into java-retail-migration
2 parents e7ce63a + 3e9a99b commit 4869569

File tree

73 files changed

+6082
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

73 files changed

+6082
-0
lines changed

‎retail/interactive-tutorials/README.md

+211
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# Retail Search Interactive Tutorials
2+
3+
## Run tutorials in Cloud Shell
4+
5+
To advance with the interactive tutorials, use Retail Search step-by-step manuals on the right side of the Cloud Shell IDE:
6+
![Interactive tutorials](images/tutorial1.png)
7+
8+
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:
9+
![Toggle tutorial](images/tutorials2.png)
10+
11+
For more details about the Cloud Shell environment, refer to the [Cloud Shell documentation](https://cloud.google.com/shell/docs).
12+
13+
## Interactive tutorial flow
14+
15+
Interactive guides are intended to help you understand the features provided by Google Cloud Retail Search and test the Retail API in action.
16+
17+
To proceed with the tutorial, choose a language you’ll be deploying your project in:
18+
![Select a programming language](images/tutorials3.png)
19+
20+
21+
To begin with the tutorial workflow, click the Start button:
22+
![Begin with the tutorial](images/tutorials4.png)
23+
24+
Then, you can use Next and Previous buttons to navigate the tutorial pages.
25+
26+
## Java code samples
27+
28+
The code here demonstrates how to consume Google Retail Search API in Java
29+
30+
## Get started with the Google Cloud Retail API
31+
32+
The Retail API provides you with the following possibilities to:
33+
- Create and maintaining the catalog data.
34+
- Fine-tune the search configuration.
35+
- Import and maintain the user events data.
36+
37+
You can find the information about the Retail services in the [documentation](https://cloud.google.com/retail/docs)
38+
39+
If you would like to have a closer look at the Retail API features and try them yourself,
40+
the best option is to use the [Interactive Tutorials](https://cloud.google.com/retail/docs/overview). 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.
41+
42+
The code samples in the directory **java-retail/samples/interactive-tutorials** are explicitly created for use with the Retail Interactive Tutorials.
43+
44+
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.
45+
46+
## Prepare your work environment
47+
48+
To prepare the work environment you should perform the following steps:
49+
- Create a service account.
50+
- Create a service account key and set it to authorize your calls to the Retail API.
51+
- Install Google Cloud Retail library.
52+
53+
### There are two ways to set up your work environment:
54+
55+
- If you want to **speed up the process** of setting up the working environment, run the script java-retail/samples/interactive-tutorials/samples/interactive-tutorials/src/main/java/user_environment_setup.sh and skip the next **set up the work environment step-by-step** tutorial step:
56+
57+
```bash
58+
bash java-retail/samples/interactive-tutorials/user_environment_setup.sh
59+
```
60+
61+
- 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.
62+
63+
## Set up the work environment step-by-step
64+
65+
### Create service account
66+
67+
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](https://console.cloud.google.com/iam-admin/iam).
68+
69+
1. To create a service account, perform the following command:
70+
71+
```bash
72+
gcloud iam service-accounts create <YOUR_SERVICE_ACCOUNT_ID>
73+
```
74+
75+
1. Assign the needed roles to your service account:
76+
77+
```bash
78+
for role in {retail.admin,editor,bigquery.admin}
79+
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}"
80+
done
81+
```
82+
83+
1. Use the following command to show the service account email:
84+
85+
```bash
86+
gcloud iam service-accounts list|grep <YOUR_SERVICE_ACCOUNT_ID>
87+
```
88+
89+
Copy the service account email.
90+
91+
92+
1. Upload your service account key JSON file and use it to activate the service
93+
account:
94+
95+
```bash
96+
gcloud iam service-accounts keys create ~/key.json --iam-account <YOUR_SERVICE_ACCOUNT_EMAIL>
97+
```
98+
99+
```bash
100+
gcloud auth activate-service-account --key-file ~/key.json
101+
```
102+
103+
1. Set the key as the GOOGLE_APPLICATION_CREDENTIALS environment variable to
104+
use it for sending requests to the Retail API.
105+
106+
```bash
107+
export GOOGLE_APPLICATION_CREDENTIALS=~/key.json
108+
```
109+
110+
### Google Cloud Retail libraries
111+
112+
Learn more about the [Java Google Cloud Retail library](https://googleapis.dev/java/google-cloud-retail/latest/index.html).
113+
114+
## Congrats! You have configured your work environment
115+
116+
1. Check that you are in the directory with code samples.
117+
118+
The code samples for each of the Retail services are stored in different directories.
119+
120+
Go to the code samples directory, your starting point to run more commands.
121+
122+
```bash
123+
cd java-retail/samples/interactive-tutorials/
124+
```
125+
126+
## Import catalog data
127+
128+
<i>This step is required if this is the first Retail API tutorial that you run.
129+
Otherwise, you can skip it.</i>
130+
131+
There is a java-retail/samples/interactive-tutorials/src/main/resources/products.json file with valid products prepared in the `resources` directory.
132+
133+
The other file, java-retail/samples/interactive-tutorials/src/main/resources/products_some_invalid.json, contains both valid and invalid products. You will use it to check the error handling.
134+
135+
- 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:
136+
137+
```bash
138+
bash java-retail/samples/interactive-tutorials/user_import_data_to_catalog.sh
139+
```
140+
141+
- 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.
142+
143+
## Prepare the catalog data step-by-step
144+
145+
### Upload catalog data to Cloud Storage
146+
147+
In your own project you need to create a Cloud Storage bucket and put the JSON file there.
148+
The bucket name must be unique. For convenience, you can name it `<YOUR_PROJECT_ID>_<TIMESTAMP>`.
149+
150+
1. The code samples for each of the Retail services are stored in different directories.
151+
152+
Go to the code samples directory, your starting point to run more commands.
153+
154+
```bash
155+
cd java-retail/samples/interactive-tutorials
156+
```
157+
158+
1. To create the bucket and upload the JSON file, open java-retail/samples/interactive-tutorials/src/main/java/product/setup/ProductsCreateGcsBucket.java file
159+
160+
1. Go to the **product** directory and run the following command in the Terminal:
161+
162+
```bash
163+
mvn compile exec:java
164+
-Dexec.mainClass=product.setup.ProductsCreateGcsBucket
165+
```
166+
167+
Now you can see the bucket is created in the [Cloud Storage](https://console.cloud.google.com/storage/browser), and the files are uploaded.
168+
169+
1. The name of the created Cloud Storage bucket is shown in the Terminal.
170+
171+
```
172+
The gcs bucket <YOUR_PROJECT_ID>_<TIMESTAMP> was created
173+
```
174+
175+
Copy the name and set it as the environment variable `BUCKET_NAME`:
176+
177+
```bash
178+
export BUCKET_NAME=<YOUR_BUCKET_NAME>
179+
```
180+
181+
### Import products to the Retail Catalog
182+
183+
To import the prepared products to a catalog, open java-retail/samples/interactive-tutorials/src/main/java/product/ImportProductsGcs.java file and run the following command in the Terminal:
184+
185+
```bash
186+
mvn compile exec:java -Dexec.mainClass=product.ImportProductsGcs
187+
```
188+
189+
## Your Retail catalog is ready to use!
190+
191+
### Running code samples
192+
193+
Use maven command to run specific code sample:
194+
195+
```
196+
mvn compile exec:java -Dexec.mainClass="package.CodeSampleClass"
197+
```
198+
199+
### Running unit tests
200+
201+
Use maven command to run specific unit test class:
202+
203+
```
204+
mvn test -Dtest=TestClassName
205+
```
206+
207+
Use maven command to run all unit tests:
208+
209+
```
210+
mvn test
211+
```

‎retail/interactive-tutorials/images/tutorail1.img

Whitespace-only changes.

‎retail/interactive-tutorials/images/tutorial1.png

359 KB
Loading

‎retail/interactive-tutorials/images/tutorials2.png

89.6 KB
Loading

‎retail/interactive-tutorials/images/tutorials3.png

360 KB
Loading

‎retail/interactive-tutorials/images/tutorials4.png

764 KB
Loading

‎retail/interactive-tutorials/pom.xml

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
<groupId>com.google.cloud</groupId>
7+
<artifactId>retail-interactive-tutorials</artifactId>
8+
<packaging>jar</packaging>
9+
<name>Google Cloud Retail Interactive Tutorials</name>
10+
<url>https://github.com/googleapis/java-retail</url>
11+
12+
<!--
13+
The parent pom defines common style checks and testing strategies for our samples.
14+
Removing or replacing it should not affect the execution of the samples in anyway.
15+
-->
16+
<parent>
17+
<groupId>com.google.cloud.samples</groupId>
18+
<artifactId>shared-configuration</artifactId>
19+
<version>1.2.0</version>
20+
<relativePath/>
21+
</parent>
22+
23+
<properties>
24+
<maven.compiler.source>1.8</maven.compiler.source>
25+
<maven.compiler.target>1.8</maven.compiler.target>
26+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
27+
</properties>
28+
29+
<dependencyManagement>
30+
<dependencies>
31+
<dependency>
32+
<groupId>com.google.cloud</groupId>
33+
<artifactId>libraries-bom</artifactId>
34+
<version>26.1.3</version>
35+
<type>pom</type>
36+
<scope>import</scope>
37+
</dependency>
38+
</dependencies>
39+
</dependencyManagement>
40+
41+
<dependencies>
42+
<dependency>
43+
<groupId>com.google.cloud</groupId>
44+
<artifactId>google-cloud-retail</artifactId>
45+
<version>2.5.2</version>
46+
</dependency>
47+
<dependency>
48+
<groupId>junit</groupId>
49+
<artifactId>junit</artifactId>
50+
<version>4.13.2</version>
51+
<scope>test</scope>
52+
</dependency>
53+
<dependency>
54+
<groupId>com.google.cloud</groupId>
55+
<artifactId>google-cloud-bigquery</artifactId>
56+
<version>2.17.0</version>
57+
</dependency>
58+
<dependency>
59+
<groupId>com.google.cloud</groupId>
60+
<artifactId>google-cloud-storage</artifactId>
61+
<version>2.13.0</version>
62+
</dependency>
63+
<dependency>
64+
<groupId>com.google.code.gson</groupId>
65+
<artifactId>gson</artifactId>
66+
<version>2.9.1</version>
67+
</dependency>
68+
<dependency>
69+
<groupId>com.google.truth</groupId>
70+
<artifactId>truth</artifactId>
71+
<version>1.1.3</version>
72+
<scope>test</scope>
73+
</dependency>
74+
</dependencies>
75+
76+
<build>
77+
<plugins>
78+
<plugin>
79+
<groupId>org.codehaus.mojo</groupId>
80+
<artifactId>exec-maven-plugin</artifactId>
81+
<version>3.1.0</version>
82+
<configuration>
83+
<cleanupDaemonThreads>true</cleanupDaemonThreads>
84+
</configuration>
85+
</plugin>
86+
</plugins>
87+
</build>
88+
</project>

0 commit comments

Comments
 (0)