Skip to content
This repository has been archived by the owner on Oct 3, 2023. It is now read-only.

docs(samples): the bash scripts for environment setup are added #392

Merged
merged 10 commits into from
Apr 7, 2022
32 changes: 7 additions & 25 deletions samples/interactive-tutorials/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#Retail Search Interactive Tutorials
# Retail Search Interactive Tutorials

##Run tutorials in Cloud Shell
## Run tutorials in Cloud Shell

To advance with the interactive tutorials, use Retail Search step-by-step manuals on the right side of the Cloud Shell IDE:
![Interactive tutorials](images/tutorial1.png)
Expand Down Expand Up @@ -53,7 +53,9 @@ If you don't have a Google Cloud project yet or you're not the owner of an exist
[create a new project](https://console.cloud.google.com/projectcreate).

After the project is created, set your PROJECT_ID to a ```project``` variable.

1. Run the following command in Terminal:

```bash
gcloud config set project <YOUR_PROJECT_ID>
```
Expand All @@ -75,15 +77,6 @@ To access the Retail API, you must create a service account.

To run a code sample from the Cloud Shell, you need to be authenticated using the service account credentials.

1. Login with your user credentials.
```bash
gcloud auth login
```

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.

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

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

```bash
Expand All @@ -99,16 +92,6 @@ To run a code sample from the Cloud Shell, you need to be authenticated using th
export GOOGLE_APPLICATION_CREDENTIALS=~/key.json
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aren't we trying to de-emphasize GOOGLE_APPLICATION_CREDENTIALS in favor of gcloud auth application-default login ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

using GOOGLE_APPLICATION_CREDENTIALS to request the Retail servicei is a recommented way to do that.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really? Most of the time we are providing you with credentials.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is discribed in the Retail documentation we are relying creating this tutorials https://cloud.google.com/retail/docs/setting-up#local-environment

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That isn't the way things are supposed to be these days.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you reach out to a TechWriter?

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://cloud.google.com/docs/authentication/production#automatically
From our previous experiences, gcloud CLI often results in using end user credentials instead of the service account credentials in some languages, and causing errors like "Your application has authenticated using end user credentials from the Google Cloud SDK or Google Cloud Shell which are not supported."

In this case, we prefer to have users explicitly set GOOGLE_APPLICATION_CREDENTIALS so that end user credentials won't be used.

```

### Set the GOOGLE_CLOUD_PROJECT environment variable

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.

1. Find the project ID in the Project Info card displayed on **Home/Dashboard**.

1. Set the **project_id** with the following command:
```bash
export GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>

## Import Catalog Data

This step is required if this is the first Retail API Tutorial you run.
Expand All @@ -125,9 +108,8 @@ In your own project, 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. To create the bucket and upload the JSON file, run the following command in the Terminal:
<!--TODO update with the correct file path when will be merged-->
```bash
pmvn compile exec:java -Dexec.mainClass=CreateGcsBucket
mvn compile exec:java -Dexec.mainClass="product.setup.ProductsCreateGcsBucket"
```

Now you can see the bucket is created in the [Cloud Storage](https://console.cloud.google.com/storage/browser), and the files are uploaded.
Expand All @@ -141,9 +123,9 @@ The bucket name must be unique. For convenience, you can name it `<YOUR_PROJECT_
### Import products to the Retail Catalog

To import the prepared products to a catalog, run the following command in the Terminal:
<!--TODO update with the correct file path when will be merged-->

```bash
pmvn compile exec:java -Dexec.mainClass=ImportProductsGcs
mvn compile exec:java -Dexec.mainClass="product.ImportProductsGcs"
```

### Running code samples
Expand Down
53 changes: 53 additions & 0 deletions samples/interactive-tutorials/user_environment_setup.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
#!/bin/bash

# Copyright 2022 Google Inc. All Rights Reserved.
Shabirmean marked this conversation as resolved.
Show resolved Hide resolved
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# set the Google Cloud project Id
Shabirmean marked this conversation as resolved.
Show resolved Hide resolved
project_id=$1
echo Project ID: $project_id
gcloud config set project project_id
Shabirmean marked this conversation as resolved.
Show resolved Hide resolved

timestamp=$(date +%s)

service_account_id="service-acc-"$timestamp
Shabirmean marked this conversation as resolved.
Show resolved Hide resolved
echo Service Account: $service_account_id

# create service account (your project_id+timestamp)
Shabirmean marked this conversation as resolved.
Show resolved Hide resolved
gcloud iam service-accounts create $service_account_id

# assign needed roles to your new service account
Shabirmean marked this conversation as resolved.
Show resolved Hide resolved
for role in {retail.admin,editor,bigquery.admin}
do
gcloud projects add-iam-policy-binding $project_id --member="serviceAccount:"$service_account_id"@"$project_id".iam.gserviceaccount.com" --role="roles/${role}"
Shabirmean marked this conversation as resolved.
Show resolved Hide resolved
done

echo Wait 70 seconds to be sure the appropriate roles have been assigned to your service account
Shabirmean marked this conversation as resolved.
Show resolved Hide resolved
sleep 70

# upload your service account key file
service_acc_email=$service_account_id"@"$project_id".iam.gserviceaccount.com"
gcloud iam service-accounts keys create ~/key.json --iam-account $service_acc_email

# activate the service account using the key
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, if your doing this, then why tell the user to provide a service account in the README?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the tutorials we give the user 2 options - eanther users want to setup the work env by themselfs, then we provide steps similar to those discribed in the README, or they want to speedup the process and start exploring the Retail features - for tha purpose we give them this scripts.

But you are right, it is good to tell users that they may use the scripts in the Readme as well

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

# install needed Google client libraries
cd ~/cloudshell_open/java-retail/samples/interactive-tutorials
Shabirmean marked this conversation as resolved.
Show resolved Hide resolved
mvn clean install -DskipTests

echo ========================================
Shabirmean marked this conversation as resolved.
Show resolved Hide resolved
echo "The Google Cloud setup is completed."
echo "Please proceed with the Tutorial steps"
echo ========================================
36 changes: 36 additions & 0 deletions samples/interactive-tutorials/user_import_data_to_catalog.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
#!/bin/bash

# Copyright 2022 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# set the key as GOOGLE_APPLICATION_CREDENTIALS
export GOOGLE_APPLICATION_CREDENTIALS=~/key.json
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You do know that this will not be set once the script ends?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know that, but we still need this variable to run the java code samples within the script


# Change the working directory
cd ~/cloudshell_open/java-retail/samples/interactive-tutorials/

# Create a GCS bucket and upload the product data to the bucket
Shabirmean marked this conversation as resolved.
Show resolved Hide resolved
output=$(mvn compile exec:java -Dexec.mainClass="product.setup.ProductsCreateGcsBucket")

# Get the bucket name and store it in the env variable BUCKET_NAME
temp="${output#*gcs bucket }"
bucket_name="${temp% was created*}"
export BUCKET_NAME=$bucket_name

# Import products to the Retail catalog
mvn compile exec:java -Dexec.mainClass="product.ImportProductsGcs"

echo =====================================
echo "Your Retail catalog is ready to use!"
echo =====================================