legacy-libs/google-proto-files/google/ads/googleads/v0/services/google_ads_service.proto

   1 // Copyright 2018 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 //
  15
  16 syntax = "proto3";
  17
  18 package google.ads.googleads.v0.services;
  19
  20 import "google/ads/googleads/v0/common/metrics.proto";
  21 import "google/ads/googleads/v0/common/segments.proto";
  22 import "google/ads/googleads/v0/resources/account_budget.proto";
  23 import "google/ads/googleads/v0/resources/account_budget_proposal.proto";
  24 import "google/ads/googleads/v0/resources/ad_group.proto";
  25 import "google/ads/googleads/v0/resources/ad_group_ad.proto";
  26 import "google/ads/googleads/v0/resources/ad_group_audience_view.proto";
  27 import "google/ads/googleads/v0/resources/ad_group_bid_modifier.proto";
  28 import "google/ads/googleads/v0/resources/ad_group_criterion.proto";
  29 import "google/ads/googleads/v0/resources/ad_group_feed.proto";
  30 import "google/ads/googleads/v0/resources/ad_schedule_view.proto";
  31 import "google/ads/googleads/v0/resources/age_range_view.proto";
  32 import "google/ads/googleads/v0/resources/bidding_strategy.proto";
  33 import "google/ads/googleads/v0/resources/billing_setup.proto";
  34 import "google/ads/googleads/v0/resources/campaign.proto";
  35 import "google/ads/googleads/v0/resources/campaign_audience_view.proto";
  36 import "google/ads/googleads/v0/resources/campaign_bid_modifier.proto";
  37 import "google/ads/googleads/v0/resources/campaign_budget.proto";
  38 import "google/ads/googleads/v0/resources/campaign_criterion.proto";
  39 import "google/ads/googleads/v0/resources/campaign_feed.proto";
  40 import "google/ads/googleads/v0/resources/campaign_shared_set.proto";
  41 import "google/ads/googleads/v0/resources/carrier_constant.proto";
  42 import "google/ads/googleads/v0/resources/change_status.proto";
  43 import "google/ads/googleads/v0/resources/conversion_action.proto";
  44 import "google/ads/googleads/v0/resources/customer.proto";
  45 import "google/ads/googleads/v0/resources/customer_client.proto";
  46 import "google/ads/googleads/v0/resources/customer_client_link.proto";
  47 import "google/ads/googleads/v0/resources/customer_feed.proto";
  48 import "google/ads/googleads/v0/resources/customer_manager_link.proto";
  49 import "google/ads/googleads/v0/resources/display_keyword_view.proto";
  50 import "google/ads/googleads/v0/resources/feed.proto";
  51 import "google/ads/googleads/v0/resources/feed_item.proto";
  52 import "google/ads/googleads/v0/resources/feed_mapping.proto";
  53 import "google/ads/googleads/v0/resources/gender_view.proto";
  54 import "google/ads/googleads/v0/resources/geo_target_constant.proto";
  55 import "google/ads/googleads/v0/resources/hotel_group_view.proto";
  56 import "google/ads/googleads/v0/resources/hotel_performance_view.proto";
  57 import "google/ads/googleads/v0/resources/keyword_plan.proto";
  58 import "google/ads/googleads/v0/resources/keyword_plan_ad_group.proto";
  59 import "google/ads/googleads/v0/resources/keyword_plan_campaign.proto";
  60 import "google/ads/googleads/v0/resources/keyword_plan_keyword.proto";
  61 import "google/ads/googleads/v0/resources/keyword_plan_negative_keyword.proto";
  62 import "google/ads/googleads/v0/resources/keyword_view.proto";
  63 import "google/ads/googleads/v0/resources/language_constant.proto";
  64 import "google/ads/googleads/v0/resources/managed_placement_view.proto";
  65 import "google/ads/googleads/v0/resources/media_file.proto";
  66 import "google/ads/googleads/v0/resources/mobile_app_category_constant.proto";
  67 import "google/ads/googleads/v0/resources/mobile_device_constant.proto";
  68 import "google/ads/googleads/v0/resources/operating_system_version_constant.proto";
  69 import "google/ads/googleads/v0/resources/parental_status_view.proto";
  70 import "google/ads/googleads/v0/resources/product_group_view.proto";
  71 import "google/ads/googleads/v0/resources/recommendation.proto";
  72 import "google/ads/googleads/v0/resources/remarketing_action.proto";
  73 import "google/ads/googleads/v0/resources/search_term_view.proto";
  74 import "google/ads/googleads/v0/resources/shared_criterion.proto";
  75 import "google/ads/googleads/v0/resources/shared_set.proto";
  76 import "google/ads/googleads/v0/resources/topic_constant.proto";
  77 import "google/ads/googleads/v0/resources/topic_view.proto";
  78 import "google/ads/googleads/v0/resources/user_interest.proto";
  79 import "google/ads/googleads/v0/resources/user_list.proto";
  80 import "google/ads/googleads/v0/resources/video.proto";
  81 import "google/ads/googleads/v0/services/ad_group_ad_service.proto";
  82 import "google/ads/googleads/v0/services/ad_group_bid_modifier_service.proto";
  83 import "google/ads/googleads/v0/services/ad_group_criterion_service.proto";
  84 import "google/ads/googleads/v0/services/ad_group_service.proto";
  85 import "google/ads/googleads/v0/services/bidding_strategy_service.proto";
  86 import "google/ads/googleads/v0/services/campaign_bid_modifier_service.proto";
  87 import "google/ads/googleads/v0/services/campaign_budget_service.proto";
  88 import "google/ads/googleads/v0/services/campaign_criterion_service.proto";
  89 import "google/ads/googleads/v0/services/campaign_service.proto";
  90 import "google/ads/googleads/v0/services/campaign_shared_set_service.proto";
  91 import "google/ads/googleads/v0/services/conversion_action_service.proto";
  92 import "google/ads/googleads/v0/services/shared_criterion_service.proto";
  93 import "google/ads/googleads/v0/services/shared_set_service.proto";
  94 import "google/ads/googleads/v0/services/user_list_service.proto";
  95 import "google/api/annotations.proto";
  96 import "google/protobuf/field_mask.proto";
  97 import "google/rpc/status.proto";
  98
  99 option csharp_namespace = "Google.Ads.GoogleAds.V0.Services";
 100 option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v0/services;services";
 101 option java_multiple_files = true;
 102 option java_outer_classname = "GoogleAdsServiceProto";
 103 option java_package = "com.google.ads.googleads.v0.services";
 104 option objc_class_prefix = "GAA";
 105 option php_namespace = "Google\\Ads\\GoogleAds\\V0\\Services";
 106 option ruby_package = "Google::Ads::GoogleAds::V0::Services";
 107
 108 // Proto file describing the GoogleAdsService.
 109
 110 // Service to fetch data and metrics across resources.
 111 service GoogleAdsService {
 112   // Returns all rows that match the search query.
 113   rpc Search(SearchGoogleAdsRequest) returns (SearchGoogleAdsResponse) {
 114     option (google.api.http) = {
 115       post: "/v0/customers/{customer_id=*}/googleAds:search"
 116       body: "*"
 117     };
 118   }
 119
 120   // Creates, updates, or removes resources. Operation statuses are returned.
 121   rpc Mutate(MutateGoogleAdsRequest) returns (MutateGoogleAdsResponse) {
 122     option (google.api.http) = {
 123       post: "/v0/customers/{customer_id=*}/googleAds:mutate"
 124       body: "*"
 125     };
 126   }
 127 }
 128
 129 // Request message for
 130 // [GoogleAdsService.Search][google.ads.googleads.v0.services.GoogleAdsService.Search].
 131 message SearchGoogleAdsRequest {
 132   // The ID of the customer being queried.
 133   string customer_id = 1;
 134
 135   // The query string.
 136   string query = 2;
 137
 138   // Token of the page to retrieve. If not specified, the first
 139   // page of results will be returned. Use the value obtained from
 140   // `next_page_token` in the previous response in order to request
 141   // the next page of results.
 142   string page_token = 3;
 143
 144   // Number of elements to retrieve in a single page.
 145   // When too large a page is requested, the server may decide to
 146   // further limit the number of returned resources.
 147   int32 page_size = 4;
 148
 149   // If true, the request is validated but not executed.
 150   bool validate_only = 5;
 151 }
 152
 153 // Response message for
 154 // [GoogleAdsService.Search][google.ads.googleads.v0.services.GoogleAdsService.Search].
 155 message SearchGoogleAdsResponse {
 156   // The list of rows that matched the query.
 157   repeated GoogleAdsRow results = 1;
 158
 159   // Pagination token used to retrieve the next page of results.
 160   // Pass the content of this string as the `page_token` attribute of
 161   // the next request. `next_page_token` is not returned for the last
 162   // page.
 163   string next_page_token = 2;
 164
 165   // Total number of results that match the query ignoring the LIMIT
 166   // clause.
 167   int64 total_results_count = 3;
 168
 169   // FieldMask that represents what fields were requested by the user.
 170   google.protobuf.FieldMask field_mask = 5;
 171 }
 172
 173 // A returned row from the query.
 174 message GoogleAdsRow {
 175   // The account budget in the query.
 176   google.ads.googleads.v0.resources.AccountBudget account_budget = 42;
 177
 178   // The account budget proposal referenced in the query.
 179   google.ads.googleads.v0.resources.AccountBudgetProposal
 180       account_budget_proposal = 43;
 181
 182   // The ad group referenced in the query.
 183   google.ads.googleads.v0.resources.AdGroup ad_group = 3;
 184
 185   // The ad referenced in the query.
 186   google.ads.googleads.v0.resources.AdGroupAd ad_group_ad = 16;
 187
 188   // The ad group audience view referenced in the query.
 189   google.ads.googleads.v0.resources.AdGroupAudienceView ad_group_audience_view =
 190       57;
 191
 192   // The bid modifier referenced in the query.
 193   google.ads.googleads.v0.resources.AdGroupBidModifier ad_group_bid_modifier =
 194       24;
 195
 196   // The criterion referenced in the query.
 197   google.ads.googleads.v0.resources.AdGroupCriterion ad_group_criterion = 17;
 198
 199   // The ad group feed referenced in the query.
 200   google.ads.googleads.v0.resources.AdGroupFeed ad_group_feed = 67;
 201
 202   // The age range view referenced in the query.
 203   google.ads.googleads.v0.resources.AgeRangeView age_range_view = 48;
 204
 205   // The ad schedule view referenced in the query.
 206   google.ads.googleads.v0.resources.AdScheduleView ad_schedule_view = 89;
 207
 208   // The bidding strategy referenced in the query.
 209   google.ads.googleads.v0.resources.BiddingStrategy bidding_strategy = 18;
 210
 211   // The billing setup referenced in the query.
 212   google.ads.googleads.v0.resources.BillingSetup billing_setup = 41;
 213
 214   // The campaign budget referenced in the query.
 215   google.ads.googleads.v0.resources.CampaignBudget campaign_budget = 19;
 216
 217   // The campaign referenced in the query.
 218   google.ads.googleads.v0.resources.Campaign campaign = 2;
 219
 220   // The campaign audience view referenced in the query.
 221   google.ads.googleads.v0.resources.CampaignAudienceView
 222       campaign_audience_view = 69;
 223
 224   // The campaign bid modifier referenced in the query.
 225   google.ads.googleads.v0.resources.CampaignBidModifier campaign_bid_modifier =
 226       26;
 227
 228   // The campaign criterion referenced in the query.
 229   google.ads.googleads.v0.resources.CampaignCriterion campaign_criterion = 20;
 230
 231   // The campaign feed referenced in the query.
 232   google.ads.googleads.v0.resources.CampaignFeed campaign_feed = 63;
 233
 234   // Campaign Shared Set referenced in AWQL query.
 235   google.ads.googleads.v0.resources.CampaignSharedSet campaign_shared_set = 30;
 236
 237   // The carrier constant referenced in the query.
 238   google.ads.googleads.v0.resources.CarrierConstant carrier_constant = 66;
 239
 240   // The ChangeStatus referenced in the query.
 241   google.ads.googleads.v0.resources.ChangeStatus change_status = 37;
 242
 243   // The conversion action referenced in the query.
 244   google.ads.googleads.v0.resources.ConversionAction conversion_action = 103;
 245
 246   // The customer referenced in the query.
 247   google.ads.googleads.v0.resources.Customer customer = 1;
 248
 249   // The CustomerManagerLink referenced in the query.
 250   google.ads.googleads.v0.resources.CustomerManagerLink customer_manager_link =
 251       61;
 252
 253   // The CustomerClientLink referenced in the query.
 254   google.ads.googleads.v0.resources.CustomerClientLink customer_client_link =
 255       62;
 256
 257   // The CustomerClient referenced in the query.
 258   google.ads.googleads.v0.resources.CustomerClient customer_client = 70;
 259
 260   // The customer feed referenced in the query.
 261   google.ads.googleads.v0.resources.CustomerFeed customer_feed = 64;
 262
 263   // The display keyword view referenced in the query.
 264   google.ads.googleads.v0.resources.DisplayKeywordView display_keyword_view =
 265       47;
 266
 267   // The feed referenced in the query.
 268   google.ads.googleads.v0.resources.Feed feed = 46;
 269
 270   // The feed item referenced in the query.
 271   google.ads.googleads.v0.resources.FeedItem feed_item = 50;
 272
 273   // The feed mapping referenced in the query.
 274   google.ads.googleads.v0.resources.FeedMapping feed_mapping = 58;
 275
 276   // The gender view referenced in the query.
 277   google.ads.googleads.v0.resources.GenderView gender_view = 40;
 278
 279   // The geo target constant referenced in the query.
 280   google.ads.googleads.v0.resources.GeoTargetConstant geo_target_constant = 23;
 281
 282   // The hotel group view referenced in the query.
 283   google.ads.googleads.v0.resources.HotelGroupView hotel_group_view = 51;
 284
 285   // The hotel performance view referenced in the query.
 286   google.ads.googleads.v0.resources.HotelPerformanceView
 287       hotel_performance_view = 71;
 288
 289   // The keyword view referenced in the query.
 290   google.ads.googleads.v0.resources.KeywordView keyword_view = 21;
 291
 292   // The keyword plan referenced in the query.
 293   google.ads.googleads.v0.resources.KeywordPlan keyword_plan = 32;
 294
 295   // The keyword plan campaign referenced in the query.
 296   google.ads.googleads.v0.resources.KeywordPlanCampaign keyword_plan_campaign =
 297       33;
 298
 299   // The keyword plan negative keyword referenced in the query.
 300   google.ads.googleads.v0.resources.KeywordPlanNegativeKeyword
 301       keyword_plan_negative_keyword = 34;
 302
 303   // The keyword plan ad group referenced in the query.
 304   google.ads.googleads.v0.resources.KeywordPlanAdGroup keyword_plan_ad_group =
 305       35;
 306
 307   // The keyword plan keyword referenced in the query.
 308   google.ads.googleads.v0.resources.KeywordPlanKeyword keyword_plan_keyword =
 309       36;
 310
 311   // The language constant referenced in the query.
 312   google.ads.googleads.v0.resources.LanguageConstant language_constant = 55;
 313
 314   // The managed placement view referenced in the query.
 315   google.ads.googleads.v0.resources.ManagedPlacementView
 316       managed_placement_view = 53;
 317
 318   // The media file referenced in the query.
 319   google.ads.googleads.v0.resources.MediaFile media_file = 90;
 320
 321   // The mobile app category constant referenced in the query.
 322   google.ads.googleads.v0.resources.MobileAppCategoryConstant
 323       mobile_app_category_constant = 87;
 324
 325   // The mobile device constant referenced in the query.
 326   google.ads.googleads.v0.resources.MobileDeviceConstant
 327       mobile_device_constant = 98;
 328
 329   // The operating system version constant referenced in the query.
 330   google.ads.googleads.v0.resources.OperatingSystemVersionConstant
 331       operating_system_version_constant = 86;
 332
 333   // The parental status view referenced in the query.
 334   google.ads.googleads.v0.resources.ParentalStatusView parental_status_view =
 335       45;
 336
 337   // The product group view referenced in the query.
 338   google.ads.googleads.v0.resources.ProductGroupView product_group_view = 54;
 339
 340   // The recommendation referenced in the query.
 341   google.ads.googleads.v0.resources.Recommendation recommendation = 22;
 342
 343   // The search term view referenced in the query.
 344   google.ads.googleads.v0.resources.SearchTermView search_term_view = 68;
 345
 346   // The shared set referenced in the query.
 347   google.ads.googleads.v0.resources.SharedCriterion shared_criterion = 29;
 348
 349   // The shared set referenced in the query.
 350   google.ads.googleads.v0.resources.SharedSet shared_set = 27;
 351
 352   // The topic view referenced in the query.
 353   google.ads.googleads.v0.resources.TopicView topic_view = 44;
 354
 355   // The user interest referenced in the query.
 356   google.ads.googleads.v0.resources.UserInterest user_interest = 59;
 357
 358   // The user list referenced in the query.
 359   google.ads.googleads.v0.resources.UserList user_list = 38;
 360
 361   // The remarketing action referenced in the query.
 362   google.ads.googleads.v0.resources.RemarketingAction remarketing_action = 60;
 363
 364   // The topic constant referenced in the query.
 365   google.ads.googleads.v0.resources.TopicConstant topic_constant = 31;
 366
 367   // The video referenced in the query.
 368   google.ads.googleads.v0.resources.Video video = 39;
 369
 370   // The metrics.
 371   google.ads.googleads.v0.common.Metrics metrics = 4;
 372
 373   // The segments.
 374   google.ads.googleads.v0.common.Segments segments = 102;
 375 }
 376
 377 // Request message for
 378 // [GoogleAdsService.Mutate][google.ads.googleads.v0.services.GoogleAdsService.Mutate].
 379 message MutateGoogleAdsRequest {
 380   // The ID of the customer whose resources are being modified.
 381   string customer_id = 1;
 382
 383   // The list of operations to perform on individual resources.
 384   repeated MutateOperation mutate_operations = 2;
 385
 386   // If true, successful operations will be carried out and invalid
 387   // operations will return errors. If false, all operations will be carried
 388   // out in one transaction if and only if they are all valid.
 389   // Default is false.
 390   bool partial_failure = 3;
 391
 392   // If true, the request is validated but not executed. Only errors are
 393   // returned, not results.
 394   bool validate_only = 4;
 395 }
 396
 397 // Response message for
 398 // [GoogleAdsService.Mutate][google.ads.googleads.v0.services.GoogleAdsService.Mutate].
 399 message MutateGoogleAdsResponse {
 400   // Errors that pertain to operation failures in the partial failure mode.
 401   // Returned only when partial_failure = true and all errors occur inside the
 402   // operations. If any errors occur outside the operations (e.g. auth errors),
 403   // we return an RPC level error.
 404   google.rpc.Status partial_failure_error = 3;
 405
 406   // All responses for the mutate.
 407   repeated MutateOperationResponse mutate_operation_responses = 1;
 408 }
 409
 410 // A single operation (create, update, remove) on a resource.
 411 message MutateOperation {
 412   // The mutate operation.
 413   oneof operation {
 414     // An ad group ad mutate operation.
 415     AdGroupAdOperation ad_group_ad_operation = 1;
 416
 417     // An ad group bid modifier mutate operation.
 418     AdGroupBidModifierOperation ad_group_bid_modifier_operation = 2;
 419
 420     // An ad group criterion mutate operation.
 421     AdGroupCriterionOperation ad_group_criterion_operation = 3;
 422
 423     // An ad group mutate operation.
 424     AdGroupOperation ad_group_operation = 5;
 425
 426     // A bidding strategy mutate operation.
 427     BiddingStrategyOperation bidding_strategy_operation = 6;
 428
 429     // A campaign bid modifier mutate operation.
 430     CampaignBidModifierOperation campaign_bid_modifier_operation = 7;
 431
 432     // A campaign budget mutate operation.
 433     CampaignBudgetOperation campaign_budget_operation = 8;
 434
 435     // A campaign mutate operation.
 436     CampaignOperation campaign_operation = 10;
 437
 438     // A campaign shared set mutate operation.
 439     CampaignSharedSetOperation campaign_shared_set_operation = 11;
 440
 441     // A conversion action mutate operation.
 442     ConversionActionOperation conversion_action_operation = 12;
 443
 444     // A campaign criterion mutate operation.
 445     CampaignCriterionOperation campaign_criterion_operation = 13;
 446
 447     // A shared criterion mutate operation.
 448     SharedCriterionOperation shared_criterion_operation = 14;
 449
 450     // A shared set mutate operation.
 451     SharedSetOperation shared_set_operation = 15;
 452
 453     // A user list mutate operation.
 454     UserListOperation user_list_operation = 16;
 455   }
 456 }
 457
 458 // Response message for the resource mutate.
 459 message MutateOperationResponse {
 460   // The mutate response
 461   oneof response {
 462     // The result for the ad group ad mutate.
 463     MutateAdGroupAdResult ad_group_ad_result = 1;
 464
 465     // The result for the ad group bid modifier mutate.
 466     MutateAdGroupBidModifierResult ad_group_bid_modifier_result = 2;
 467
 468     // The result for the ad group criterion mutate.
 469     MutateAdGroupCriterionResult ad_group_criterion_result = 3;
 470
 471     // The result for the ad group mutate.
 472     MutateAdGroupResult ad_group_result = 5;
 473
 474     // The result for the bidding strategy mutate.
 475     MutateBiddingStrategyResult bidding_strategy_result = 6;
 476
 477     // The result for the campaign bid modifier mutate.
 478     MutateCampaignBidModifierResult campaign_bid_modifier_result = 7;
 479
 480     // The result for the campaign budget mutate.
 481     MutateCampaignBudgetResult campaign_budget_result = 8;
 482
 483     // The result for the campaign mutate.
 484     MutateCampaignResult campaign_result = 10;
 485
 486     // The result for the campaign shared set mutate.
 487     MutateCampaignSharedSetResult campaign_shared_set_result = 11;
 488
 489     // The result for the conversion action mutate.
 490     MutateConversionActionResult conversion_action_result = 12;
 491
 492     // The result for the campaign criterion mutate.
 493     MutateCampaignCriterionResult campaign_criterion_result = 13;
 494
 495     // The result for the shared criterion mutate.
 496     MutateSharedCriterionResult shared_criterion_result = 14;
 497
 498     // The result for the shared set mutate.
 499     MutateSharedSetResult shared_set_result = 15;
 500
 501     // The result for the user list mutate.
 502     MutateUserListResult user_list_result = 16;
 503   }
 504 }