Skip to content

Commit

Permalink
chore: update README and setup scripts (#193)
Browse files Browse the repository at this point in the history 
* update README

* fix: sleep is added to the setup script

* fix: sleep is added to the setup script

Co-authored-by: tetiana-karasova <[email protected]>
Co-authored-by: Anthonios Partheniou <[email protected]>
  • Loading branch information
@t-karasova @tetiana-karasova @parthea
3 people authored Mar 30, 2022
1 parent 18693eb commit 4e7a806
Show file tree
Hide file tree
Showing 3 changed files with 101 additions and 50 deletions.
105 changes: 73 additions & 32 deletions packages/google-cloud-retail/samples/interactive-tutorials/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,44 +43,69 @@ If, for some reason, you have decided to proceed with these code samples without
### Select your project and enable the Retail API

Google Cloud organizes resources into projects. This lets you
collect all the related resources for a single application in one place.
collect all related resources for a single application in one place.

If you don't have a Google Cloud project yet or you're not the owner of an existing one, you can
[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:
After the project is created, set your PROJECT_ID to a ```project``` variable:

1. Run the following command in the Terminal:

```bash
gcloud config set project <YOUR_PROJECT_ID>
```

1. To check that the Retail API is enabled for your Project, go to the [Admin Console](https://console.cloud.google.com/ai/retail/).
1. Ensure that the Retail API is enabled for your project in the [API & Services page](https://console.cloud.google.com/apis/api/retail.googleapis.com/).

1. Log in with your user credentials to run a code sample from the Cloud Shell:

```bash
gcloud auth login
```

1. Type `Y` and press **Enter**. Click the link in the 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.

## Prepare your work environment

To prepare the work environment you should perform the following steps:
- Create a service account.
- Create service account key and set it to authorize your calls to the Retail API.
- Install Google Cloud Retail library.

### Create service account

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

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

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

1. Copy the service account email in the Principal field.
1. Assign the needed roles to your service account:

### Set up authentication
```bash
for role in {retail.admin,storage.admin,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
```

To run a code sample from the Cloud Shell, you need to be authenticated using the service account credentials.
1. Use the following command to print out the service account email:

1. Login with your user credentials.
```bash
gcloud auth login
gcloud iam service-accounts list|grep <YOUR_SERVICE_ACCOUNT_ID>
```

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.
Copy the service account email.

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:
1. Upload your service account key JSON file and use it to activate the service
account:

```bash
gcloud iam service-accounts keys create ~/key.json --iam-account <YOUR_SERVICE_ACCOUNT_EMAIL>
Expand All @@ -90,7 +115,9 @@ To run a code sample from the Cloud Shell, you need to be authenticated using th
gcloud auth activate-service-account --key-file ~/key.json
```

1. To request the Retail API, set your service account key JSON file as the GOOGLE_APPLICATION_CREDENTIALS environment variable :
1. Set the key as the GOOGLE_APPLICATION_CREDENTIALS environment variable to
use it for sending requests to the Retail API.

```bash
export GOOGLE_APPLICATION_CREDENTIALS=~/key.json
```
Expand All @@ -100,12 +127,14 @@ To run a code sample from the Cloud Shell, you need to be authenticated using th
To run Python code samples for the Retail API tutorial, you need to set up your virtual environment.

1. Run the following commands in a Terminal to create an isolated Python environment:

```bash
pip install virtualenv
virtualenv myenv
virtualenv -p python3 myenv
source myenv/bin/activate
```

1. Next, install Google packages:

```bash
pip install google
pip install google-cloud-retail
Expand All @@ -114,41 +143,53 @@ To run Python code samples for the Retail API tutorial, you need to set up your
```

## Import Catalog Data
## Import catalog data

This step is required if this is the first Retail API Tutorial you run.
Otherwise, you can skip it.
There is a python-retail/samples/interactive-tutorials/resources/products.json file with valid products prepared in the `resources` directory.

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

### Upload catalog data to Cloud Storage

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

Another file, `product/resources/products_some_invalid.json`, contains both valid and invalid products, and you will use it to check the error handling.
1. The code samples for each of the Retail services are stored in different directories.

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>`.
Go to the code samples directory, your starting point to run more commands.

1. To create the bucket and upload the JSON file, run the following command in the Terminal:
```bash
cd python-retail/samples/interactive-tutorials
```

1. To create the bucket and upload the JSON file, open python-retail/samples/interactive-tutorials/product/setup_product/products_create_gcs_bucket.py file

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

```bash
python product/setup_product/create_gcs_bucket.py
python setup_product/products_create_gcs_bucket.py
```

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

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`:
1. The name of the created Cloud Storage bucket is printed in the Terminal.

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

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

```bash
export BUCKET_NAME=<YOUR_BUCKET_NAME>
```

### Import products to the Retail Catalog

To import the prepared products to a catalog, run the following command in the Terminal:
To import the prepared products to a catalog, open python-retail/samples/interactive-tutorials/product/import_products_gcs.py file and run the following command in the Terminal:

```bash
python product/import_products_gcs.py
python import_products_gcs.py
```

## Run your code sample
Expand Down
27 changes: 17 additions & 10 deletions packages/google-cloud-retail/samples/interactive-tutorials/user_environment_setup.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,21 +14,27 @@
# See the License for the specific language governing permissions and
# limitations under the License.

# get the project_id from gcloud config
project_id=$(gcloud config get-value project)
echo $project_id
# set the Google Cloud project Id
project_id=$1
echo Project ID: $project_id
gcloud config set project project_id

timestamp=$(date +%s)
echo $timestamp

service_account_id="service-acc-"$timestamp
echo Service Account: $service_account_id

# create service account (your project_id+timestamp)
gcloud iam service-accounts create $service_account_id

# assign needed roles to your new service account
for role in {retail.admin,storage.admin,bigquery.admin}
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}"
done
done

echo Wait 70 seconds to be sure the appropriate roles have been assigned to your service account
sleep 70

# upload your service account key file
service_acc_email=$service_account_id"@"$project_id".iam.gserviceaccount.com"
Expand All @@ -37,16 +43,17 @@ gcloud iam service-accounts keys create ~/key.json --iam-account $service_acc_em
# activate the service account using the key
gcloud auth activate-service-account --key-file ~/key.json

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

# install needed Google client libraries
virtualenv -p python3 myenv
source myenv/bin/activate
sleep 2

pip install google
pip install google-cloud-retail
pip install google-cloud.storage
pip install google-cloud.bigquery

echo "Your working environment is set up now!"
echo ========================================
echo "The Google Cloud setup is completed."
echo "Please proceed with the Tutorial steps"
echo ========================================
19 changes: 11 additions & 8 deletions packages/google-cloud-retail/samples/interactive-tutorials/user_import_data_to_catalog.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,20 +14,23 @@
# See the License for the specific language governing permissions and
# limitations under the License.

# Change the working directory
current_path=$(pwd)
temp_path="${current_path%cloudshell_open*}"
full_path=$temp_path"cloudshell_open/python-retail/samples/interactive-tutorials/product"
cd $full_path
# set the service account key as a GOOGLE_APPLICATION_CREDENTIALS
export GOOGLE_APPLICATION_CREDENTIALS=~/key.json

# activate the python virtual env
source ~/cloudshell_open/myenv/bin/activate

# Create a GCS bucket and upload the product data to the bucket
output=$(python setup_product/products_create_gcs_bucket.py)
output=$(python ~/cloudshell_open/python-retail/samples/interactive-tutorials/product/setup_product/products_create_gcs_bucket.py)

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

# Import products to the Retail catalog
python import_products_gcs.py
echo "Products are successfully imported to catalog"
python ~/cloudshell_open/python-retail/samples/interactive-tutorials/product/import_products_gcs.py

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

0 comments on commit 4e7a806

Please sign in to comment.