1// Copyright 2023 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.ads.searchads360.v0.services; 18 19import "google/ads/searchads360/v0/common/metrics.proto"; 20import "google/ads/searchads360/v0/common/segments.proto"; 21import "google/ads/searchads360/v0/common/value.proto"; 22import "google/ads/searchads360/v0/enums/summary_row_setting.proto"; 23import "google/ads/searchads360/v0/resources/accessible_bidding_strategy.proto"; 24import "google/ads/searchads360/v0/resources/ad_group.proto"; 25import "google/ads/searchads360/v0/resources/ad_group_ad.proto"; 26import "google/ads/searchads360/v0/resources/ad_group_ad_label.proto"; 27import "google/ads/searchads360/v0/resources/ad_group_asset.proto"; 28import "google/ads/searchads360/v0/resources/ad_group_asset_set.proto"; 29import "google/ads/searchads360/v0/resources/ad_group_audience_view.proto"; 30import "google/ads/searchads360/v0/resources/ad_group_bid_modifier.proto"; 31import "google/ads/searchads360/v0/resources/ad_group_criterion.proto"; 32import "google/ads/searchads360/v0/resources/ad_group_criterion_label.proto"; 33import "google/ads/searchads360/v0/resources/ad_group_label.proto"; 34import "google/ads/searchads360/v0/resources/age_range_view.proto"; 35import "google/ads/searchads360/v0/resources/asset.proto"; 36import "google/ads/searchads360/v0/resources/asset_group.proto"; 37import "google/ads/searchads360/v0/resources/asset_group_asset.proto"; 38import "google/ads/searchads360/v0/resources/asset_group_listing_group_filter.proto"; 39import "google/ads/searchads360/v0/resources/asset_group_signal.proto"; 40import "google/ads/searchads360/v0/resources/asset_group_top_combination_view.proto"; 41import "google/ads/searchads360/v0/resources/asset_set.proto"; 42import "google/ads/searchads360/v0/resources/asset_set_asset.proto"; 43import "google/ads/searchads360/v0/resources/audience.proto"; 44import "google/ads/searchads360/v0/resources/bidding_strategy.proto"; 45import "google/ads/searchads360/v0/resources/campaign.proto"; 46import "google/ads/searchads360/v0/resources/campaign_asset.proto"; 47import "google/ads/searchads360/v0/resources/campaign_asset_set.proto"; 48import "google/ads/searchads360/v0/resources/campaign_audience_view.proto"; 49import "google/ads/searchads360/v0/resources/campaign_budget.proto"; 50import "google/ads/searchads360/v0/resources/campaign_criterion.proto"; 51import "google/ads/searchads360/v0/resources/campaign_label.proto"; 52import "google/ads/searchads360/v0/resources/cart_data_sales_view.proto"; 53import "google/ads/searchads360/v0/resources/conversion.proto"; 54import "google/ads/searchads360/v0/resources/conversion_action.proto"; 55import "google/ads/searchads360/v0/resources/conversion_custom_variable.proto"; 56import "google/ads/searchads360/v0/resources/customer.proto"; 57import "google/ads/searchads360/v0/resources/customer_asset.proto"; 58import "google/ads/searchads360/v0/resources/customer_asset_set.proto"; 59import "google/ads/searchads360/v0/resources/customer_client.proto"; 60import "google/ads/searchads360/v0/resources/customer_manager_link.proto"; 61import "google/ads/searchads360/v0/resources/dynamic_search_ads_search_term_view.proto"; 62import "google/ads/searchads360/v0/resources/gender_view.proto"; 63import "google/ads/searchads360/v0/resources/geo_target_constant.proto"; 64import "google/ads/searchads360/v0/resources/keyword_view.proto"; 65import "google/ads/searchads360/v0/resources/label.proto"; 66import "google/ads/searchads360/v0/resources/language_constant.proto"; 67import "google/ads/searchads360/v0/resources/location_view.proto"; 68import "google/ads/searchads360/v0/resources/product_bidding_category_constant.proto"; 69import "google/ads/searchads360/v0/resources/product_group_view.proto"; 70import "google/ads/searchads360/v0/resources/shopping_performance_view.proto"; 71import "google/ads/searchads360/v0/resources/user_list.proto"; 72import "google/ads/searchads360/v0/resources/visit.proto"; 73import "google/ads/searchads360/v0/resources/webpage_view.proto"; 74import "google/api/annotations.proto"; 75import "google/api/client.proto"; 76import "google/api/field_behavior.proto"; 77import "google/protobuf/field_mask.proto"; 78 79option csharp_namespace = "Google.Ads.SearchAds360.V0.Services"; 80option go_package = "google.golang.org/genproto/googleapis/ads/searchads360/v0/services;services"; 81option java_multiple_files = true; 82option java_outer_classname = "SearchAds360ServiceProto"; 83option java_package = "com.google.ads.searchads360.v0.services"; 84option objc_class_prefix = "GASA360"; 85option php_namespace = "Google\\Ads\\SearchAds360\\V0\\Services"; 86option ruby_package = "Google::Ads::SearchAds360::V0::Services"; 87 88// Proto file describing the SearchAds360Service. 89 90// Service to fetch data and metrics across resources. 91service SearchAds360Service { 92 option (google.api.default_host) = "searchads360.googleapis.com"; 93 option (google.api.oauth_scopes) = 94 "https://www.googleapis.com/auth/doubleclicksearch"; 95 96 // Returns all rows that match the search query. 97 // 98 // List of thrown errors: 99 // [AuthenticationError]() 100 // [AuthorizationError]() 101 // [HeaderError]() 102 // [InternalError]() 103 // [QueryError]() 104 // [QuotaError]() 105 // [RequestError]() 106 rpc Search(SearchSearchAds360Request) returns (SearchSearchAds360Response) { 107 option (google.api.http) = { 108 post: "/v0/customers/{customer_id=*}/searchAds360:search" 109 body: "*" 110 }; 111 option (google.api.method_signature) = "customer_id,query"; 112 } 113 114 // Returns all rows that match the search stream query. 115 // 116 // List of thrown errors: 117 // [AuthenticationError]() 118 // [AuthorizationError]() 119 // [HeaderError]() 120 // [InternalError]() 121 // [QueryError]() 122 // [QuotaError]() 123 // [RequestError]() 124 rpc SearchStream(SearchSearchAds360StreamRequest) 125 returns (stream SearchSearchAds360StreamResponse) { 126 option (google.api.http) = { 127 post: "/v0/customers/{customer_id=*}/searchAds360:searchStream" 128 body: "*" 129 }; 130 option (google.api.method_signature) = "customer_id,query"; 131 } 132} 133 134// Request message for 135// [SearchAds360Service.Search][google.ads.searchads360.v0.services.SearchAds360Service.Search]. 136message SearchSearchAds360Request { 137 // Required. The ID of the customer being queried. 138 string customer_id = 1 [(google.api.field_behavior) = REQUIRED]; 139 140 // Required. The query string. 141 string query = 2 [(google.api.field_behavior) = REQUIRED]; 142 143 // Token of the page to retrieve. If not specified, the first 144 // page of results will be returned. Use the value obtained from 145 // `next_page_token` in the previous response in order to request 146 // the next page of results. 147 string page_token = 3; 148 149 // Number of elements to retrieve in a single page. 150 // When too large a page is requested, the server may decide to 151 // further limit the number of returned resources. 152 int32 page_size = 4; 153 154 // If true, the request is validated but not executed. 155 bool validate_only = 5; 156 157 // If true, the total number of results that match the query ignoring the 158 // LIMIT clause will be included in the response. 159 // Default is false. 160 bool return_total_results_count = 7; 161 162 // Determines whether a summary row will be returned. By default, summary row 163 // is not returned. If requested, the summary row will be sent in a response 164 // by itself after all other query results are returned. 165 google.ads.searchads360.v0.enums.SummaryRowSettingEnum.SummaryRowSetting 166 summary_row_setting = 8; 167} 168 169// Response message for 170// [SearchAds360Service.Search][google.ads.searchads360.v0.services.SearchAds360Service.Search]. 171message SearchSearchAds360Response { 172 // The list of rows that matched the query. 173 repeated SearchAds360Row results = 1; 174 175 // Pagination token used to retrieve the next page of results. 176 // Pass the content of this string as the `page_token` attribute of 177 // the next request. `next_page_token` is not returned for the last 178 // page. 179 string next_page_token = 2; 180 181 // Total number of results that match the query ignoring the LIMIT 182 // clause. 183 int64 total_results_count = 3; 184 185 // FieldMask that represents what fields were requested by the user. 186 google.protobuf.FieldMask field_mask = 5; 187 188 // Summary row that contains summary of metrics in results. 189 // Summary of metrics means aggregation of metrics across all results, 190 // here aggregation could be sum, average, rate, etc. 191 SearchAds360Row summary_row = 6; 192 193 // The headers of the custom columns in the results. 194 repeated CustomColumnHeader custom_column_headers = 7; 195 196 // The headers of the conversion custom metrics in the results. 197 repeated ConversionCustomMetricHeader conversion_custom_metric_headers = 9; 198 199 // The headers of the conversion custom dimensions in the results. 200 repeated ConversionCustomDimensionHeader conversion_custom_dimension_headers = 201 10; 202 203 // The headers of the raw event conversion metrics in the results. 204 repeated RawEventConversionMetricHeader raw_event_conversion_metric_headers = 205 11; 206 207 // The headers of the raw event conversion dimensions in the results. 208 repeated RawEventConversionDimensionHeader 209 raw_event_conversion_dimension_headers = 12; 210} 211 212// Request message for 213// [SearchAds360Service.SearchStream][google.ads.searchads360.v0.services.SearchAds360Service.SearchStream]. 214message SearchSearchAds360StreamRequest { 215 // Required. The ID of the customer being queried. 216 string customer_id = 1 [(google.api.field_behavior) = REQUIRED]; 217 218 // Required. The query string. 219 string query = 2 [(google.api.field_behavior) = REQUIRED]; 220 221 // The number of rows that are returned in each stream response batch. 222 // When too large batch is requested, the server may decide to further limit 223 // the number of returned rows. 224 int32 batch_size = 4; 225 226 // Determines whether a summary row will be returned. By default, summary row 227 // is not returned. If requested, the summary row will be sent in a response 228 // by itself after all other query results are returned. 229 google.ads.searchads360.v0.enums.SummaryRowSettingEnum.SummaryRowSetting 230 summary_row_setting = 3; 231} 232 233// Response message for 234// [SearchAds360Service.SearchStream][google.ads.searchads360.v0.services.SearchAds360Service.SearchStream]. 235message SearchSearchAds360StreamResponse { 236 // The list of rows that matched the query. 237 repeated SearchAds360Row results = 1; 238 239 // FieldMask that represents what fields were requested by the user. 240 google.protobuf.FieldMask field_mask = 2; 241 242 // Summary row that contains summary of metrics in results. 243 // Summary of metrics means aggregation of metrics across all results, 244 // here aggregation could be sum, average, rate, etc. 245 SearchAds360Row summary_row = 3; 246 247 // The headers of the custom columns in the results. 248 repeated CustomColumnHeader custom_column_headers = 5; 249 250 // The headers of the conversion custom metrics in the results. 251 repeated ConversionCustomMetricHeader conversion_custom_metric_headers = 7; 252 253 // The headers of the conversion custom dimension in the results. 254 repeated ConversionCustomDimensionHeader conversion_custom_dimension_headers = 255 8; 256 257 // The headers of the raw event conversion metrics in the results. 258 repeated RawEventConversionMetricHeader raw_event_conversion_metric_headers = 259 9; 260 261 // The headers of the raw event conversion dimensions in the results. 262 repeated RawEventConversionDimensionHeader 263 raw_event_conversion_dimension_headers = 10; 264 265 // The unique id of the request that is used for debugging purposes. 266 string request_id = 4; 267} 268 269// A returned row from the query. 270message SearchAds360Row { 271 // The ad group referenced in the query. 272 google.ads.searchads360.v0.resources.AdGroup ad_group = 3; 273 274 // The ad referenced in the query. 275 google.ads.searchads360.v0.resources.AdGroupAd ad_group_ad = 16; 276 277 // The ad group ad label referenced in the query. 278 google.ads.searchads360.v0.resources.AdGroupAdLabel ad_group_ad_label = 120; 279 280 // The ad group asset referenced in the query. 281 google.ads.searchads360.v0.resources.AdGroupAsset ad_group_asset = 154; 282 283 // The ad group asset set referenced in the query. 284 google.ads.searchads360.v0.resources.AdGroupAssetSet ad_group_asset_set = 196; 285 286 // The ad group audience view referenced in the query. 287 google.ads.searchads360.v0.resources.AdGroupAudienceView 288 ad_group_audience_view = 57; 289 290 // The bid modifier referenced in the query. 291 google.ads.searchads360.v0.resources.AdGroupBidModifier 292 ad_group_bid_modifier = 24; 293 294 // The criterion referenced in the query. 295 google.ads.searchads360.v0.resources.AdGroupCriterion ad_group_criterion = 17; 296 297 // The ad group criterion label referenced in the query. 298 google.ads.searchads360.v0.resources.AdGroupCriterionLabel 299 ad_group_criterion_label = 121; 300 301 // The ad group label referenced in the query. 302 google.ads.searchads360.v0.resources.AdGroupLabel ad_group_label = 115; 303 304 // The age range view referenced in the query. 305 google.ads.searchads360.v0.resources.AgeRangeView age_range_view = 48; 306 307 // The asset referenced in the query. 308 google.ads.searchads360.v0.resources.Asset asset = 105; 309 310 // The asset group asset referenced in the query. 311 google.ads.searchads360.v0.resources.AssetGroupAsset asset_group_asset = 173; 312 313 // The asset group signal referenced in the query. 314 google.ads.searchads360.v0.resources.AssetGroupSignal asset_group_signal = 315 191; 316 317 // The asset group listing group filter referenced in the query. 318 google.ads.searchads360.v0.resources.AssetGroupListingGroupFilter 319 asset_group_listing_group_filter = 182; 320 321 // The asset group top combination view referenced in the query. 322 google.ads.searchads360.v0.resources.AssetGroupTopCombinationView 323 asset_group_top_combination_view = 199; 324 325 // The asset group referenced in the query. 326 google.ads.searchads360.v0.resources.AssetGroup asset_group = 172; 327 328 // The asset set asset referenced in the query. 329 google.ads.searchads360.v0.resources.AssetSetAsset asset_set_asset = 180; 330 331 // The asset set referenced in the query. 332 google.ads.searchads360.v0.resources.AssetSet asset_set = 179; 333 334 // The bidding strategy referenced in the query. 335 google.ads.searchads360.v0.resources.BiddingStrategy bidding_strategy = 18; 336 337 // The campaign budget referenced in the query. 338 google.ads.searchads360.v0.resources.CampaignBudget campaign_budget = 19; 339 340 // The campaign referenced in the query. 341 google.ads.searchads360.v0.resources.Campaign campaign = 2; 342 343 // The campaign asset referenced in the query. 344 google.ads.searchads360.v0.resources.CampaignAsset campaign_asset = 142; 345 346 // The campaign asset set referenced in the query. 347 google.ads.searchads360.v0.resources.CampaignAssetSet campaign_asset_set = 348 181; 349 350 // The campaign audience view referenced in the query. 351 google.ads.searchads360.v0.resources.CampaignAudienceView 352 campaign_audience_view = 69; 353 354 // The campaign criterion referenced in the query. 355 google.ads.searchads360.v0.resources.CampaignCriterion campaign_criterion = 356 20; 357 358 // The campaign label referenced in the query. 359 google.ads.searchads360.v0.resources.CampaignLabel campaign_label = 108; 360 361 // The cart data sales view referenced in the query. 362 google.ads.searchads360.v0.resources.CartDataSalesView cart_data_sales_view = 363 221; 364 365 // The Audience referenced in the query. 366 google.ads.searchads360.v0.resources.Audience audience = 190; 367 368 // The conversion action referenced in the query. 369 google.ads.searchads360.v0.resources.ConversionAction conversion_action = 103; 370 371 // The conversion custom variable referenced in the query. 372 google.ads.searchads360.v0.resources.ConversionCustomVariable 373 conversion_custom_variable = 153; 374 375 // The customer referenced in the query. 376 google.ads.searchads360.v0.resources.Customer customer = 1; 377 378 // The customer asset referenced in the query. 379 google.ads.searchads360.v0.resources.CustomerAsset customer_asset = 155; 380 381 // The customer asset set referenced in the query. 382 google.ads.searchads360.v0.resources.CustomerAssetSet customer_asset_set = 383 195; 384 385 // The accessible bidding strategy referenced in the query. 386 google.ads.searchads360.v0.resources.AccessibleBiddingStrategy 387 accessible_bidding_strategy = 169; 388 389 // The CustomerManagerLink referenced in the query. 390 google.ads.searchads360.v0.resources.CustomerManagerLink 391 customer_manager_link = 61; 392 393 // The CustomerClient referenced in the query. 394 google.ads.searchads360.v0.resources.CustomerClient customer_client = 70; 395 396 // The dynamic search ads search term view referenced in the query. 397 google.ads.searchads360.v0.resources.DynamicSearchAdsSearchTermView 398 dynamic_search_ads_search_term_view = 106; 399 400 // The gender view referenced in the query. 401 google.ads.searchads360.v0.resources.GenderView gender_view = 40; 402 403 // The geo target constant referenced in the query. 404 google.ads.searchads360.v0.resources.GeoTargetConstant geo_target_constant = 405 23; 406 407 // The keyword view referenced in the query. 408 google.ads.searchads360.v0.resources.KeywordView keyword_view = 21; 409 410 // The label referenced in the query. 411 google.ads.searchads360.v0.resources.Label label = 52; 412 413 // The language constant referenced in the query. 414 google.ads.searchads360.v0.resources.LanguageConstant language_constant = 55; 415 416 // The location view referenced in the query. 417 google.ads.searchads360.v0.resources.LocationView location_view = 123; 418 419 // The Product Bidding Category referenced in the query. 420 google.ads.searchads360.v0.resources.ProductBiddingCategoryConstant 421 product_bidding_category_constant = 109; 422 423 // The product group view referenced in the query. 424 google.ads.searchads360.v0.resources.ProductGroupView product_group_view = 54; 425 426 // The shopping performance view referenced in the query. 427 google.ads.searchads360.v0.resources.ShoppingPerformanceView 428 shopping_performance_view = 117; 429 430 // The user list referenced in the query. 431 google.ads.searchads360.v0.resources.UserList user_list = 38; 432 433 // The webpage view referenced in the query. 434 google.ads.searchads360.v0.resources.WebpageView webpage_view = 162; 435 436 // The event level visit referenced in the query. 437 google.ads.searchads360.v0.resources.Visit visit = 203; 438 439 // The event level conversion referenced in the query. 440 google.ads.searchads360.v0.resources.Conversion conversion = 206; 441 442 // The metrics. 443 google.ads.searchads360.v0.common.Metrics metrics = 4; 444 445 // The segments. 446 google.ads.searchads360.v0.common.Segments segments = 102; 447 448 // The custom columns. 449 repeated google.ads.searchads360.v0.common.Value custom_columns = 156; 450} 451 452// Message for custom column header. 453message CustomColumnHeader { 454 // The custom column ID. 455 int64 id = 1; 456 457 // The user defined name of the custom column. 458 string name = 2; 459 460 // True when the custom column references metrics. 461 bool references_metrics = 3; 462} 463 464// Message for conversion custom metric header. 465message ConversionCustomMetricHeader { 466 // The conversion custom metric ID. 467 int64 id = 1; 468 469 // The user defined name of the conversion custom metric. 470 string name = 2; 471} 472 473// Message for conversion custom dimension header. 474message ConversionCustomDimensionHeader { 475 // The conversion custom dimension ID. 476 int64 id = 1; 477 478 // The user defined name of the conversion custom dimension. 479 string name = 2; 480} 481 482// Message for raw event conversion metric header. 483message RawEventConversionMetricHeader { 484 // The conversion custom variable ID. 485 int64 id = 1; 486 487 // The user defined name of the raw event metric. 488 string name = 2; 489} 490 491// Message for raw event conversion dimension header. 492message RawEventConversionDimensionHeader { 493 // The conversion custom variable ID. 494 int64 id = 1; 495 496 // The user defined name of the raw event dimension. 497 string name = 2; 498} 499