// Copyright 2020 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.googleads.v3.services;

import "google/ads/googleads/v3/resources/mutate_job.proto";
import "google/ads/googleads/v3/services/google_ads_service.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/longrunning/operations.proto";
import "google/rpc/status.proto";

option csharp_namespace = "Google.Ads.GoogleAds.V3.Services";
option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v3/services;services";
option java_multiple_files = true;
option java_outer_classname = "MutateJobServiceProto";
option java_package = "com.google.ads.googleads.v3.services";
option objc_class_prefix = "GAA";
option php_namespace = "Google\\Ads\\GoogleAds\\V3\\Services";
option ruby_package = "Google::Ads::GoogleAds::V3::Services";

// Proto file describing the MutateJobService.

// Service to manage mutate jobs.
service MutateJobService {
  option (google.api.default_host) = "googleads.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/adwords";

  // Creates a mutate job.
  rpc CreateMutateJob(CreateMutateJobRequest) returns (CreateMutateJobResponse) {
    option (google.api.http) = {
      post: "/v3/customers/{customer_id=*}/mutateJobs:create"
      body: "*"
    };
    option (google.api.method_signature) = "customer_id";
  }

  // Returns the mutate job.
  rpc GetMutateJob(GetMutateJobRequest) returns (google.ads.googleads.v3.resources.MutateJob) {
    option (google.api.http) = {
      get: "/v3/{resource_name=customers/*/mutateJobs/*}"
    };
    option (google.api.method_signature) = "resource_name";
  }

  // Returns the results of the mutate job. The job must be done.
  // Supports standard list paging.
  rpc ListMutateJobResults(ListMutateJobResultsRequest) returns (ListMutateJobResultsResponse) {
    option (google.api.http) = {
      get: "/v3/{resource_name=customers/*/mutateJobs/*}:listResults"
    };
    option (google.api.method_signature) = "resource_name";
  }

  // Runs the mutate job.
  //
  // The Operation.metadata field type is MutateJobMetadata. When finished, the
  // long running operation will not contain errors or a response. Instead, use
  // ListMutateJobResults to get the results of the job.
  rpc RunMutateJob(RunMutateJobRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v3/{resource_name=customers/*/mutateJobs/*}:run"
      body: "*"
    };
    option (google.api.method_signature) = "resource_name";
    option (google.longrunning.operation_info) = {
      response_type: "google.protobuf.Empty"
      metadata_type: "google.ads.googleads.v3.resources.MutateJob.MutateJobMetadata"
    };
  }

  // Add operations to the mutate job.
  rpc AddMutateJobOperations(AddMutateJobOperationsRequest) returns (AddMutateJobOperationsResponse) {
    option (google.api.http) = {
      post: "/v3/{resource_name=customers/*/mutateJobs/*}:addOperations"
      body: "*"
    };
    option (google.api.method_signature) = "resource_name,sequence_token,mutate_operations";
    option (google.api.method_signature) = "resource_name,mutate_operations";
  }
}

// Request message for [MutateJobService.CreateMutateJobRequest][]
message CreateMutateJobRequest {
  // Required. The ID of the customer for which to create a mutate job.
  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];
}

// Response message for [MutateJobService.CreateMutateJobResponse][]
message CreateMutateJobResponse {
  // The resource name of the MutateJob.
  string resource_name = 1;
}

// Request message for [MutateJobService.GetMutateJob][google.ads.googleads.v3.services.MutateJobService.GetMutateJob]
message GetMutateJobRequest {
  // Required. The resource name of the MutateJob to get.
  string resource_name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "googleads.googleapis.com/MutateJob"
    }
  ];
}

// Request message for [MutateJobService.RunMutateJob][google.ads.googleads.v3.services.MutateJobService.RunMutateJob]
message RunMutateJobRequest {
  // Required. The resource name of the MutateJob to run.
  string resource_name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "googleads.googleapis.com/MutateJob"
    }
  ];
}

// Request message for [MutateJobService.AddMutateJobOperations][google.ads.googleads.v3.services.MutateJobService.AddMutateJobOperations]
message AddMutateJobOperationsRequest {
  // Required. The resource name of the MutateJob.
  string resource_name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "googleads.googleapis.com/MutateJob"
    }
  ];

  // A token used to enforce sequencing.
  //
  // The first AddMutateJobOperations request for a MutateJob should not set
  // sequence_token. Subsequent requests must set sequence_token to the value of
  // next_sequence_token received in the previous AddMutateJobOperations
  // response.
  string sequence_token = 2;

  // Required. The list of mutates being added.
  //
  // Operations can use negative integers as temp ids to signify dependencies
  // between entities created in this MutateJob. For example, a customer with
  // id = 1234 can create a campaign and an ad group in that same campaign by
  // creating a campaign in the first operation with the resource name
  // explicitly set to "customers/1234/campaigns/-1", and creating an ad group
  // in the second operation with the campaign field also set to
  // "customers/1234/campaigns/-1".
  repeated MutateOperation mutate_operations = 3 [(google.api.field_behavior) = REQUIRED];
}

// Response message for [MutateJobService.AddMutateJobOperations][google.ads.googleads.v3.services.MutateJobService.AddMutateJobOperations]
message AddMutateJobOperationsResponse {
  // The total number of operations added so far for this job.
  int64 total_operations = 1;

  // The sequence token to be used when calling AddMutateJobOperations again if
  // more operations need to be added. The next AddMutateJobOperations request
  // must set the sequence_token field to the value of this field.
  string next_sequence_token = 2;
}

// Request message for [MutateJobService.ListMutateJobResults][google.ads.googleads.v3.services.MutateJobService.ListMutateJobResults].
message ListMutateJobResultsRequest {
  // Required. The resource name of the MutateJob whose results are being listed.
  string resource_name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "googleads.googleapis.com/MutateJob"
    }
  ];

  // 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 = 2;

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

// Response message for [MutateJobService.ListMutateJobResults][google.ads.googleads.v3.services.MutateJobService.ListMutateJobResults].
message ListMutateJobResultsResponse {
  // The list of rows that matched the query.
  repeated MutateJobResult 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;
}

// MutateJob result.
message MutateJobResult {
  // Index of the mutate operation.
  int64 operation_index = 1;

  // Response for the mutate.
  // May be empty if errors occurred.
  MutateOperationResponse mutate_operation_response = 2;

  // Details of the errors when processing the operation.
  google.rpc.Status status = 3;
}