kpt-grpc-demo/google/ads/searchads360/v0/services/search_ads360_service.proto

// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.ads.searchads360.v0.services;

import "google/ads/searchads360/v0/common/metrics.proto";
import "google/ads/searchads360/v0/common/segments.proto";
import "google/ads/searchads360/v0/common/value.proto";
import "google/ads/searchads360/v0/enums/summary_row_setting.proto";
import "google/ads/searchads360/v0/resources/ad_group.proto";
import "google/ads/searchads360/v0/resources/ad_group_bid_modifier.proto";
import "google/ads/searchads360/v0/resources/ad_group_criterion.proto";
import "google/ads/searchads360/v0/resources/bidding_strategy.proto";
import "google/ads/searchads360/v0/resources/campaign.proto";
import "google/ads/searchads360/v0/resources/campaign_budget.proto";
import "google/ads/searchads360/v0/resources/campaign_criterion.proto";
import "google/ads/searchads360/v0/resources/conversion_action.proto";
import "google/ads/searchads360/v0/resources/customer.proto";
import "google/ads/searchads360/v0/resources/customer_client.proto";
import "google/ads/searchads360/v0/resources/customer_manager_link.proto";
import "google/ads/searchads360/v0/resources/keyword_view.proto";
import "google/ads/searchads360/v0/resources/product_group_view.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/field_mask.proto";

option csharp_namespace = "Google.Ads.SearchAds360.V0.Services";
option go_package = "google.golang.org/genproto/googleapis/ads/searchads360/v0/services;services";
option java_multiple_files = true;
option java_outer_classname = "SearchAds360ServiceProto";
option java_package = "com.google.ads.searchads360.v0.services";
option objc_class_prefix = "GASA360";
option php_namespace = "Google\\Ads\\SearchAds360\\V0\\Services";
option ruby_package = "Google::Ads::SearchAds360::V0::Services";

// Proto file describing the SearchAds360Service.

// Service to fetch data and metrics across resources.
service SearchAds360Service {
  option (google.api.default_host) = "searchads360.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/doubleclicksearch";

  // Returns all rows that match the search query.
  //
  // List of thrown errors:
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QueryError]()
  //   [QuotaError]()
  //   [RequestError]()
  rpc Search(SearchSearchAds360Request) returns (SearchSearchAds360Response) {
    option (google.api.http) = {
      post: "/v0/customers/{customer_id=*}/searchAds360:search"
      body: "*"
    };
    option (google.api.method_signature) = "customer_id,query";
  }

  // Returns all rows that match the search stream query.
  //
  // List of thrown errors:
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QueryError]()
  //   [QuotaError]()
  //   [RequestError]()
  rpc SearchStream(SearchSearchAds360StreamRequest) returns (stream SearchSearchAds360StreamResponse) {
    option (google.api.http) = {
      post: "/v0/customers/{customer_id=*}/searchAds360:searchStream"
      body: "*"
    };
    option (google.api.method_signature) = "customer_id,query";
  }
}

// Request message for [SearchAds360Service.Search][google.ads.searchads360.v0.services.SearchAds360Service.Search].
message SearchSearchAds360Request {
  // Required. The ID of the customer being queried.
  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The query string.
  string query = 2 [(google.api.field_behavior) = REQUIRED];

  // Token of the page to retrieve. If not specified, the first
  // page of results will be returned. Use the value obtained from
  // `next_page_token` in the previous response in order to request
  // the next page of results.
  string page_token = 3;

  // Number of elements to retrieve in a single page.
  // When too large a page is requested, the server may decide to
  // further limit the number of returned resources.
  int32 page_size = 4;

  // If true, the request is validated but not executed.
  bool validate_only = 5;

  // If true, the total number of results that match the query ignoring the
  // LIMIT clause will be included in the response.
  // Default is false.
  bool return_total_results_count = 7;

  // Determines whether a summary row will be returned. By default, summary row
  // is not returned. If requested, the summary row will be sent in a response
  // by itself after all other query results are returned.
  google.ads.searchads360.v0.enums.SummaryRowSettingEnum.SummaryRowSetting summary_row_setting = 8;
}

// Response message for [SearchAds360Service.Search][google.ads.searchads360.v0.services.SearchAds360Service.Search].
message SearchSearchAds360Response {
  // The list of rows that matched the query.
  repeated SearchAds360Row results = 1;

  // Pagination token used to retrieve the next page of results.
  // Pass the content of this string as the `page_token` attribute of
  // the next request. `next_page_token` is not returned for the last
  // page.
  string next_page_token = 2;

  // Total number of results that match the query ignoring the LIMIT
  // clause.
  int64 total_results_count = 3;

  // FieldMask that represents what fields were requested by the user.
  google.protobuf.FieldMask field_mask = 5;

  // Summary row that contains summary of metrics in results.
  // Summary of metrics means aggregation of metrics across all results,
  // here aggregation could be sum, average, rate, etc.
  SearchAds360Row summary_row = 6;

  // The headers of the custom columns in the results.
  repeated CustomColumnHeader custom_column_headers = 7;
}

// Request message for [SearchAds360Service.SearchStream][google.ads.searchads360.v0.services.SearchAds360Service.SearchStream].
message SearchSearchAds360StreamRequest {
  // Required. The ID of the customer being queried.
  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The query string.
  string query = 2 [(google.api.field_behavior) = REQUIRED];

  // The number of rows that are returned in each stream response batch.
  // When too large batch is requested, the server may decide to further limit
  // the number of returned rows.
  int32 batch_size = 4;

  // Determines whether a summary row will be returned. By default, summary row
  // is not returned. If requested, the summary row will be sent in a response
  // by itself after all other query results are returned.
  google.ads.searchads360.v0.enums.SummaryRowSettingEnum.SummaryRowSetting summary_row_setting = 3;
}

// Response message for [SearchAds360Service.SearchStream][google.ads.searchads360.v0.services.SearchAds360Service.SearchStream].
message SearchSearchAds360StreamResponse {
  // The list of rows that matched the query.
  repeated SearchAds360Row results = 1;

  // FieldMask that represents what fields were requested by the user.
  google.protobuf.FieldMask field_mask = 2;

  // Summary row that contains summary of metrics in results.
  // Summary of metrics means aggregation of metrics across all results,
  // here aggregation could be sum, average, rate, etc.
  SearchAds360Row summary_row = 3;

  // The headers of the custom columns in the results.
  repeated CustomColumnHeader custom_column_headers = 5;

  // The unique id of the request that is used for debugging purposes.
  string request_id = 4;
}

// A returned row from the query.
message SearchAds360Row {
  // The ad group referenced in the query.
  google.ads.searchads360.v0.resources.AdGroup ad_group = 3;

  // The bid modifier referenced in the query.
  google.ads.searchads360.v0.resources.AdGroupBidModifier ad_group_bid_modifier = 24;

  // The criterion referenced in the query.
  google.ads.searchads360.v0.resources.AdGroupCriterion ad_group_criterion = 17;

  // The bidding strategy referenced in the query.
  google.ads.searchads360.v0.resources.BiddingStrategy bidding_strategy = 18;

  // The campaign budget referenced in the query.
  google.ads.searchads360.v0.resources.CampaignBudget campaign_budget = 19;

  // The campaign referenced in the query.
  google.ads.searchads360.v0.resources.Campaign campaign = 2;

  // The campaign criterion referenced in the query.
  google.ads.searchads360.v0.resources.CampaignCriterion campaign_criterion = 20;

  // The conversion action referenced in the query.
  google.ads.searchads360.v0.resources.ConversionAction conversion_action = 103;

  // The customer referenced in the query.
  google.ads.searchads360.v0.resources.Customer customer = 1;

  // The CustomerManagerLink referenced in the query.
  google.ads.searchads360.v0.resources.CustomerManagerLink customer_manager_link = 61;

  // The CustomerClient referenced in the query.
  google.ads.searchads360.v0.resources.CustomerClient customer_client = 70;

  // The keyword view referenced in the query.
  google.ads.searchads360.v0.resources.KeywordView keyword_view = 21;

  // The product group view referenced in the query.
  google.ads.searchads360.v0.resources.ProductGroupView product_group_view = 54;

  // The metrics.
  google.ads.searchads360.v0.common.Metrics metrics = 4;

  // The segments.
  google.ads.searchads360.v0.common.Segments segments = 102;

  // The custom columns.
  repeated google.ads.searchads360.v0.common.Value custom_columns = 156;
}

// Message for custom column header.
message CustomColumnHeader {
  // The custom column ID.
  int64 id = 1;

  // The user defined name of the custom column.
  string name = 2;

  // True when the custom column references metrics.
  bool references_metrics = 3;
}