1// Copyright 2021 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.cloud.retail.v2;
18
19import "google/api/annotations.proto";
20import "google/api/client.proto";
21import "google/api/field_behavior.proto";
22import "google/api/httpbody.proto";
23import "google/api/resource.proto";
24import "google/cloud/retail/v2/import_config.proto";
25import "google/cloud/retail/v2/purge_config.proto";
26import "google/cloud/retail/v2/user_event.proto";
27import "google/longrunning/operations.proto";
28
29option csharp_namespace = "Google.Cloud.Retail.V2";
30option go_package = "cloud.google.com/go/retail/apiv2/retailpb;retailpb";
31option java_multiple_files = true;
32option java_outer_classname = "UserEventServiceProto";
33option java_package = "com.google.cloud.retail.v2";
34option objc_class_prefix = "RETAIL";
35option php_namespace = "Google\\Cloud\\Retail\\V2";
36option ruby_package = "Google::Cloud::Retail::V2";
37
38// Service for ingesting end user actions on the customer website.
39service UserEventService {
40  option (google.api.default_host) = "retail.googleapis.com";
41  option (google.api.oauth_scopes) =
42      "https://www.googleapis.com/auth/cloud-platform";
43
44  // Writes a single user event.
45  rpc WriteUserEvent(WriteUserEventRequest) returns (UserEvent) {
46    option (google.api.http) = {
47      post: "/v2/{parent=projects/*/locations/*/catalogs/*}/userEvents:write"
48      body: "user_event"
49    };
50  }
51
52  // Writes a single user event from the browser. This uses a GET request to
53  // due to browser restriction of POST-ing to a 3rd party domain.
54  //
55  // This method is used only by the Retail API JavaScript pixel and Google Tag
56  // Manager. Users should not call this method directly.
57  rpc CollectUserEvent(CollectUserEventRequest) returns (google.api.HttpBody) {
58    option (google.api.http) = {
59      get: "/v2/{parent=projects/*/locations/*/catalogs/*}/userEvents:collect"
60    };
61  }
62
63  // Deletes permanently all user events specified by the filter provided.
64  // Depending on the number of events specified by the filter, this operation
65  // could take hours or days to complete. To test a filter, use the list
66  // command first.
67  rpc PurgeUserEvents(PurgeUserEventsRequest)
68      returns (google.longrunning.Operation) {
69    option (google.api.http) = {
70      post: "/v2/{parent=projects/*/locations/*/catalogs/*}/userEvents:purge"
71      body: "*"
72    };
73    option (google.longrunning.operation_info) = {
74      response_type: "google.cloud.retail.v2.PurgeUserEventsResponse"
75      metadata_type: "google.cloud.retail.v2.PurgeMetadata"
76    };
77  }
78
79  // Bulk import of User events. Request processing might be
80  // synchronous. Events that already exist are skipped.
81  // Use this method for backfilling historical user events.
82  //
83  // `Operation.response` is of type `ImportResponse`. Note that it is
84  // possible for a subset of the items to be successfully inserted.
85  // `Operation.metadata` is of type `ImportMetadata`.
86  rpc ImportUserEvents(ImportUserEventsRequest)
87      returns (google.longrunning.Operation) {
88    option (google.api.http) = {
89      post: "/v2/{parent=projects/*/locations/*/catalogs/*}/userEvents:import"
90      body: "*"
91    };
92    option (google.longrunning.operation_info) = {
93      response_type: "google.cloud.retail.v2.ImportUserEventsResponse"
94      metadata_type: "google.cloud.retail.v2.ImportMetadata"
95    };
96  }
97
98  // Starts a user-event rejoin operation with latest product catalog. Events
99  // are not annotated with detailed product information for products that are
100  // missing from the catalog when the user event is ingested. These
101  // events are stored as unjoined events with limited usage on training and
102  // serving. You can use this method to start a join operation on specified
103  // events with the latest version of product catalog. You can also use this
104  // method to correct events joined with the wrong product catalog. A rejoin
105  // operation can take hours or days to complete.
106  rpc RejoinUserEvents(RejoinUserEventsRequest)
107      returns (google.longrunning.Operation) {
108    option (google.api.http) = {
109      post: "/v2/{parent=projects/*/locations/*/catalogs/*}/userEvents:rejoin"
110      body: "*"
111    };
112    option (google.longrunning.operation_info) = {
113      response_type: "RejoinUserEventsResponse"
114      metadata_type: "RejoinUserEventsMetadata"
115    };
116  }
117}
118
119// Request message for WriteUserEvent method.
120message WriteUserEventRequest {
121  // Required. The parent catalog resource name, such as
122  // `projects/1234/locations/global/catalogs/default_catalog`.
123  string parent = 1 [(google.api.field_behavior) = REQUIRED];
124
125  // Required. User event to write.
126  UserEvent user_event = 2 [(google.api.field_behavior) = REQUIRED];
127
128  // If set to true, the user event will be written asynchronously after
129  // validation, and the API will respond without waiting for the write.
130  // Therefore, silent failures can occur even if the API returns success. In
131  // case of silent failures, error messages can be found in Stackdriver logs.
132  bool write_async = 3;
133}
134
135// Request message for CollectUserEvent method.
136message CollectUserEventRequest {
137  // The rule that can convert the raw_json to a user event. It is needed
138  // only when the raw_json is set.
139  oneof conversion_rule {
140    // The prebuilt rule name that can convert a specific type of raw_json.
141    // For example: "ga4_bq" rule for the GA4 user event schema.
142    string prebuilt_rule = 6;
143  }
144
145  // Required. The parent catalog name, such as
146  // `projects/1234/locations/global/catalogs/default_catalog`.
147  string parent = 1 [(google.api.field_behavior) = REQUIRED];
148
149  // Required. URL encoded UserEvent proto with a length limit of 2,000,000
150  // characters.
151  string user_event = 2 [(google.api.field_behavior) = REQUIRED];
152
153  // The URL including cgi-parameters but excluding the hash fragment with a
154  // length limit of 5,000 characters. This is often more useful than the
155  // referer URL, because many browsers only send the domain for 3rd party
156  // requests.
157  string uri = 3;
158
159  // The event timestamp in milliseconds. This prevents browser caching of
160  // otherwise identical get requests. The name is abbreviated to reduce the
161  // payload bytes.
162  int64 ets = 4;
163
164  // An arbitrary serialized JSON string that contains necessary information
165  // that can comprise a user event. When this field is specified, the
166  // user_event field will be ignored. Note: line-delimited JSON is not
167  // supported, a single JSON only.
168  string raw_json = 5;
169}
170
171// Request message for RejoinUserEvents method.
172message RejoinUserEventsRequest {
173  // The scope of user events to be rejoined with the latest product catalog.
174  // If the rejoining aims at reducing number of unjoined events, set
175  // `UserEventRejoinScope` to `UNJOINED_EVENTS`.
176  // If the rejoining aims at correcting product catalog information in joined
177  // events, set `UserEventRejoinScope` to `JOINED_EVENTS`.
178  // If all events needs to be rejoined, set `UserEventRejoinScope` to
179  // `USER_EVENT_REJOIN_SCOPE_UNSPECIFIED`.
180  enum UserEventRejoinScope {
181    // Rejoin all events with the latest product catalog, including both joined
182    // events and unjoined events.
183    USER_EVENT_REJOIN_SCOPE_UNSPECIFIED = 0;
184
185    // Only rejoin joined events with the latest product catalog.
186    JOINED_EVENTS = 1;
187
188    // Only rejoin unjoined events with the latest product catalog.
189    UNJOINED_EVENTS = 2;
190  }
191
192  // Required. The parent catalog resource name, such as
193  // `projects/1234/locations/global/catalogs/default_catalog`.
194  string parent = 1 [(google.api.field_behavior) = REQUIRED];
195
196  // The type of the user event rejoin to define the scope and range of the user
197  // events to be rejoined with the latest product catalog. Defaults to
198  // `USER_EVENT_REJOIN_SCOPE_UNSPECIFIED` if this field is not set, or set to
199  // an invalid integer value.
200  UserEventRejoinScope user_event_rejoin_scope = 2;
201}
202
203// Response message for `RejoinUserEvents` method.
204message RejoinUserEventsResponse {
205  // Number of user events that were joined with latest product catalog.
206  int64 rejoined_user_events_count = 1;
207}
208
209// Metadata for `RejoinUserEvents` method.
210message RejoinUserEventsMetadata {}
211