admanager/v1/line_item_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/ads/admanager/v1/computed_status_enum.proto";
import "google/ads/admanager/v1/creative_placeholder.proto";
import "google/ads/admanager/v1/environment_type_enum.proto";
import "google/ads/admanager/v1/goal.proto";
import "google/ads/admanager/v1/line_item_enums.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/timestamp.proto";
import "google/type/money.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 = "LineItemServiceProto";
option java_package = "com.google.ads.admanager.v1";
option objc_class_prefix = "GAA";
option php_namespace = "Google\\Ads\\AdManager\\V1";

// Provides methods for handling LineItem objects.
service LineItemService {
  option (google.api.default_host) = "admanager.googleapis.com";

  // API to retrieve a LineItem object.
  rpc GetLineItem(GetLineItemRequest) returns (LineItem) {
    option (google.api.http) = {
      get: "/v1/{name=networks/*/orders/*/lineItems/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // API to retrieve a list of LineItem objects.
  rpc ListLineItems(ListLineItemsRequest) returns (ListLineItemsResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=networks/*/orders/*}/lineItems"
    };
    option (google.api.method_signature) = "parent";
  }
}

// The LineItem resource.
message LineItem {
  option (google.api.resource) = {
    type: "admanager.googleapis.com/LineItem"
    pattern: "networks/{network_code}/orders/{order}/lineItems/{line_item}"
    plural: "lineItems"
    singular: "lineItem"
  };

  // Identifier. The resource name of the LineItem.
  // Format:
  // `networks/{network_code}/orders/{order_id}/lineItems/{line_item_id}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Optional. Display name of the LineItem. This attribute has a maximum length
  // of 255 characters.
  string display_name = 2 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The archival status of the LineItem.
  bool archived = 14 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. This attribute is only applicable for certain
  // [line item types][LineItemType] and acts as an "FYI" or note, which does
  // not impact ad-serving or other backend systems.
  //
  // For [SPONSORSHIP][LineItemType.SPONSORSHIP] line items, this represents
  // the minimum quantity, which is a lifetime impression volume goal for
  // reporting purposes.
  //
  // For [STANDARD][LineItemType.STANDARD] line items, this represents the
  // contracted quantity, which is the number of units specified in the contract
  // that the advertiser has bought for this line item. This attribute is only
  // available if you have this feature enabled on your network.
  int64 contracted_units_bought = 18 [(google.api.field_behavior) = OPTIONAL];

  // Required. The amount of money to spend per impression or click.
  google.type.Money cost_per_unit = 15 [(google.api.field_behavior) = REQUIRED];

  // Required. The method used for billing this line item.
  LineItemCostTypeEnum.LineItemCostType cost_type = 19
      [(google.api.field_behavior) = REQUIRED];

  // Output only. The instant at which the LineItem was created. This attribute
  // may be null for line items created before this feature was introduced.
  google.protobuf.Timestamp create_time = 12
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The instant at which the LineItem was last updated
  google.protobuf.Timestamp update_time = 31
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. The strategy used for displaying multiple
  // [creatives][google.ads.admanager.v1.Creative] that are associated with the
  // line item.
  CreativeRotationTypeEnum.CreativeRotationType creative_rotation_type = 22
      [(google.api.field_behavior) = REQUIRED];

  // Non-empty default. The strategy for delivering ads over the duration of the
  // line item. Defaults to [EVENLY][DeliveryRateType.EVENLY] or
  // [FRONTLOADED][DeliveryRatetype.FRONTLOADED] depending on the network's
  // configuration.
  DeliveryRateTypeEnum.DeliveryRateType delivery_rate_type = 23
      [(google.api.field_behavior) = NON_EMPTY_DEFAULT];

  // Optional. The number here is either a percentage or an absolute value
  // depending on the
  // [discount_type][google.ads.admanager.v1.LineItem.discount_type]. If it is
  // [PERCENTAGE][LineItemDiscountType.PERCENTAGE], then only non-fractional
  // values are supported.
  double discount = 13 [(google.api.field_behavior) = OPTIONAL];

  // Non-empty default. The type of discount applied to the line item. Defaults
  // to [PERCENTAGE][LineItemDiscountType.PERCENTAGE].
  LineItemDiscountTypeEnum.LineItemDiscountType discount_type = 24
      [(google.api.field_behavior) = NON_EMPTY_DEFAULT];

  // Non-empty default. The environment that the line item is targeting. The
  // default value is [BROWSER][EnvironmentType.BROWSER]. If this value is
  // [VIDEO_PLAYER][EnvironmentType.VIDEO_PLAYER], then this line item can only
  // target [AdUnits][google.ads.admanager.v1.AdUnit] that have `AdUnitSizes`
  // whose `environment_type` is also `VIDEO_PLAYER`.
  EnvironmentTypeEnum.EnvironmentType environment_type = 25
      [(google.api.field_behavior) = NON_EMPTY_DEFAULT];

  // Optional. Identifier for the LineItem that is meaningful to the publisher.
  // This attribute has a maximum length of 255 characters.
  string external_id = 5 [(google.api.field_behavior) = OPTIONAL];

  // Required. Time at which the LineItem will begin serving. This attribute
  // must be in the future when creating a LineItem.
  google.protobuf.Timestamp start_time = 6
      [(google.api.field_behavior) = REQUIRED];

  // Optional. Time at which the LineItem will stop serving. This attribute is
  // ignored when
  // [unlimited_end_time][google.ads.admanager.v1.LineItem.unlimited_end_time]
  // is `true`. If specified, it must be after
  // [start_time][google.ads.admanager.v1.LineItem.start_time]. This end time
  // does not include
  // [auto_extension_days][google.ads.admanager.v1.LineItem.auto_extension_days].
  google.protobuf.Timestamp end_time = 7
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Number of days to allow a LineItem to deliver past its
  // [end_time][google.ads.admanager.v1.LineItem.end_time]. A maximum of 7 days
  // is allowed. This feature is only available for Ad Manager 360 accounts.
  int32 auto_extension_days = 8 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Whether the LineItem has an
  // [end_time][google.ads.admanager.v1.LineItem.end_time]. This attribute can
  // be set to `true` for only LineItems with
  // [line_item_type][google.ads.admanager.v1.LineItem.line_item_type]
  // [SPONSORSHIP][LineItemType.SPONSORSHIP], [NETWORK][LineItemType.NETWORK],
  // [PRICE_PRIORITY][LineItemType.PRICE_PRIORITY] and
  // [HOUSE][LineItemType.HOUSE].
  bool unlimited_end_time = 9 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The application that last modified this line item.
  string last_modified_by_app = 17 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. Determines the default priority of the LineItem for delivery.
  // More information can be found on the [Ad Manager Help
  // Center](https://support.google.com/dfp_premium/answer/177279).
  LineItemTypeEnum.LineItemType line_item_type = 10
      [(google.api.field_behavior) = REQUIRED];

  // Output only. Indicates if a line item is missing any
  // [creatives][google.ads.admanager.v1.Creative] for the
  // [creative_placeholders][google.ads.admanager.v1.LineItem.creative_placeholders]
  // specified.
  //
  // [Creatives][google.ads.admanager.v1.Creative] can be considered missing for
  // several reasons:
  //
  // * Not enough [creatives][google.ads.admanager.v1.Creative] of a certain
  // size have been uploaded,
  //   as determined by
  //   [expectedCreativeCount][google.ads.admanager.v1.CreativePlaceholder.expected_creative_count].
  //   For example a line item specifies 750x350, 400x200, but only a 750x350
  //   was uploaded. Or line item specifies 750x350 with an expected count of 2,
  //   but only one was uploaded.
  // * The [appliedLabels][Creative.applied_labels] of an associated
  // [Creative][google.ads.admanager.v1.Creative]
  //   do not match the
  //   [effectiveAppliedLabels][CreativePlaceholder.effective_applied_labels] of
  //   the line item. For example if a line item specifies 750x350 with a foo
  //   applied label, but a 750x350 creative without an applied label was
  //   uploaded.
  bool missing_creatives = 16 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Provides any additional notes that may annotate LineItem. This
  // field has a maximum length of 65,535 characters.
  string notes = 20 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Priority of the LineItem for delivery. Valid values range from 1
  // to 16. This field can only be changed by certain networks, otherwise a
  // `PERMISSION_DENIED` error will occur.
  //
  // The following list shows the default, minimum, and maximum priority values
  // for each [LineItemType][LineItemType]: formatted as `LineItemType`: default
  // priority (minimum priority, maximum priority):
  //
  // * `SPONSORSHIP`: 4 (2,5)
  // * `STANDARD`: 8 (6,10)
  // * `NETWORK`: 12 (11, 14)
  // * `BULK`: 12 (11, 14)
  // * `PRICE_PRIORITY`: 12 (11, 14)
  // * `HOUSE`: 16 (15, 16)
  // * `CLICK_TRACKING`: 16 (1, 16)
  // * `AD_EXCHANGE`: 12 (1, 16)
  // * `ADSENSE`: 12 (1, 16)
  // * `BUMPER`: 16 (15, 16)
  int64 priority = 11 [(google.api.field_behavior) = OPTIONAL];

  // Output only. Describes whether or not inventory has been reserved for the
  // line item.
  ReservationStatusEnum.ReservationStatus reservation_status = 26
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The web property code used for dynamic allocation line items.
  // This web property is only required with line item types
  // [AD_EXCHANGE][LineItemType.AD_EXCHANGE] and
  // [ADSENSE][LineItemType.ADSENSE].
  string web_property_code = 21 [(google.api.field_behavior) = OPTIONAL];

  // Required. Details about the creatives that are expected to serve through
  // this LineItem.
  repeated CreativePlaceholder creative_placeholders = 27
      [(google.api.field_behavior) = REQUIRED];

  // Output only. The status of the LineItem.
  ComputedStatusEnum.ComputedStatus status = 28
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. The primary goal that this LineItem is associated with, which is
  // used in its pacing and budgeting.
  Goal primary_goal = 29 [(google.api.field_behavior) = REQUIRED];

  // Optional. The impression limit for the LineItem. This field is meaningful
  // only if the
  // [LineItem.line_item_type][google.ads.admanager.v1.LineItem.line_item_type]
  // is [LineItemType.SPONSORSHIP][] and
  // [LineItem.cost_type][google.ads.admanager.v1.LineItem.cost_type] is
  // [CostType.CPM][].
  Goal impression_limit = 30 [(google.api.field_behavior) = OPTIONAL];
}

// Request object for GetLineItem method.
message GetLineItemRequest {
  // Required. The resource name of the LineItem.
  // Format:
  // `networks/{network_code}/orders/{order_id}/lineItems/{line_item_id}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "admanager.googleapis.com/LineItem"
    }
  ];
}

// Request object for ListLineItems method.
message ListLineItemsRequest {
  // Required. The parent, which owns this collection of LineItems.
  // Format: networks/{network_code}/orders/{order_id}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "admanager.googleapis.com/Order" }
  ];

  // Optional. The maximum number of LineItems to return. The service may return
  // fewer than this value. If unspecified, at most 50 line items will be
  // returned. The maximum value is 1000; values above 1000 will be coerced to
  // 1000.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous `ListLineItems` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListLineItems` must
  // match the call that provided the page token.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Expression to filter the response.
  // See syntax details at
  // https://developers.google.com/ad-manager/api/beta/filters
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Expression to specify sorting order.
  // See syntax details at
  // https://developers.google.com/ad-manager/api/beta/filters#order
  string order_by = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Number of individual resources to skip while paginating.
  int32 skip = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Response object for ListLineItemsRequest containing matching LineItem
// resources.
message ListLineItemsResponse {
  // The LineItem from the specified network.
  repeated LineItem line_items = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;

  // Total number of LineItems.
  // If a filter was included in the request, this reflects the total number
  // after the filtering is applied.
  //
  // `total_size` will not be calculated in the response unless it has been
  // included in a response field mask. The response field mask can be provided
  // to the method by using the URL parameter `$fields` or `fields`, or by using
  // the HTTP/gRPC header `X-Goog-FieldMask`.
  //
  // For more information, see
  // https://developers.google.com/ad-manager/api/beta/field-masks
  int32 total_size = 3;
}