legacy-libs/google-proto-files/google/ads/googleads/v0/services/recommendation_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/enums/keyword_match_type.proto";
  21 import "google/ads/googleads/v0/resources/ad.proto";
  22 import "google/ads/googleads/v0/resources/recommendation.proto";
  23 import "google/api/annotations.proto";
  24 import "google/protobuf/wrappers.proto";
  25 import "google/rpc/status.proto";
  26
  27 option csharp_namespace = "Google.Ads.GoogleAds.V0.Services";
  28 option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v0/services;services";
  29 option java_multiple_files = true;
  30 option java_outer_classname = "RecommendationServiceProto";
  31 option java_package = "com.google.ads.googleads.v0.services";
  32 option objc_class_prefix = "GAA";
  33 option php_namespace = "Google\\Ads\\GoogleAds\\V0\\Services";
  34 option ruby_package = "Google::Ads::GoogleAds::V0::Services";
  35
  36 // Proto file describing the Recommendation service.
  37
  38 // Service to manage recommendations.
  39 service RecommendationService {
  40   // Returns the requested recommendation in full detail.
  41   rpc GetRecommendation(GetRecommendationRequest)
  42       returns (google.ads.googleads.v0.resources.Recommendation) {
  43     option (google.api.http) = {
  44       get: "/v0/{resource_name=customers/*/recommendations/*}"
  45     };
  46   }
  47
  48   // Applies given recommendations with corresponding apply parameters.
  49   rpc ApplyRecommendation(ApplyRecommendationRequest)
  50       returns (ApplyRecommendationResponse) {
  51     option (google.api.http) = {
  52       post: "/v0/customers/{customer_id=*}/recommendations:apply"
  53       body: "*"
  54     };
  55   }
  56
  57   // Dismisses given recommendations.
  58   rpc DismissRecommendation(DismissRecommendationRequest)
  59       returns (DismissRecommendationResponse) {
  60     option (google.api.http) = {
  61       post: "/v0/customers/{customer_id=*}/recommendations:dismiss"
  62       body: "*"
  63     };
  64   }
  65 }
  66
  67 // Request message for
  68 // [RecommendationService.GetRecommendation][google.ads.googleads.v0.services.RecommendationService.GetRecommendation].
  69 message GetRecommendationRequest {
  70   // The resource name of the recommendation to fetch.
  71   string resource_name = 1;
  72 }
  73
  74 // Request message for
  75 // [RecommendationService.ApplyRecommendation][google.ads.googleads.v0.services.RecommendationService.ApplyRecommendation].
  76 message ApplyRecommendationRequest {
  77   // The ID of the customer with the recommendation.
  78   string customer_id = 1;
  79
  80   // The list of operations to apply recommendations.
  81   // If partial_failure=false all recommendations should be of the same type
  82   // There is a limit of 100 operations per request.
  83   repeated ApplyRecommendationOperation operations = 2;
  84
  85   // If true, successful operations will be carried out and invalid
  86   // operations will return errors. If false, operations will be carried
  87   // out as a transaction if and only if they are all valid.
  88   // Default is false.
  89   bool partial_failure = 3;
  90 }
  91
  92 // Information about the operation to apply a recommendation and any parameters
  93 // to
  94 // customize it.
  95 message ApplyRecommendationOperation {
  96   // Parameters to use when applying a campaign budget recommendation.
  97   message CampaignBudgetParameters {
  98     // New budget amount to set for target budget resource. This is a required
  99     // field.
 100     google.protobuf.Int64Value new_budget_amount_micros = 1;
 101   }
 102
 103   // Parameters to use when applying a text ad recommendation.
 104   message TextAdParameters {
 105     // New ad to add to recommended ad group. All necessary fields need to be
 106     // set in this message. This is a required field.
 107     google.ads.googleads.v0.resources.Ad ad = 1;
 108   }
 109
 110   // Parameters to use when applying keyword recommendation.
 111   message KeywordParameters {
 112     // The ad group resource to add keyword to. This is a required field.
 113     google.protobuf.StringValue ad_group = 1;
 114
 115     // The match type of the keyword. This is a required field.
 116     google.ads.googleads.v0.enums.KeywordMatchTypeEnum.KeywordMatchType
 117         match_type = 2;
 118
 119     // Optional, CPC bid to set for the keyword. If not set, keyword will use
 120     // bid based on bidding strategy used by target ad group.
 121     google.protobuf.Int64Value cpc_bid_micros = 3;
 122   }
 123
 124   // Parameters to use when applying Target CPA recommendation.
 125   message TargetCpaOptInParameters {
 126     // Average CPA to use for Target CPA bidding strategy. This is a required
 127     // field.
 128     google.protobuf.Int64Value target_cpa_micros = 1;
 129
 130     // Optional, budget amount to set for the campaign.
 131     google.protobuf.Int64Value new_campaign_budget_amount_micros = 2;
 132   }
 133
 134   // The resource name of the recommendation to apply.
 135   string resource_name = 1;
 136
 137   // Parameters to use when applying the recommendation.
 138   oneof apply_parameters {
 139     // Optional parameters to use when applying a campaign budget
 140     // recommendation.
 141     CampaignBudgetParameters campaign_budget = 2;
 142
 143     // Optional parameters to use when applying a text ad recommendation.
 144     TextAdParameters text_ad = 3;
 145
 146     // Optional parameters to use when applying keyword recommendation.
 147     KeywordParameters keyword = 4;
 148
 149     // Optional parameters to use when applying target CPA opt-in
 150     // recommendation.
 151     TargetCpaOptInParameters target_cpa_opt_in = 5;
 152   }
 153 }
 154
 155 // Response message for
 156 // [RecommendationService.ApplyRecommendation][google.ads.googleads.v0.services.RecommendationService.ApplyRecommendation].
 157 message ApplyRecommendationResponse {
 158   // Results of operations to apply recommendations.
 159   repeated ApplyRecommendationResult results = 1;
 160
 161   // Errors that pertain to operation failures in the partial failure mode.
 162   // Returned only when partial_failure = true and all errors occur inside the
 163   // operations. If any errors occur outside the operations (e.g. auth errors)
 164   // we return the RPC level error.
 165   google.rpc.Status partial_failure_error = 2;
 166 }
 167
 168 // The result of applying a recommendation.
 169 message ApplyRecommendationResult {
 170   // Returned for successful applies.
 171   string resource_name = 1;
 172 }
 173
 174 // Request message for
 175 // [RecommendationService.DismissRecommendation][google.ads.googleads.v0.services.RecommendationService.DismissRecommendation].
 176 message DismissRecommendationRequest {
 177   // Operation to dismiss a single recommendation identified by resource_name.
 178   message DismissRecommendationOperation {
 179     // The resource name of the recommendation to dismiss.
 180     string resource_name = 1;
 181   }
 182
 183   // The ID of the customer with the recommendation.
 184   string customer_id = 1;
 185
 186   // The list of operations to dismiss recommendations.
 187   // If partial_failure=false all recommendations should be of the same type
 188   // There is a limit of 100 operations per request.
 189   repeated DismissRecommendationOperation operations = 3;
 190
 191   // If true, successful operations will be carried out and invalid
 192   // operations will return errors. If false, operations will be carried in a
 193   // single transaction if and only if they are all valid.
 194   // Default is false.
 195   bool partial_failure = 2;
 196 }
 197
 198 // Response message for
 199 // [RecommendationService.DismissRecommendation][google.ads.googleads.v0.services.RecommendationService.DismissRecommendation].
 200 message DismissRecommendationResponse {
 201   // The result of dismissing a recommendation.
 202   message DismissRecommendationResult {
 203     // Returned for successful dismissals.
 204     string resource_name = 1;
 205   }
 206
 207   // Results of operations to dismiss recommendations.
 208   repeated DismissRecommendationResult results = 1;
 209
 210   // Errors that pertain to operation failures in the partial failure mode.
 211   // Returned only when partial_failure = true and all errors occur inside the
 212   // operations. If any errors occur outside the operations (e.g. auth errors)
 213   // we return the RPC level error.
 214   google.rpc.Status partial_failure_error = 2;
 215 }