Skip to content

Commit 0c27908

Browse files
t-karasovatetiana-karasovasborisenkoxgcf-owl-bot[bot]kweinmeister
authored and
Shabirmean
committed
docs(samples): the bash scripts for environment setup are added (#392)
* Update README * the bash scripts are added * Update README.md * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * Update user_environment_setup.sh * Update user_import_data_to_catalog.sh * Update README.md Co-authored-by: tetiana-karasova <[email protected]> Co-authored-by: Sergey Borisenko <[email protected]> Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Karl Weinmeister <[email protected]>
1 parent d57261a commit 0c27908

File tree

3 files changed

+180
-49
lines changed

3 files changed

+180
-49
lines changed

‎retail/interactive-tutorials/README.md

+91-49
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
#Retail Search Interactive Tutorials
1+
# Retail Search Interactive Tutorials
22

3-
##Run tutorials in Cloud Shell
3+
## Run tutorials in Cloud Shell
44

55
To advance with the interactive tutorials, use Retail Search step-by-step manuals on the right side of the Cloud Shell IDE:
66
![Interactive tutorials](images/tutorial1.png)
@@ -36,55 +36,61 @@ The Retail API provides you with the following possibilities to:
3636

3737
You can find the information about the Retail services in the [documentation](https://cloud.google.com/retail/docs)
3838

39-
<!--TODO(tkarasova) update the link to the tutorials when will be published-->
4039
If you would like to have a closer look at the Retail API features and try them yourself,
41-
the best option is to use the [Interactive Tutorials](https://cloud.google.com/retail/docs/overview). 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.
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.
4241

43-
The code samples in the directory **python-retail/samples/interactive-tutorials** are explicitly created for use with the Retail Interactive Tutorials.
42+
The code samples in the directory **java-retail/samples/interactive-tutorials** are explicitly created for use with the Retail Interactive Tutorials.
4443

4544
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.
4645

47-
### Select your project and enable the Retail API
46+
## Prepare your work environment
4847

49-
Google Cloud organizes resources into projects. This lets you
50-
collect all the related resources for a single application in one place.
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.
5152

52-
If you don't have a Google Cloud project yet or you're not the owner of an existing one, you can
53-
[create a new project](https://console.cloud.google.com/projectcreate).
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:
5456

55-
After the project is created, set your PROJECT_ID to a ```project``` variable.
56-
1. Run the following command in Terminal:
5757
```bash
58-
gcloud config set project <YOUR_PROJECT_ID>
58+
bash java-retail/samples/interactive-tutorials/user_environment_setup.sh
5959
```
6060

61-
1. To check that the Retail API is enabled for your Project, go to the [Admin Console](https://console.cloud.google.com/ai/retail/).
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
6264

6365
### Create service account
6466

65-
To access the Retail API, you must create a service account.
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).
6668

67-
1. To create a service account, follow this [instruction](https://cloud.google.com/retail/docs/setting-up#service-account)
69+
1. To create a service account, perform the following command:
6870

69-
1. Find your service account on the [IAM page](https://console.cloud.google.com/iam-admin/iam),
70-
click `Edit` icon, add the 'Storage Admin' and 'BigQuery Admin' roles. It may take some time for changes to apply.
71+
```bash
72+
gcloud iam service-accounts create <YOUR_SERVICE_ACCOUNT_ID>
73+
```
7174

72-
1. Copy the service account email in the Principal field.
75+
1. Assign the needed roles to your service account:
7376

74-
### Set up authentication
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+
```
7582

76-
To run a code sample from the Cloud Shell, you need to be authenticated using the service account credentials.
83+
1. Use the following command to show the service account email:
7784

78-
1. Login with your user credentials.
7985
```bash
80-
gcloud auth login
86+
gcloud iam service-accounts list|grep <YOUR_SERVICE_ACCOUNT_ID>
8187
```
8288

83-
1. Type `Y` and press **Enter**. Click the link in a Terminal. A browser window should appear asking you to log in using your Gmail account.
89+
Copy the service account email.
8490

85-
1. Provide the Google Auth Library with access to your credentials and paste the code from the browser to the Terminal.
8691

87-
1. Upload your service account key JSON file and use it to activate the service account:
92+
1. Upload your service account key JSON file and use it to activate the service
93+
account:
8894

8995
```bash
9096
gcloud iam service-accounts keys create ~/key.json --iam-account <YOUR_SERVICE_ACCOUNT_EMAIL>
@@ -94,57 +100,93 @@ To run a code sample from the Cloud Shell, you need to be authenticated using th
94100
gcloud auth activate-service-account --key-file ~/key.json
95101
```
96102

97-
1. To request the Retail API, set your service account key JSON file as the GOOGLE_APPLICATION_CREDENTIALS environment variable :
103+
1. Set the key as the GOOGLE_APPLICATION_CREDENTIALS environment variable to
104+
use it for sending requests to the Retail API.
105+
98106
```bash
99107
export GOOGLE_APPLICATION_CREDENTIALS=~/key.json
100108
```
101109

102-
### Set the GOOGLE_CLOUD_PROJECT environment variable
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
103115

104-
You will run the code samples in your own Google Cloud project. To use the **project_id** in every request to the Retail API, you should first specify them as environment variables.
116+
1. Check that you are in the directory with code samples.
105117

106-
1. Find the project ID in the Project Info card displayed on **Home/Dashboard**.
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.
107121

108-
1. Set the **project_id** with the following command:
109122
```bash
110-
export GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
123+
cd java-retail/samples/interactive-tutorials/
124+
```
111125

112-
## Import Catalog Data
126+
## Import catalog data
113127

114-
This step is required if this is the first Retail API Tutorial you run.
115-
Otherwise, you can skip it.
128+
<i>This step is required if this is the first Retail API tutorial that you run.
129+
Otherwise, you can skip it.</i>
116130

117-
### Upload catalog data to Cloud Storage
131+
There is a java-retail/samples/interactive-tutorials/src/main/resources/products.json file with valid products prepared in the `resources` directory.
118132

119-
There is a JSON file with valid products prepared in the `product` directory:
120-
`product/resources/products.json`.
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.
121134

122-
Another file, `product/resources/products_some_invalid.json`, contains both valid and invalid products, and you will use it to check the error handling.
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:
123136

124-
In your own project, create a Cloud Storage bucket and put the JSON file there.
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.
125148
The bucket name must be unique. For convenience, you can name it `<YOUR_PROJECT_ID>_<TIMESTAMP>`.
126149

127-
1. To create the bucket and upload the JSON file, run the following command in the Terminal:
128-
<!--TODO update with the correct file path when will be merged-->
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+
129154
```bash
130-
pmvn compile exec:java -Dexec.mainClass=CreateGcsBucket
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
131165
```
132166

133167
Now you can see the bucket is created in the [Cloud Storage](https://console.cloud.google.com/storage/browser), and the files are uploaded.
134168

135-
1. The name of the created Retail Search bucket is printed in the Terminal. Copy the name and set it as the environment variable `BUCKET_NAME`:
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`:
136176

137177
```bash
138178
export BUCKET_NAME=<YOUR_BUCKET_NAME>
139179
```
140180

141181
### Import products to the Retail Catalog
142182

143-
To import the prepared products to a catalog, run the following command in the Terminal:
144-
<!--TODO update with the correct file path when will be merged-->
145-
```bash
146-
pmvn compile exec:java -Dexec.mainClass=ImportProductsGcs
147-
```
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!
148190

149191
### Running code samples
150192

‎retail/interactive-tutorials/user_environment_setup.sh

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
#!/bin/bash
2+
3+
# Copyright 2022 Google Inc. All Rights Reserved.
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
# set the Google Cloud Project ID
18+
project_id=$1
19+
echo "Project ID: $project_id"
20+
gcloud config set project "$project_id"
21+
22+
timestamp=$(date +%s)
23+
24+
service_account_id="service-acc-$timestamp"
25+
echo "Service Account: $service_account_id"
26+
27+
# create service account (your service-acc-$timestamp)
28+
gcloud iam service-accounts create "$service_account_id"
29+
30+
# assign necessary roles to your new service account
31+
for role in {retail.admin,editor,bigquery.admin}
32+
do
33+
gcloud projects add-iam-policy-binding "$project_id" --member="serviceAccount:$service_account_id@$project_id.iam.gserviceaccount.com" --role=roles/"${role}"
34+
done
35+
36+
echo "Wait ~60 seconds to be sure the appropriate roles have been assigned to your service account"
37+
sleep 60
38+
39+
# upload your service account key file
40+
service_acc_email="$service_account_id@$project_id.iam.gserviceaccount.com"
41+
gcloud iam service-accounts keys create ~/key.json --iam-account "$service_acc_email"
42+
43+
# activate the service account using the key
44+
gcloud auth activate-service-account --key-file ~/key.json
45+
46+
# install needed Google client libraries
47+
cd ~/cloudshell_open/java-retail/samples/interactive-tutorials || exit
48+
mvn clean install -DskipTests
49+
50+
echo "========================================"
51+
echo "The Google Cloud setup is completed."
52+
echo "Please proceed with the Tutorial steps"
53+
echo "========================================"

‎retail/interactive-tutorials/user_import_data_to_catalog.sh

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
#!/bin/bash
2+
3+
# Copyright 2022 Google Inc. All Rights Reserved.
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
# set the key as GOOGLE_APPLICATION_CREDENTIALS
18+
export GOOGLE_APPLICATION_CREDENTIALS=~/key.json
19+
20+
# Change the working directory
21+
cd ~/cloudshell_open/java-retail/samples/interactive-tutorials/ || exit
22+
23+
# Run the sample for creating the GCS bucket and extract the output of that execution
24+
output=$(mvn compile exec:java -Dexec.mainClass="product.setup.ProductsCreateGcsBucket")
25+
26+
# Get the bucket name and store it in the env variable BUCKET_NAME
27+
temp="${output#*gcs bucket }"
28+
bucket_name="${temp% was created*}"
29+
export BUCKET_NAME=$bucket_name
30+
31+
# Import products to the Retail catalog
32+
mvn compile exec:java -Dexec.mainClass="product.ImportProductsGcs"
33+
34+
echo "====================================="
35+
echo "Your Retail catalog is ready to use!"
36+
echo "====================================="

0 commit comments

Comments
 (0)