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.v2beta; 18 19import "google/api/annotations.proto"; 20import "google/api/client.proto"; 21import "google/api/field_behavior.proto"; 22import "google/api/resource.proto"; 23import "google/cloud/retail/v2beta/control.proto"; 24import "google/protobuf/empty.proto"; 25import "google/protobuf/field_mask.proto"; 26 27option csharp_namespace = "Google.Cloud.Retail.V2Beta"; 28option go_package = "cloud.google.com/go/retail/apiv2beta/retailpb;retailpb"; 29option java_multiple_files = true; 30option java_outer_classname = "ControlServiceProto"; 31option java_package = "com.google.cloud.retail.v2beta"; 32option objc_class_prefix = "RETAIL"; 33option php_namespace = "Google\\Cloud\\Retail\\V2beta"; 34option ruby_package = "Google::Cloud::Retail::V2beta"; 35 36// Service for modifying Control. 37service ControlService { 38 option (google.api.default_host) = "retail.googleapis.com"; 39 option (google.api.oauth_scopes) = 40 "https://www.googleapis.com/auth/cloud-platform"; 41 42 // Creates a Control. 43 // 44 // If the [Control][google.cloud.retail.v2beta.Control] to create already 45 // exists, an ALREADY_EXISTS error is returned. 46 rpc CreateControl(CreateControlRequest) returns (Control) { 47 option (google.api.http) = { 48 post: "/v2beta/{parent=projects/*/locations/*/catalogs/*}/controls" 49 body: "control" 50 }; 51 option (google.api.method_signature) = "parent,control,control_id"; 52 } 53 54 // Deletes a Control. 55 // 56 // If the [Control][google.cloud.retail.v2beta.Control] to delete does not 57 // exist, a NOT_FOUND error is returned. 58 rpc DeleteControl(DeleteControlRequest) returns (google.protobuf.Empty) { 59 option (google.api.http) = { 60 delete: "/v2beta/{name=projects/*/locations/*/catalogs/*/controls/*}" 61 }; 62 option (google.api.method_signature) = "name"; 63 } 64 65 // Updates a Control. 66 // 67 // [Control][google.cloud.retail.v2beta.Control] cannot be set to a different 68 // oneof field, if so an INVALID_ARGUMENT is returned. If the 69 // [Control][google.cloud.retail.v2beta.Control] to update does not exist, a 70 // NOT_FOUND error is returned. 71 rpc UpdateControl(UpdateControlRequest) returns (Control) { 72 option (google.api.http) = { 73 patch: "/v2beta/{control.name=projects/*/locations/*/catalogs/*/controls/*}" 74 body: "control" 75 }; 76 option (google.api.method_signature) = "control,update_mask"; 77 } 78 79 // Gets a Control. 80 rpc GetControl(GetControlRequest) returns (Control) { 81 option (google.api.http) = { 82 get: "/v2beta/{name=projects/*/locations/*/catalogs/*/controls/*}" 83 }; 84 option (google.api.method_signature) = "name"; 85 } 86 87 // Lists all Controls by their parent 88 // [Catalog][google.cloud.retail.v2beta.Catalog]. 89 rpc ListControls(ListControlsRequest) returns (ListControlsResponse) { 90 option (google.api.http) = { 91 get: "/v2beta/{parent=projects/*/locations/*/catalogs/*}/controls" 92 }; 93 option (google.api.method_signature) = "parent"; 94 } 95} 96 97// Request for CreateControl method. 98message CreateControlRequest { 99 // Required. Full resource name of parent catalog. Format: 100 // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}` 101 string parent = 1 [ 102 (google.api.field_behavior) = REQUIRED, 103 (google.api.resource_reference) = { type: "retail.googleapis.com/Catalog" } 104 ]; 105 106 // Required. The Control to create. 107 Control control = 2 [(google.api.field_behavior) = REQUIRED]; 108 109 // Required. The ID to use for the Control, which will become the final 110 // component of the Control's resource name. 111 // 112 // This value should be 4-63 characters, and valid characters 113 // are /[a-z][0-9]-_/. 114 string control_id = 3 [(google.api.field_behavior) = REQUIRED]; 115} 116 117// Request for UpdateControl method. 118message UpdateControlRequest { 119 // Required. The Control to update. 120 Control control = 1 [(google.api.field_behavior) = REQUIRED]; 121 122 // Indicates which fields in the provided 123 // [Control][google.cloud.retail.v2beta.Control] to update. The following are 124 // NOT supported: 125 // 126 // * [Control.name][google.cloud.retail.v2beta.Control.name] 127 // 128 // If not set or empty, all supported fields are updated. 129 google.protobuf.FieldMask update_mask = 2; 130} 131 132// Request for DeleteControl method. 133message DeleteControlRequest { 134 // Required. The resource name of the Control to delete. Format: 135 // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/controls/{control_id}` 136 string name = 1 [ 137 (google.api.field_behavior) = REQUIRED, 138 (google.api.resource_reference) = { type: "retail.googleapis.com/Control" } 139 ]; 140} 141 142// Request for GetControl method. 143message GetControlRequest { 144 // Required. The resource name of the Control to get. Format: 145 // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/controls/{control_id}` 146 string name = 1 [ 147 (google.api.field_behavior) = REQUIRED, 148 (google.api.resource_reference) = { type: "retail.googleapis.com/Control" } 149 ]; 150} 151 152// Request for ListControls method. 153message ListControlsRequest { 154 // Required. The catalog resource name. Format: 155 // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}` 156 string parent = 1 [ 157 (google.api.field_behavior) = REQUIRED, 158 (google.api.resource_reference) = { type: "retail.googleapis.com/Catalog" } 159 ]; 160 161 // Optional. Maximum number of results to return. If unspecified, defaults 162 // to 50. Max allowed value is 1000. 163 int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL]; 164 165 // Optional. A page token, received from a previous `ListControls` call. 166 // Provide this to retrieve the subsequent page. 167 string page_token = 3 [(google.api.field_behavior) = OPTIONAL]; 168 169 // Optional. A filter to apply on the list results. Supported features: 170 // 171 // * List all the products under the parent branch if 172 // [filter][google.cloud.retail.v2beta.ListControlsRequest.filter] is unset. 173 // * List controls that are used in a single ServingConfig: 174 // 'serving_config = "boosted_home_page_cvr"' 175 string filter = 4 [(google.api.field_behavior) = OPTIONAL]; 176} 177 178// Response for ListControls method. 179message ListControlsResponse { 180 // All the Controls for a given catalog. 181 repeated Control controls = 1; 182 183 // Pagination token, if not returned indicates the last page. 184 string next_page_token = 2; 185} 186