docs(samples): add samples for write/rejoin/purge user events (#157)

* feat: User Events: write/rejoin/purge

* 🦉 Updates from OwlBot

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* lint fix

* change the copyright year

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* fix tests

* remove endpoint

* 🦉 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: Anthonios Partheniou <partheniou@google.com>

samples/interactive-tutorials/events/noxfile_config.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Google LLC
+# Copyright 2022 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -24,7 +24,6 @@
     # to 'PROJECT_NUMBER' if you want to opt in using a
     # build specific Cloud project. You can also use your own string
     # to use your own Cloud project.
-    # 'gcloud_project_env': 'GOOGLE_CLOUD_PROJECT',
     "gcloud_project_env": "GOOGLE_CLOUD_PROJECT",
     # A dictionary you want to inject into your test. Don't put any
     # secrets here. These values will override predefined values.

samples/interactive-tutorials/events/purge_user_event.py

@@ -0,0 +1,57 @@
+# 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.
+
+
+# [START retail_purge_user_event]
+# Import user events into a catalog from inline source using Retail API
+#
+import os
+
+from google.cloud.retail import PurgeUserEventsRequest, UserEventServiceClient
+
+from setup_events.setup_cleanup import write_user_event
+
+project_id = os.getenv("GOOGLE_CLOUD_PROJECT")
+
+default_catalog = "projects/{0}/locations/global/catalogs/default_catalog".format(
+    project_id
+)
+visitor_id = "test_visitor_id"
+
+
+# get purge user event request
+def get_purge_user_event_request():
+    purge_user_event_request = PurgeUserEventsRequest()
+    # TO CHECK ERROR HANDLING SET INVALID FILTER HERE:
+    purge_user_event_request.filter = 'visitorId="{}"'.format(visitor_id)
+    purge_user_event_request.parent = default_catalog
+    purge_user_event_request.force = True
+    print("---purge user events request---")
+    print(purge_user_event_request)
+    return purge_user_event_request
+
+
+# call the Retail API to purge user event
+def call_purge_user_events():
+    purge_operation = UserEventServiceClient().purge_user_events(
+        get_purge_user_event_request()
+    )
+
+    print("---the purge operation was started:----")
+    print(purge_operation.operation.name)
+
+
+write_user_event(visitor_id)
+call_purge_user_events()
+# [END retail_purge_user_event]

samples/interactive-tutorials/events/purge_user_event_test.py

@@ -0,0 +1,39 @@
+# 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.
+
+import re
+import subprocess
+
+
+def test_create_product():
+    output = str(subprocess.check_output("python purge_user_event.py", shell=True))
+
+    assert re.match(".*the user event is written.*", output)
+    assert re.match(
+        '.*purge user events request.*?parent: "projects/.*?/locations/global/catalogs/default_catalog.*',
+        output,
+    )
+    assert re.match(
+        '.*purge user events request.*?filter: "visitorId=.*?test_visitor_id.*?".*',
+        output,
+    )
+    assert re.match(
+        '.*purge user events request.*?parent: "projects/.*?/locations/global/catalogs/default_catalog.*',
+        output,
+    )
+    assert re.match(".*purge user events request.*?force: true.*", output)
+    assert re.match(
+        ".*the purge operation was started.*?projects/.*?/locations/global/catalogs/default_catalog/operations/purge-user-events.*",
+        output,
+    )

samples/interactive-tutorials/events/rejoin_user_event.py

@@ -0,0 +1,61 @@
+# 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.
+
+
+# [START retail_rejoin_user_event]
+# Import user events into a catalog from inline source using Retail API
+#
+import os
+
+from google.cloud.retail import RejoinUserEventsRequest, UserEventServiceClient
+
+from setup_events.setup_cleanup import purge_user_event, write_user_event
+
+project_id = os.getenv("GOOGLE_CLOUD_PROJECT")
+
+default_catalog = "projects/{0}/locations/global/catalogs/default_catalog".format(
+    project_id
+)
+visitor_id = "test_visitor_id"
+
+
+# get rejoin user event request
+def get_rejoin_user_event_request():
+    # TO CHECK THE ERROR HANDLING TRY TO PASS INVALID CATALOG:
+    # default_catalog = "projects/{0}/locations/global/catalogs/invalid_catalog".format(project_number)
+    rejoin_user_event_request = RejoinUserEventsRequest()
+    rejoin_user_event_request.parent = default_catalog
+    rejoin_user_event_request.user_event_rejoin_scope = (
+        RejoinUserEventsRequest.UserEventRejoinScope.UNJOINED_EVENTS
+    )
+    print("---rejoin user events request---")
+    print(rejoin_user_event_request)
+    return rejoin_user_event_request
+
+
+# call the Retail API to rejoin user event
+def call_rejoin_user_events():
+    rejoin_operation = UserEventServiceClient().rejoin_user_events(
+        get_rejoin_user_event_request()
+    )
+
+    print("---the rejoin operation was started:----")
+    print(rejoin_operation.operation.name)
+
+
+write_user_event(visitor_id)
+call_rejoin_user_events()
+purge_user_event(visitor_id)
+
+# [END retail_rejoin_user_event]

samples/interactive-tutorials/events/rejoin_user_event_test.py

@@ -0,0 +1,38 @@
+# 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.
+
+import re
+import subprocess
+
+
+def test_create_product():
+    output = str(subprocess.check_output("python rejoin_user_event.py", shell=True))
+
+    assert re.match(".*the user event is written.*", output)
+    assert re.match(
+        '.*rejoin user events request.*?parent: "projects/.*?/locations/global/catalogs/default_catalog.*',
+        output,
+    )
+    assert re.match(
+        ".*rejoin user events request.*?user_event_rejoin_scope: UNJOINED_EVENTS.*",
+        output,
+    )
+    assert re.match(
+        ".*the rejoin operation was started.*?projects/.*?/locations/global/catalogs/default_catalog/operations/rejoin-user-events.*",
+        output,
+    )
+    assert re.match(
+        ".*the purge operation was started.*?projects/.*?/locations/global/catalogs/default_catalog/operations/purge-user-events.*",
+        output,
+    )

samples/interactive-tutorials/events/requirements.txt

@@ -1,4 +1,4 @@
 google==3.0.0
 google-cloud-retail==1.3.0
 google-cloud-storage==2.1.0
-google-cloud-bigquery==2.33.0
+google-cloud-bigquery==2.33.0

samples/interactive-tutorials/events/write_user_event.py

@@ -0,0 +1,77 @@
+# 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.
+
+
+# [START retail_write_user_event]
+# Import user events into a catalog from inline source using Retail API
+#
+import datetime
+import os
+
+from google.cloud.retail import UserEvent, UserEventServiceClient, WriteUserEventRequest
+from google.protobuf.timestamp_pb2 import Timestamp
+
+from setup_events.setup_cleanup import purge_user_event
+
+project_id = os.getenv("GOOGLE_CLOUD_PROJECT")
+
+default_catalog = "projects/{0}/locations/global/catalogs/default_catalog".format(
+    project_id
+)
+visitor_id = "test_visitor_id"
+
+
+# get user event
+def get_user_event():
+    timestamp = Timestamp()
+    timestamp.seconds = int(datetime.datetime.now().timestamp())
+
+    user_event = UserEvent()
+    user_event.event_type = "home-page-view"
+    user_event.visitor_id = visitor_id
+    user_event.event_time = timestamp
+
+    print(user_event)
+    return user_event
+
+
+# get write user event request
+def get_write_event_request(user_event):
+    # TO CHECK THE ERROR HANDLING TRY TO PASS INVALID CATALOG:
+    # default_catalog = "projects/{0}/locations/global/catalogs/invalid_catalog"
+    # .format(project_number)
+    write_user_event_request = WriteUserEventRequest()
+    write_user_event_request.user_event = user_event
+    write_user_event_request.parent = default_catalog
+
+    print("---write user event request---")
+    print(write_user_event_request)
+
+    return write_user_event_request
+
+
+# call the Retail API to write user event
+def write_user_event():
+    write_user_event_request = get_write_event_request(get_user_event())
+    user_event = UserEventServiceClient().write_user_event(write_user_event_request)
+
+    print("---written user event:---")
+    print(user_event)
+    return user_event
+
+
+write_user_event()
+purge_user_event(visitor_id)
+
+# [END retail_write_user_event]

samples/interactive-tutorials/events/write_user_event_test.py

@@ -0,0 +1,27 @@
+# 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.
+
+import re
+import subprocess
+
+
+def test_create_product():
+    output = str(subprocess.check_output("python write_user_event.py", shell=True))
+
+    assert re.match(
+        '.*write user event request.*?user_event.*?event_type: "home-page-view".*',
+        output,
+    )
+    assert re.match('.*written user event.*?event_type: "home-page-view".*', output)
+    assert re.match('.*written user event.*?visitor_id: "test_visitor_id".*', output)