google/ads/admanager/v1/report_service.proto

// Copyright 2023 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.admanager.v1;

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";

option csharp_namespace = "Google.Ads.AdManager.V1";
option go_package = "google.golang.org/genproto/googleapis/ads/admanager/v1;admanager";
option java_multiple_files = true;
option java_outer_classname = "ReportServiceProto";
option java_package = "com.google.ads.admanager.v1";
option php_namespace = "Google\\Ads\\AdManager\\V1";

// Provides methods for interacting with Reports.
service ReportService {
  option (google.api.default_host) = "admanager.googleapis.com";

  // Initiates the execution and export of a report asynchronously. Users can
  // get the report by polling this operation via
  // OperationsService.GetOperation.
  // Intervals of at least 2 seconds are recommended, with an exponential
  // backoff. Once a report is complete, the operation will contain a
  // ExportSavedReportResponse in its response field.
  rpc ExportSavedReport(ExportSavedReportRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1/{report=networks/*/reports/*}:exportSavedReport"
      body: "*"
    };
    option (google.api.method_signature) = "report";
    option (google.longrunning.operation_info) = {
      response_type: "ExportSavedReportResponse"
      metadata_type: "ExportSavedReportMetadata"
    };
  }
}

// The Report resource.
message Report {
  option (google.api.resource) = {
    type: "admanager.googleapis.com/Report"
    pattern: "networks/{network_code}/reports/{report}"
    plural: "reports"
    singular: "report"
  };

  // Identifier. The resource name of the Report.
  // Report resource name have the form:
  // `networks/{network_code}/reports/{report_id}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];
}

// Request proto for the configuration of a report run.
message ExportSavedReportRequest {
  // Supported file formats.
  enum Format {
    // Default value. This value is unused.
    FORMAT_UNSPECIFIED = 0;

    // Comma separated values meant to be used by automated machine
    // processing.
    //
    // Unlike other formats, the output is not localized and there is no
    // totals row by default.
    CSV_DUMP = 2;

    // The report file is generated as an Office Open XML spreadsheet designed
    // for Excel 2007+.
    XLSX = 5;

    // The report is generated as XML.
    XML = 6;
  }

  // The name of a particular saved report resource.
  //
  // A report will be run based on the specification of this saved report.
  // It must have the format of
  // "networks/{network_code}/reports/{report_id}"
  string report = 1 [(google.api.resource_reference) = {
    type: "admanager.googleapis.com/Report"
  }];

  // Required. The export format requested.
  Format format = 2 [(google.api.field_behavior) = REQUIRED];

  // Whether or not to include the report properties (e.g. network, user, date
  // generated...) in the generated report.
  bool include_report_properties = 3;

  // Whether or not to include the IDs if there are any (e.g. advertiser ID,
  //  order ID...) present in the report.
  bool include_ids = 4;

  // Whether or not to include a row containing metric totals.
  bool include_totals_row = 5;

  // The file name of report download. The file extension is determined by
  // export_format and gzip_compressed.
  //
  // Defaults to "DFP Report" if not specified.
  string file_name = 6;
}

// The message stored in the google.longrunning.Operation.metadata field.
// Contains metadata regarding this execution.
message ExportSavedReportMetadata {
  // The result generated in this report run.
  int64 result_id = 1;
}

// Message included in the longrunning Operation result.response field when
// the report completes successfully.
message ExportSavedReportResponse {
  // The link to the exported file.
  string download_url = 1;
}