Skip to content

Commit 171282a

Browse files
sborisenkoxgcf-owl-bot[bot]tetiana-karasovakweinmeister
authored
chore(samples): Code samples for Retail Tutorials. Search service samples (part 1) (#289)
* Configure modules settings. * Add search tutorials. * 🦉 Updates from OwlBot See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * Minor fixes. * 🦉 Updates from OwlBot See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * 🦉 Updates from OwlBot See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * Minor fix. * Replace PROJECT_NUMBER with PROJECT_ID * kokoro configuration added * update tutorials README * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: tetiana-karasova <tetiana.karasova@gmail.com> Co-authored-by: Karl Weinmeister <11586922+kweinmeister@users.noreply.github.com>
1 parent 792a74c commit 171282a

File tree

14 files changed

+578
-2
lines changed

14 files changed

+578
-2
lines changed

‎retail/interactive-tutorials/README.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
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+
<!--TODO(tkarasova) update the link to the tutorials when will be published-->
40+
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.
42+
43+
The code samples in the directory **python-retail/samples/interactive-tutorials** are explicitly created for use with the Retail Interactive Tutorials.
44+
45+
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.
46+
47+
### Select your project and enable the Retail API
48+
49+
Google Cloud organizes resources into projects. This lets you
50+
collect all the related resources for a single application in one place.
51+
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).
54+
55+
After the project is created, set your PROJECT_ID to a ```project``` variable.
56+
1. Run the following command in Terminal:
57+
```bash
58+
gcloud config set project <YOUR_PROJECT_ID>
59+
```
60+
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/).
62+
63+
### Create service account
64+
65+
To access the Retail API, you must create a service account.
66+
67+
1. To create a service account, follow this [instruction](https://cloud.google.com/retail/docs/setting-up#service-account)
68+
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+
72+
1. Copy the service account email in the Principal field.
73+
74+
### Set up authentication
75+
76+
To run a code sample from the Cloud Shell, you need to be authenticated using the service account credentials.
77+
78+
1. Login with your user credentials.
79+
```bash
80+
gcloud auth login
81+
```
82+
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.
84+
85+
1. Provide the Google Auth Library with access to your credentials and paste the code from the browser to the Terminal.
86+
87+
1. Upload your service account key JSON file and use it to activate the service account:
88+
89+
```bash
90+
gcloud iam service-accounts keys create ~/key.json --iam-account <YOUR_SERVICE_ACCOUNT_EMAIL>
91+
```
92+
93+
```bash
94+
gcloud auth activate-service-account --key-file ~/key.json
95+
```
96+
97+
1. To request the Retail API, set your service account key JSON file as the GOOGLE_APPLICATION_CREDENTIALS environment variable :
98+
```bash
99+
export GOOGLE_APPLICATION_CREDENTIALS=~/key.json
100+
```
101+
102+
### Set the GOOGLE_CLOUD_PROJECT environment variable
103+
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.
105+
106+
1. Find the project ID in the Project Info card displayed on **Home/Dashboard**.
107+
108+
1. Set the **project_id** with the following command:
109+
```bash
110+
export GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
111+
112+
## Import Catalog Data
113+
114+
This step is required if this is the first Retail API Tutorial you run.
115+
Otherwise, you can skip it.
116+
117+
### Upload catalog data to Cloud Storage
118+
119+
There is a JSON file with valid products prepared in the `product` directory:
120+
`product/resources/products.json`.
121+
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.
123+
124+
In your own project, create a Cloud Storage bucket and put the JSON file there.
125+
The bucket name must be unique. For convenience, you can name it `<YOUR_PROJECT_ID>_<TIMESTAMP>`.
126+
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-->
129+
```bash
130+
pmvn compile exec:java -Dexec.mainClass=CreateGcsBucket
131+
```
132+
133+
Now you can see the bucket is created in the [Cloud Storage](https://console.cloud.google.com/storage/browser), and the files are uploaded.
134+
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`:
136+
137+
```bash
138+
export BUCKET_NAME=<YOUR_BUCKET_NAME>
139+
```
140+
141+
### Import products to the Retail Catalog
142+
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+
```
148+
149+
### Running code samples
150+
151+
Use maven command to run specific code sample:
152+
153+
```
154+
mvn compile exec:java -Dexec.mainClass="package.CodeSampleClass"
155+
```
156+
157+
### Running unit tests
158+
159+
Use maven command to run specific unit test class:
160+
161+
```
162+
mvn test -Dtest=TestClassName
163+
```
164+
165+
Use maven command to run all unit tests:
166+
167+
```
168+
mvn test
169+
```

‎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‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,4 +66,4 @@
6666
</plugin>
6767
</plugins>
6868
</build>
69-
</project>
69+
</project>

‎retail/interactive-tutorials/src/main/java/search/SearchSimpleQuery.java‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
/*
2+
* Copyright 2022 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
// [START retail_search_for_products_with_query_parameter]
18+
19+
/*
20+
* Call Retail API to search for a products in a catalog
21+
* using only search query.
22+
*/
23+
24+
package search;
25+
26+
import com.google.cloud.retail.v2.SearchRequest;
27+
import com.google.cloud.retail.v2.SearchResponse;
28+
import com.google.cloud.retail.v2.SearchServiceClient;
29+
import java.io.IOException;
30+
import java.util.UUID;
31+
32+
public class SearchSimpleQuery {
33+
34+
public static void main(String[] args) throws IOException {
35+
// TODO(developer): Replace these variables before running the sample.
36+
String projectId = System.getenv("PROJECT_ID");
37+
String defaultCatalogName =
38+
String.format("projects/%s/locations/global/catalogs/default_catalog", projectId);
39+
String defaultSearchPlacementName = defaultCatalogName + "/placements/default_search";
40+
41+
getSearchResponse(defaultSearchPlacementName);
42+
}
43+
44+
public static SearchResponse getSearchResponse(String defaultSearchPlacementName)
45+
throws IOException {
46+
// TRY DIFFERENT QUERY PHRASES HERE:
47+
String queryPhrase = "Hoodie";
48+
String visitorId = UUID.randomUUID().toString();
49+
int pageSize = 10;
50+
51+
SearchRequest searchRequest =
52+
SearchRequest.newBuilder()
53+
.setPlacement(defaultSearchPlacementName)
54+
.setQuery(queryPhrase)
55+
.setVisitorId(visitorId)
56+
.setPageSize(pageSize)
57+
.build();
58+
System.out.println("Search request: " + searchRequest);
59+
60+
try (SearchServiceClient client = SearchServiceClient.create()) {
61+
SearchResponse searchResponse = client.search(searchRequest).getPage().getResponse();
62+
System.out.println("Search response: " + searchResponse);
63+
64+
return searchResponse;
65+
}
66+
}
67+
}
68+
69+
// [END retail_search_for_products_with_query_parameter]

‎retail/interactive-tutorials/src/main/java/search/SearchWithBoostSpec.java‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
/*
2+
* Copyright 2022 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
// [START retail_search_product_with_boost_spec]
18+
19+
/*
20+
* Call Retail API to search for a products in a catalog, rerank the
21+
* results boosting or burying the products that match defined condition.
22+
*/
23+
24+
package search;
25+
26+
import com.google.cloud.retail.v2.SearchRequest;
27+
import com.google.cloud.retail.v2.SearchRequest.BoostSpec;
28+
import com.google.cloud.retail.v2.SearchRequest.BoostSpec.ConditionBoostSpec;
29+
import com.google.cloud.retail.v2.SearchResponse;
30+
import com.google.cloud.retail.v2.SearchServiceClient;
31+
import java.io.IOException;
32+
import java.util.UUID;
33+
34+
public class SearchWithBoostSpec {
35+
36+
public static void main(String[] args) throws IOException {
37+
// TODO(developer): Replace these variables before running the sample.
38+
String projectId = System.getenv("PROJECT_ID");
39+
String defaultCatalogName =
40+
String.format("projects/%s/locations/global/catalogs/default_catalog", projectId);
41+
String defaultSearchPlacementName = defaultCatalogName + "/placements/default_search";
42+
43+
getSearchResponse(defaultSearchPlacementName);
44+
}
45+
46+
public static SearchResponse getSearchResponse(String defaultSearchPlacementName)
47+
throws IOException {
48+
// TRY DIFFERENT CONDITIONS HERE:
49+
String searchQuery = "Tee";
50+
String condition = "(colorFamilies: ANY(\"Blue\"))";
51+
float boost = 0.0f;
52+
int pageSize = 10;
53+
String visitorId = UUID.randomUUID().toString();
54+
55+
BoostSpec boostSpec =
56+
BoostSpec.newBuilder()
57+
.addConditionBoostSpecs(
58+
ConditionBoostSpec.newBuilder().setCondition(condition).setBoost(boost).build())
59+
.build();
60+
61+
SearchRequest searchRequest =
62+
SearchRequest.newBuilder()
63+
.setPlacement(defaultSearchPlacementName)
64+
.setQuery(searchQuery)
65+
.setVisitorId(visitorId)
66+
.setBoostSpec(boostSpec)
67+
.setPageSize(pageSize)
68+
.build();
69+
System.out.println("Search request: " + searchRequest);
70+
71+
try (SearchServiceClient client = SearchServiceClient.create()) {
72+
SearchResponse searchResponse = client.search(searchRequest).getPage().getResponse();
73+
System.out.println("Search response: " + searchResponse);
74+
75+
return searchResponse;
76+
}
77+
}
78+
}
79+
80+
// [END retail_search_product_with_boost_spec]

‎retail/interactive-tutorials/src/main/java/search/SearchWithFacetSpec.java‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
/*
2+
* Copyright 2022 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
// [START retail_search_product_with_facet_spec]
18+
19+
package search;
20+
21+
import com.google.cloud.retail.v2.SearchRequest;
22+
import com.google.cloud.retail.v2.SearchRequest.FacetSpec;
23+
import com.google.cloud.retail.v2.SearchRequest.FacetSpec.FacetKey;
24+
import com.google.cloud.retail.v2.SearchResponse;
25+
import com.google.cloud.retail.v2.SearchServiceClient;
26+
import java.io.IOException;
27+
import java.util.UUID;
28+
29+
public class SearchWithFacetSpec {
30+
31+
public static void main(String[] args) throws IOException {
32+
// TODO(developer): Replace these variables before running the sample.
33+
String projectId = System.getenv("PROJECT_ID");
34+
String defaultCatalogName =
35+
String.format("projects/%s/locations/global/catalogs/default_catalog", projectId);
36+
String defaultSearchPlacementName = defaultCatalogName + "/placements/default_search";
37+
38+
getSearchResponse(defaultSearchPlacementName);
39+
}
40+
41+
public static SearchResponse getSearchResponse(String defaultSearchPlacementName)
42+
throws IOException {
43+
// TRY DIFFERENT CONDITIONS HERE:
44+
String searchQuery = "Tee";
45+
String facetKeyParam = "colorFamilies";
46+
int pageSize = 10;
47+
String visitorId = UUID.randomUUID().toString();
48+
49+
FacetKey facetKey = FacetKey.newBuilder().setKey(facetKeyParam).build();
50+
FacetSpec facetSpec = FacetSpec.newBuilder().setFacetKey(facetKey).build();
51+
52+
SearchRequest searchRequest =
53+
SearchRequest.newBuilder()
54+
.setPlacement(defaultSearchPlacementName)
55+
.setQuery(searchQuery)
56+
.setVisitorId(visitorId)
57+
.addFacetSpecs(facetSpec)
58+
.setPageSize(pageSize)
59+
.build();
60+
System.out.println("Search request: " + searchRequest);
61+
62+
try (SearchServiceClient client = SearchServiceClient.create()) {
63+
SearchResponse searchResponse = client.search(searchRequest).getPage().getResponse();
64+
System.out.println("Search response: " + searchResponse);
65+
66+
return searchResponse;
67+
}
68+
}
69+
}
70+
71+
// [END retail_search_product_with_facet_spec]

0 commit comments

Comments
 (0)