Blame - docs/dyn/displayvideo_v1.advertisers.insertionOrders.html - platform/external/python/google-api-python-client

<h1><a href="displayvideo_v1.html">Display & Video 360 API</a> . <a href="displayvideo_v1.advertisers.html">advertisers</a> . <a href="displayvideo_v1.advertisers.insertionOrders.html">insertionOrders</a></h1>

76

<h2>Instance Methods</h2>

77

78

<code><a href="#create">create(advertiserId, body=None, x__xgafv=None)</a></code></p>

79

<p class="firstline">Creates a new insertion order.</p>

80

81

<code><a href="#delete">delete(advertiserId, insertionOrderId, x__xgafv=None)</a></code></p>

82

<p class="firstline">Deletes an insertion order.</p>

83

84

<code><a href="#get">get(advertiserId, insertionOrderId, x__xgafv=None)</a></code></p>

85

<p class="firstline">Gets an insertion order.</p>

86

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

87

<code><a href="#list">list(advertiserId, filter=None, pageToken=None, orderBy=None, pageSize=None, x__xgafv=None)</a></code></p>

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

88

<p class="firstline">Lists insertion orders in an advertiser.</p>

89

90

<code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p>

91

<p class="firstline">Retrieves the next page of results.</p>

92

93

<code><a href="#patch">patch(advertiserId, insertionOrderId, body=None, updateMask=None, x__xgafv=None)</a></code></p>

94

<p class="firstline">Updates an existing insertion order.</p>

95

<h3>Method Details</h3>

96

97

<code class="details" id="create">create(advertiserId, body=None, x__xgafv=None)</code>

98

<pre>Creates a new insertion order.

99

Returns the newly created insertion order if successful.

100

101

Args:

102

advertiserId: string, Output only. The unique ID of the advertiser the insertion order belongs to. (required)

103

body: object, The request body.

104

The object takes the form of:

105

106

{ # A single insertion order.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

107

"bidStrategy": { # Settings that control the bid strategy. # Optional. The bidding strategy of the insertion order. By default,

108

# fixed_bid is set.

109

# Bid strategy determines the bid price.

110

"fixedBid": { # A strategy that uses a fixed bidding price. # A strategy that uses a fixed bid price.

111

"bidAmountMicros": "A String", # The fixed bid amount, in micros of the advertiser's currency.

112

# For insertion order entity,

113

# bid_amount_micros should be set as 0.

114

# For line item entity,

115

# bid_amount_micros must be greater

116

# than or equal to billable unit of the given currency and smaller than or

117

# equal to the upper limit 1000000000.

118

#

119

# For example, 1500000 represents 1.5 standard units of the currency.

120

},

121

"maximizeSpendAutoBid": { # A strategy that automatically adjusts the bid to optimize a specified # A strategy that automatically adjusts the bid to optimize to your

122

# performance goal while spending the full budget.

123

#

124

# At insertion order level, the

125

# markup_type of line items

126

# cannot be set to `PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM`. In addition,

127

# when

128

# performance_goal_type

129

# is one of:

130

#

131

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`

132

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`

133

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_AV_VIEWED` ,

134

#

135

# the line_item_type

136

# of the insertion order line items must be either:

137

#

138

# * `LINE_ITEM_TYPE_DISPLAY_DEFAULT`

139

# * `LINE_ITEM_TYPE_VIDEO_DEFAULT` ,

140

#

141

# and when

142

# performance_goal_type

143

# is either:

144

#

145

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CIVA`

146

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_IVO_TEN`

147

#

148

# the line_item_type

149

# of the insertion order line items must be `LINE_ITEM_TYPE_VIDEO_DEFAULT`.

150

# performance goal while spending the full budget.

151

"performanceGoalType": "A String", # Required. The type of the performance goal that the bidding strategy

152

# tries to minimize while spending the full budget.

153

# `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM` is not supported for

154

# this strategy.

155

"maxAverageCpmBidAmountMicros": "A String", # The maximum average CPM that may be bid, in micros of the advertiser's

156

# currency. Must be greater than or equal to a billable unit of the given

157

# currency.

158

#

159

# For example, 1500000 represents 1.5 standard units of the currency.

160

},

161

"performanceGoalAutoBid": { # A strategy that automatically adjusts the bid to meet or beat a specified # A strategy that automatically adjusts the bid to meet or beat a specified

162

# performance goal. It is to be used only for a line item entity.

163

# performance goal.

164

"performanceGoalType": "A String", # Required. The type of the performance goal that the bidding strategy

165

# will try to meet or beat.

166

#

167

# For line item level usage, the value must be one of:

168

#

169

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`

170

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`

171

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`.

172

"maxAverageCpmBidAmountMicros": "A String", # The maximum average CPM that may be bid, in micros of the advertiser's

173

# currency. Must be greater than or equal to a billable unit of the given

174

# currency. Not applicable when

175

# performance_goal_type

176

# is set to `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`.

177

#

178

# For example, 1500000 represents 1.5 standard units of the currency.

179

"performanceGoalAmountMicros": "A String", # Required. The performance goal the bidding strategy will attempt to

180

# meet or beat, in micros of the advertiser's currency.

181

# Must be greater than or equal to a billable unit of the given currency and

182

# smaller or equal to upper bounds. Each

183

# performance_goal_type

184

# has its upper bound:

185

#

186

# * when

187

# performance_goal_type

188

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`,

189

# upper bound is 10000.00 USD.

190

# * when

191

# performance_goal_type

192

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`,

193

# upper bound is 1000.00 USD.

194

# * when

195

# performance_goal_type

196

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`, upper bound is

# 1000.00 USD.

#

# Example: If set to

# `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`, the bid price will

201

# be based on the probability that each available impression will be

202

# viewable. For example, if viewable CPM target is $2 and an impression is

203

# 40% likely to be viewable, the bid price will be $0.80 CPM (40% of $2).

204

#

205

# For example, 1500000 represents 1.5 standard units of the currency.

206

},

207

},

208

"frequencyCap": { # Settings that control the number of times a user may be shown with the same # Required. The frequency capping setting of the insertion order.

209

# ad during a given time period.

210

"unlimited": True or False, # Whether unlimited frequency capping is applied. When this field is set to

211

# `true`, the remaining frequency cap fields are not applicable.

212

"maxImpressions": 42, # The maximum number of times a user may be shown with the same ad

213

# during this period. Must be greater than 0.

214

#

215

# Applicable when unlimited is `false`.

216

"timeUnit": "A String", # The time unit in which the frequency cap will be applied.

217

#

218

# Applicable when unlimited is `false`.

219

"timeUnitCount": 42, # The number of time_unit the frequency cap will

220

# last.

221

#

222

# Applicable when unlimited is `false`.

223

# The following restrictions apply based on the value of

224

# time_unit:

225

#

226

# * `TIME_UNIT_LIFETIME` - this field is output only and will

227

# default to 1

228

# * `TIME_UNIT_MONTHS` - must be between 1 and 2

229

# * `TIME_UNIT_WEEKS` - must be between 1 and 4

230

# * `TIME_UNIT_DAYS` - must be between 1 and 6

231

# * `TIME_UNIT_HOURS` - must be between 1 and 23

232

# * `TIME_UNIT_MINUTES` - must be between 1 and 59

233

},

234

"displayName": "A String", # Required. The display name of the insertion order.

235

#

236

# Must be UTF-8 encoded with a maximum size of 240 bytes.

237

"partnerCosts": [ # The partner costs associated with the insertion order.

238

#

239

# If absent or empty in

240

# CreateInsertionOrder

241

# method, the newly created insertion order will inherit partner costs from

242

# the partner settings.

243

{ # Settings that control a partner cost.

244

#

245

# A partner cost is any type of expense involved in running a campaign, other

246

# than the costs of purchasing impressions (which is called the media cost)

247

# and using third-party audience segment data (data fee). Some examples of

248

# partner costs include the fees for using DV360, a third-party ad server,

249

# or a third-party ad serving verification service.

250

"feeAmount": "A String", # The CPM fee amount in micros of advertiser's currency.

251

#

252

# Applicable when the fee_type is

253

# `PARTNER_FEE_TYPE_CPM_FEE`. Must be greater than or equal to 0.

254

#

255

# For example, for 1.5 standard unit of the advertiser's currency, set

256

# this field to 1500000.

257

"costType": "A String", # Required. The type of the partner cost.

258

"feeType": "A String", # Required. The fee type for this partner cost.

259

"feePercentageMillis": "A String", # The media fee percentage in millis (1/1000 of a percent).

260

#

261

# Applicable when the fee_type is

262

# `PARTNER_FEE_TYPE_MEDIA_FEE`. Must be greater than or equal to 0.

263

#

264

# For example: 100 represents 0.1%.

265

"invoiceType": "A String", # The invoice type for this partner cost.

266

#

267

# * Required when cost_type is one of:

268

# - `PARTNER_COST_TYPE_ADLOOX`

269

# - `PARTNER_COST_TYPE_DOUBLE_VERIFY`

270

# - `PARTNER_COST_TYPE_INTEGRAL_AD_SCIENCE`.

271

# * Output only for other types.

272

},

273

],

274

"updateTime": "A String", # Output only. The timestamp when the insertion order was last updated.

275

# Assigned by the system.

276

"advertiserId": "A String", # Output only. The unique ID of the advertiser the insertion order belongs to.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

277

"budget": { # Settings that control how insertion order budget is allocated. # Required. The budget allocation settings of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

278

"budgetSegments": [ # Required. The list of budget segments. Use a budget segment to specify

279

# a specific budget for a given period of time an insertion order is running.

280

{ # Settings that control the budget of a single budget segment.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

281

"budgetAmountMicros": "A String", # Required. The budget amount the insertion order will spend for the given

282

# date_range.

283

# The amount is in micros. Must be greater than 0. For example, 500000000

284

# represents 500 standard units of the currency.

285

"dateRange": { # A date range. # Required. The start and end date settings of the budget segment. They are resolved

286

# relative to the parent advertiser's time zone.

287

#

288

# * When creating a new budget segment, both `start_date` and `end_date`

289

# must be in the future.

290

# * An existing budget segment with a `start_date` in the past has a mutable

291

# `end_date` but an immutable `start_date`.

292

# * `end_date` must be the `start_date` or later, both before the year 2037.

293

"endDate": { # Represents a whole or partial calendar date, e.g. a birthday. The time of day # The upper bound of the date range, inclusive. Must specify a positive value

294

# for `year`, `month`, and `day`.

295

# and time zone are either specified elsewhere or are not significant. The date

296

# is relative to the Proleptic Gregorian Calendar. This can represent:

297

#

298

# * A full date, with non-zero year, month and day values

299

# * A month and day value, with a zero year, e.g. an anniversary

300

# * A year on its own, with zero month and day values

301

# * A year and month value, with a zero day, e.g. a credit card expiration date

302

#

303

# Related types are google.type.TimeOfDay and `google.protobuf.Timestamp`.

304

"year": 42, # Year of date. Must be from 1 to 9999, or 0 if specifying a date without

305

# a year.

306

"day": 42, # Day of month. Must be from 1 to 31 and valid for the year and month, or 0

307

# if specifying a year by itself or a year and month where the day is not

308

# significant.

309

"month": 42, # Month of year. Must be from 1 to 12, or 0 if specifying a year without a

310

# month and day.

311

},

312

"startDate": { # Represents a whole or partial calendar date, e.g. a birthday. The time of day # The lower bound of the date range, inclusive. Must specify a positive value

313

# for `year`, `month`, and `day`.

314

# and time zone are either specified elsewhere or are not significant. The date

315

# is relative to the Proleptic Gregorian Calendar. This can represent:

316

#

317

# * A full date, with non-zero year, month and day values

318

# * A month and day value, with a zero year, e.g. an anniversary

319

# * A year on its own, with zero month and day values

320

# * A year and month value, with a zero day, e.g. a credit card expiration date

321

#

322

# Related types are google.type.TimeOfDay and `google.protobuf.Timestamp`.

323

"year": 42, # Year of date. Must be from 1 to 9999, or 0 if specifying a date without

324

# a year.

325

"day": 42, # Day of month. Must be from 1 to 31 and valid for the year and month, or 0

326

# if specifying a year by itself or a year and month where the day is not

327

# significant.

328

"month": 42, # Month of year. Must be from 1 to 12, or 0 if specifying a year without a

# month and day.

},

},

"description": "A String", # The budget segment description. It can be used to enter Purchase Order

333

# information for each budget segment and have that information printed on

334

# the invoices.

335

#

336

# Must be UTF-8 encoded with a length of no more than 80 characters.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

337

"campaignBudgetId": "A String", # The ID of the campaign budget linked to this insertion order budget

338

# segment.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

339

},

340

],

341

"automationType": "A String", # The type of automation used to manage bid and budget for

342

# the insertion order.

343

#

344

# If this field is unspecified in creation, the value defaults to

345

# `INSERTION_ORDER_AUTOMATION_TYPE_NONE`.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

346

"budgetUnit": "A String", # Required. Immutable. The budget unit specifies whether the budget is currency based or

347

# impression based.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

348

},

349

"entityStatus": "A String", # Required. Controls whether or not the insertion order can spend its budget

350

# and bid on inventory.

351

#

352

# * For

353

# CreateInsertionOrder method,

354

# only `ENTITY_STATUS_DRAFT` is allowed. To activate an insertion order, use

355

# UpdateInsertionOrder method

356

# and update the status to `ENTITY_STATUS_ACTIVE` after creation.

357

# * An insertion order cannot be changed back to `ENTITY_STATUS_DRAFT` status

358

# from any other status.

359

# * An insertion order cannot be set to `ENTITY_STATUS_ACTIVE` if its parent

360

# campaign is not active.

361

"pacing": { # Settings that control the rate at which a budget is spent. # Required. The budget spending speed setting of the insertion order.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

362

"pacingPeriod": "A String", # Required. The time period in which the pacing budget will be spent.

363

#

364

# When automatic budget allocation is enabled at the insertion order via

365

# auto_budget_allocation, this

366

# field is output only and defaults to `PACING_PERIOD_FLIGHT`.

367

"pacingType": "A String", # Required. The type of pacing that defines how the budget amount will be

368

# spent across the pacing_period.

369

"dailyMaxImpressions": "A String", # Maximum number of impressions to serve every day.

370

#

371

# Applicable when the budget is impression based. Must be greater than 0.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

372

"dailyMaxMicros": "A String", # Maximum currency amount to spend every day in micros of

373

# advertiser's currency.

374

#

375

# Applicable when the budget is currency based. Must be greater than 0.

376

# For example, for 1.5 standard unit of the currency, set this field to

377

# 1500000.

378

#

379

# The value assigned will be rounded to whole billable units for the

380

# relevant currency by the following rules: any positive value less than a

381

# single billable unit will be rounded up to one billable unit and any

382

# value larger than a single billable unit will be rounded down to the

383

# nearest billable value. For example, if the currency's billable unit is

384

# 0.01, and this field is set to 10257770, it will round down to 10250000,

385

# a value of 10.25. If set to 505, it will round up to 10000, a value of

386

# 0.01.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

387

},

388

"performanceGoal": { # Settings that control the performance goal of a campaign or insertion order. # Required. Performance goal of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

389

"performanceGoalAmountMicros": "A String", # The goal amount, in micros of the advertiser's currency.

390

#

391

# Applicable when

392

# performance_goal_type is one of:

393

#

394

# * `PERFORMANCE_GOAL_TYPE_CPM`

395

# * `PERFORMANCE_GOAL_TYPE_CPC`

396

# * `PERFORMANCE_GOAL_TYPE_CPA`

397

# * `PERFORMANCE_GOAL_TYPE_CPIAVC`

398

#

399

# For example 1500000 represents 1.5 standard units of the currency.

400

"performanceGoalPercentageMicros": "A String", # The decimal representation of the goal percentage in micros.

401

#

402

# Applicable when

403

# performance_goal_type is one of:

404

#

405

# * `PERFORMANCE_GOAL_TYPE_CTR`

406

# * `PERFORMANCE_GOAL_TYPE_VIEWABILITY`

407

#

408

# For example, 70000 represents 7% (decimal 0.07).

409

"performanceGoalString": "A String", # A key performance indicator (KPI) string, which can be empty.

410

# Must be UTF-8 encoded with a length of no more than 100 characters.

411

#

412

# Applicable when

413

# performance_goal_type is set to

414

# `PERFORMANCE_GOAL_TYPE_OTHER`.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

415

"performanceGoalType": "A String", # Required. The type of the performance goal.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

416

},

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

417

"insertionOrderId": "A String", # Output only. The unique ID of the insertion order. Assigned by the system.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

418

"campaignId": "A String", # Required. Immutable. The unique ID of the campaign that the insertion order belongs to.

419

"name": "A String", # Output only. The resource name of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

420

"integrationDetails": { # Integration details of an entry. # Additional integration details of the insertion order.

421

"details": "A String", # Additional details of the entry in string format.

422

#

423

# Must be UTF-8 encoded with a length of no more than 1000 characters.

424

"integrationCode": "A String", # An external identifier to be associated with the entry.

425

# The integration code will show up together with the entry in many

426

# places in the system, for example, reporting.

427

#

428

# Must be UTF-8 encoded with a length of no more than 500 characters.

429

},

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

430

}

431

432

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

439

440

{ # A single insertion order.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

441

"bidStrategy": { # Settings that control the bid strategy. # Optional. The bidding strategy of the insertion order. By default,

442

# fixed_bid is set.

443

# Bid strategy determines the bid price.

444

"fixedBid": { # A strategy that uses a fixed bidding price. # A strategy that uses a fixed bid price.

445

"bidAmountMicros": "A String", # The fixed bid amount, in micros of the advertiser's currency.

446

# For insertion order entity,

447

# bid_amount_micros should be set as 0.

448

# For line item entity,

449

# bid_amount_micros must be greater

450

# than or equal to billable unit of the given currency and smaller than or

451

# equal to the upper limit 1000000000.

452

#

453

# For example, 1500000 represents 1.5 standard units of the currency.

454

},

455

"maximizeSpendAutoBid": { # A strategy that automatically adjusts the bid to optimize a specified # A strategy that automatically adjusts the bid to optimize to your

456

# performance goal while spending the full budget.

457

#

458

# At insertion order level, the

459

# markup_type of line items

460

# cannot be set to `PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM`. In addition,

461

# when

462

# performance_goal_type

463

# is one of:

464

#

465

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`

466

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`

467

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_AV_VIEWED` ,

468

#

469

# the line_item_type

470

# of the insertion order line items must be either:

471

#

472

# * `LINE_ITEM_TYPE_DISPLAY_DEFAULT`

473

# * `LINE_ITEM_TYPE_VIDEO_DEFAULT` ,

474

#

475

# and when

476

# performance_goal_type

477

# is either:

478

#

479

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CIVA`

480

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_IVO_TEN`

481

#

482

# the line_item_type

483

# of the insertion order line items must be `LINE_ITEM_TYPE_VIDEO_DEFAULT`.

484

# performance goal while spending the full budget.

485

"performanceGoalType": "A String", # Required. The type of the performance goal that the bidding strategy

486

# tries to minimize while spending the full budget.

487

# `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM` is not supported for

488

# this strategy.

489

"maxAverageCpmBidAmountMicros": "A String", # The maximum average CPM that may be bid, in micros of the advertiser's

490

# currency. Must be greater than or equal to a billable unit of the given

491

# currency.

492

#

493

# For example, 1500000 represents 1.5 standard units of the currency.

494

},

495

"performanceGoalAutoBid": { # A strategy that automatically adjusts the bid to meet or beat a specified # A strategy that automatically adjusts the bid to meet or beat a specified

496

# performance goal. It is to be used only for a line item entity.

497

# performance goal.

498

"performanceGoalType": "A String", # Required. The type of the performance goal that the bidding strategy

499

# will try to meet or beat.

500

#

501

# For line item level usage, the value must be one of:

502

#

503

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`

504

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`

505

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`.

506

"maxAverageCpmBidAmountMicros": "A String", # The maximum average CPM that may be bid, in micros of the advertiser's

507

# currency. Must be greater than or equal to a billable unit of the given

508

# currency. Not applicable when

509

# performance_goal_type

510

# is set to `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`.

511

#

512

# For example, 1500000 represents 1.5 standard units of the currency.

513

"performanceGoalAmountMicros": "A String", # Required. The performance goal the bidding strategy will attempt to

514

# meet or beat, in micros of the advertiser's currency.

515

# Must be greater than or equal to a billable unit of the given currency and

516

# smaller or equal to upper bounds. Each

517

# performance_goal_type

518

# has its upper bound:

519

#

520

# * when

521

# performance_goal_type

522

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`,

523

# upper bound is 10000.00 USD.

524

# * when

525

# performance_goal_type

526

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`,

527

# upper bound is 1000.00 USD.

528

# * when

529

# performance_goal_type

530

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`, upper bound is

# 1000.00 USD.

#

# Example: If set to

# `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`, the bid price will

535

# be based on the probability that each available impression will be

536

# viewable. For example, if viewable CPM target is $2 and an impression is

537

# 40% likely to be viewable, the bid price will be $0.80 CPM (40% of $2).

538

#

539

# For example, 1500000 represents 1.5 standard units of the currency.

540

},

541

},

542

"frequencyCap": { # Settings that control the number of times a user may be shown with the same # Required. The frequency capping setting of the insertion order.

543

# ad during a given time period.

544

"unlimited": True or False, # Whether unlimited frequency capping is applied. When this field is set to

545

# `true`, the remaining frequency cap fields are not applicable.

546

"maxImpressions": 42, # The maximum number of times a user may be shown with the same ad

547

# during this period. Must be greater than 0.

548

#

549

# Applicable when unlimited is `false`.

550

"timeUnit": "A String", # The time unit in which the frequency cap will be applied.

551

#

552

# Applicable when unlimited is `false`.

553

"timeUnitCount": 42, # The number of time_unit the frequency cap will

554

# last.

555

#

556

# Applicable when unlimited is `false`.

557

# The following restrictions apply based on the value of

558

# time_unit:

559

#

560

# * `TIME_UNIT_LIFETIME` - this field is output only and will

561

# default to 1

562

# * `TIME_UNIT_MONTHS` - must be between 1 and 2

563

# * `TIME_UNIT_WEEKS` - must be between 1 and 4

564

# * `TIME_UNIT_DAYS` - must be between 1 and 6

565

# * `TIME_UNIT_HOURS` - must be between 1 and 23

566

# * `TIME_UNIT_MINUTES` - must be between 1 and 59

567

},

568

"displayName": "A String", # Required. The display name of the insertion order.

569

#

570

# Must be UTF-8 encoded with a maximum size of 240 bytes.

571

"partnerCosts": [ # The partner costs associated with the insertion order.

572

#

573

# If absent or empty in

574

# CreateInsertionOrder

575

# method, the newly created insertion order will inherit partner costs from

576

# the partner settings.

577

{ # Settings that control a partner cost.

578

#

579

# A partner cost is any type of expense involved in running a campaign, other

580

# than the costs of purchasing impressions (which is called the media cost)

581

# and using third-party audience segment data (data fee). Some examples of

582

# partner costs include the fees for using DV360, a third-party ad server,

583

# or a third-party ad serving verification service.

584

"feeAmount": "A String", # The CPM fee amount in micros of advertiser's currency.

585

#

586

# Applicable when the fee_type is

587

# `PARTNER_FEE_TYPE_CPM_FEE`. Must be greater than or equal to 0.

588

#

589

# For example, for 1.5 standard unit of the advertiser's currency, set

590

# this field to 1500000.

591

"costType": "A String", # Required. The type of the partner cost.

592

"feeType": "A String", # Required. The fee type for this partner cost.

593

"feePercentageMillis": "A String", # The media fee percentage in millis (1/1000 of a percent).

594

#

595

# Applicable when the fee_type is

596

# `PARTNER_FEE_TYPE_MEDIA_FEE`. Must be greater than or equal to 0.

597

#

598

# For example: 100 represents 0.1%.

599

"invoiceType": "A String", # The invoice type for this partner cost.

600

#

601

# * Required when cost_type is one of:

602

# - `PARTNER_COST_TYPE_ADLOOX`

603

# - `PARTNER_COST_TYPE_DOUBLE_VERIFY`

604

# - `PARTNER_COST_TYPE_INTEGRAL_AD_SCIENCE`.

605

# * Output only for other types.

606

},

607

],

608

"updateTime": "A String", # Output only. The timestamp when the insertion order was last updated.

609

# Assigned by the system.

610

"advertiserId": "A String", # Output only. The unique ID of the advertiser the insertion order belongs to.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

611

"budget": { # Settings that control how insertion order budget is allocated. # Required. The budget allocation settings of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

612

"budgetSegments": [ # Required. The list of budget segments. Use a budget segment to specify

613

# a specific budget for a given period of time an insertion order is running.

614

{ # Settings that control the budget of a single budget segment.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

615

"budgetAmountMicros": "A String", # Required. The budget amount the insertion order will spend for the given

616

# date_range.

617

# The amount is in micros. Must be greater than 0. For example, 500000000

618

# represents 500 standard units of the currency.

619

"dateRange": { # A date range. # Required. The start and end date settings of the budget segment. They are resolved

620

# relative to the parent advertiser's time zone.

621

#

622

# * When creating a new budget segment, both `start_date` and `end_date`

623

# must be in the future.

624

# * An existing budget segment with a `start_date` in the past has a mutable

625

# `end_date` but an immutable `start_date`.

626

# * `end_date` must be the `start_date` or later, both before the year 2037.

627

"endDate": { # Represents a whole or partial calendar date, e.g. a birthday. The time of day # The upper bound of the date range, inclusive. Must specify a positive value

628

# for `year`, `month`, and `day`.

629

# and time zone are either specified elsewhere or are not significant. The date

630

# is relative to the Proleptic Gregorian Calendar. This can represent:

631

#

632

# * A full date, with non-zero year, month and day values

633

# * A month and day value, with a zero year, e.g. an anniversary

634

# * A year on its own, with zero month and day values

635

# * A year and month value, with a zero day, e.g. a credit card expiration date

636

#

637

# Related types are google.type.TimeOfDay and `google.protobuf.Timestamp`.

638

"year": 42, # Year of date. Must be from 1 to 9999, or 0 if specifying a date without

639

# a year.

640

"day": 42, # Day of month. Must be from 1 to 31 and valid for the year and month, or 0

641

# if specifying a year by itself or a year and month where the day is not

642

# significant.

643

"month": 42, # Month of year. Must be from 1 to 12, or 0 if specifying a year without a

644

# month and day.

645

},

646

"startDate": { # Represents a whole or partial calendar date, e.g. a birthday. The time of day # The lower bound of the date range, inclusive. Must specify a positive value

647

# for `year`, `month`, and `day`.

648

# and time zone are either specified elsewhere or are not significant. The date

649

# is relative to the Proleptic Gregorian Calendar. This can represent:

650

#

651

# * A full date, with non-zero year, month and day values

652

# * A month and day value, with a zero year, e.g. an anniversary

653

# * A year on its own, with zero month and day values

654

# * A year and month value, with a zero day, e.g. a credit card expiration date

655

#

656

# Related types are google.type.TimeOfDay and `google.protobuf.Timestamp`.

657

"year": 42, # Year of date. Must be from 1 to 9999, or 0 if specifying a date without

658

# a year.

659

"day": 42, # Day of month. Must be from 1 to 31 and valid for the year and month, or 0

660

# if specifying a year by itself or a year and month where the day is not

661

# significant.

662

"month": 42, # Month of year. Must be from 1 to 12, or 0 if specifying a year without a

# month and day.

},

},

"description": "A String", # The budget segment description. It can be used to enter Purchase Order

667

# information for each budget segment and have that information printed on

668

# the invoices.

669

#

670

# Must be UTF-8 encoded with a length of no more than 80 characters.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

671

"campaignBudgetId": "A String", # The ID of the campaign budget linked to this insertion order budget

672

# segment.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

673

},

674

],

675

"automationType": "A String", # The type of automation used to manage bid and budget for

676

# the insertion order.

677

#

678

# If this field is unspecified in creation, the value defaults to

679

# `INSERTION_ORDER_AUTOMATION_TYPE_NONE`.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

680

"budgetUnit": "A String", # Required. Immutable. The budget unit specifies whether the budget is currency based or

681

# impression based.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

682

},

683

"entityStatus": "A String", # Required. Controls whether or not the insertion order can spend its budget

684

# and bid on inventory.

685

#

686

# * For

687

# CreateInsertionOrder method,

688

# only `ENTITY_STATUS_DRAFT` is allowed. To activate an insertion order, use

689

# UpdateInsertionOrder method

690

# and update the status to `ENTITY_STATUS_ACTIVE` after creation.

691

# * An insertion order cannot be changed back to `ENTITY_STATUS_DRAFT` status

692

# from any other status.

693

# * An insertion order cannot be set to `ENTITY_STATUS_ACTIVE` if its parent

694

# campaign is not active.

695

"pacing": { # Settings that control the rate at which a budget is spent. # Required. The budget spending speed setting of the insertion order.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

696

"pacingPeriod": "A String", # Required. The time period in which the pacing budget will be spent.

697

#

698

# When automatic budget allocation is enabled at the insertion order via

699

# auto_budget_allocation, this

700

# field is output only and defaults to `PACING_PERIOD_FLIGHT`.

701

"pacingType": "A String", # Required. The type of pacing that defines how the budget amount will be

702

# spent across the pacing_period.

703

"dailyMaxImpressions": "A String", # Maximum number of impressions to serve every day.

704

#

705

# Applicable when the budget is impression based. Must be greater than 0.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

706

"dailyMaxMicros": "A String", # Maximum currency amount to spend every day in micros of

707

# advertiser's currency.

708

#

709

# Applicable when the budget is currency based. Must be greater than 0.

710

# For example, for 1.5 standard unit of the currency, set this field to

711

# 1500000.

712

#

713

# The value assigned will be rounded to whole billable units for the

714

# relevant currency by the following rules: any positive value less than a

715

# single billable unit will be rounded up to one billable unit and any

716

# value larger than a single billable unit will be rounded down to the

717

# nearest billable value. For example, if the currency's billable unit is

718

# 0.01, and this field is set to 10257770, it will round down to 10250000,

719

# a value of 10.25. If set to 505, it will round up to 10000, a value of

720

# 0.01.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

721

},

722

"performanceGoal": { # Settings that control the performance goal of a campaign or insertion order. # Required. Performance goal of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

723

"performanceGoalAmountMicros": "A String", # The goal amount, in micros of the advertiser's currency.

724

#

725

# Applicable when

726

# performance_goal_type is one of:

727

#

728

# * `PERFORMANCE_GOAL_TYPE_CPM`

729

# * `PERFORMANCE_GOAL_TYPE_CPC`

730

# * `PERFORMANCE_GOAL_TYPE_CPA`

731

# * `PERFORMANCE_GOAL_TYPE_CPIAVC`

732

#

733

# For example 1500000 represents 1.5 standard units of the currency.

734

"performanceGoalPercentageMicros": "A String", # The decimal representation of the goal percentage in micros.

735

#

736

# Applicable when

737

# performance_goal_type is one of:

738

#

739

# * `PERFORMANCE_GOAL_TYPE_CTR`

740

# * `PERFORMANCE_GOAL_TYPE_VIEWABILITY`

741

#

742

# For example, 70000 represents 7% (decimal 0.07).

743

"performanceGoalString": "A String", # A key performance indicator (KPI) string, which can be empty.

744

# Must be UTF-8 encoded with a length of no more than 100 characters.

745

#

746

# Applicable when

747

# performance_goal_type is set to

748

# `PERFORMANCE_GOAL_TYPE_OTHER`.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

749

"performanceGoalType": "A String", # Required. The type of the performance goal.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

750

},

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

751

"insertionOrderId": "A String", # Output only. The unique ID of the insertion order. Assigned by the system.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

752

"campaignId": "A String", # Required. Immutable. The unique ID of the campaign that the insertion order belongs to.

753

"name": "A String", # Output only. The resource name of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

754

"integrationDetails": { # Integration details of an entry. # Additional integration details of the insertion order.

755

"details": "A String", # Additional details of the entry in string format.

756

#

757

# Must be UTF-8 encoded with a length of no more than 1000 characters.

758

"integrationCode": "A String", # An external identifier to be associated with the entry.

759

# The integration code will show up together with the entry in many

760

# places in the system, for example, reporting.

761

#

762

# Must be UTF-8 encoded with a length of no more than 500 characters.

763

},

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

}</pre>

</div>

<code class="details" id="delete">delete(advertiserId, insertionOrderId, x__xgafv=None)</code>

769

<pre>Deletes an insertion order.

770

Returns error code `NOT_FOUND` if the insertion order does not exist.

771

The insertion order should be archived first, i.e. set

772

entity_status to `ENTITY_STATUS_ARCHIVED`,

773

to be able to delete it.

774

775

Args:

776

advertiserId: string, The ID of the advertiser this insertion order belongs to. (required)

777

insertionOrderId: string, The ID of the insertion order we need to delete. (required)

778

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

785

786

{ # A generic empty message that you can re-use to avoid defining duplicated

787

# empty messages in your APIs. A typical example is to use it as the request

788

# or the response type of an API method. For instance:

789

#

790

# service Foo {

791

# rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);

792

# }

793

#

794

# The JSON representation for `Empty` is empty JSON object `{}`.

}</pre>

</div>

<code class="details" id="get">get(advertiserId, insertionOrderId, x__xgafv=None)</code>

800

<pre>Gets an insertion order.

801

Returns error code `NOT_FOUND` if the insertion order does not exist.

802

803

Args:

804

advertiserId: string, Required. The ID of the advertiser this insertion order belongs to. (required)

805

insertionOrderId: string, Required. The ID of the insertion order to fetch. (required)

806

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

813

814

{ # A single insertion order.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

815

"bidStrategy": { # Settings that control the bid strategy. # Optional. The bidding strategy of the insertion order. By default,

816

# fixed_bid is set.

817

# Bid strategy determines the bid price.

818

"fixedBid": { # A strategy that uses a fixed bidding price. # A strategy that uses a fixed bid price.

819

"bidAmountMicros": "A String", # The fixed bid amount, in micros of the advertiser's currency.

820

# For insertion order entity,

821

# bid_amount_micros should be set as 0.

822

# For line item entity,

823

# bid_amount_micros must be greater

824

# than or equal to billable unit of the given currency and smaller than or

825

# equal to the upper limit 1000000000.

826

#

827

# For example, 1500000 represents 1.5 standard units of the currency.

828

},

829

"maximizeSpendAutoBid": { # A strategy that automatically adjusts the bid to optimize a specified # A strategy that automatically adjusts the bid to optimize to your

830

# performance goal while spending the full budget.

831

#

832

# At insertion order level, the

833

# markup_type of line items

834

# cannot be set to `PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM`. In addition,

835

# when

836

# performance_goal_type

837

# is one of:

838

#

839

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`

840

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`

841

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_AV_VIEWED` ,

842

#

843

# the line_item_type

844

# of the insertion order line items must be either:

845

#

846

# * `LINE_ITEM_TYPE_DISPLAY_DEFAULT`

847

# * `LINE_ITEM_TYPE_VIDEO_DEFAULT` ,

848

#

849

# and when

850

# performance_goal_type

851

# is either:

852

#

853

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CIVA`

854

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_IVO_TEN`

855

#

856

# the line_item_type

857

# of the insertion order line items must be `LINE_ITEM_TYPE_VIDEO_DEFAULT`.

858

# performance goal while spending the full budget.

859

"performanceGoalType": "A String", # Required. The type of the performance goal that the bidding strategy

860

# tries to minimize while spending the full budget.

861

# `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM` is not supported for

862

# this strategy.

863

"maxAverageCpmBidAmountMicros": "A String", # The maximum average CPM that may be bid, in micros of the advertiser's

864

# currency. Must be greater than or equal to a billable unit of the given

865

# currency.

866

#

867

# For example, 1500000 represents 1.5 standard units of the currency.

868

},

869

"performanceGoalAutoBid": { # A strategy that automatically adjusts the bid to meet or beat a specified # A strategy that automatically adjusts the bid to meet or beat a specified

870

# performance goal. It is to be used only for a line item entity.

871

# performance goal.

872

"performanceGoalType": "A String", # Required. The type of the performance goal that the bidding strategy

873

# will try to meet or beat.

874

#

875

# For line item level usage, the value must be one of:

876

#

877

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`

878

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`

879

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`.

880

"maxAverageCpmBidAmountMicros": "A String", # The maximum average CPM that may be bid, in micros of the advertiser's

881

# currency. Must be greater than or equal to a billable unit of the given

882

# currency. Not applicable when

883

# performance_goal_type

884

# is set to `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`.

885

#

886

# For example, 1500000 represents 1.5 standard units of the currency.

887

"performanceGoalAmountMicros": "A String", # Required. The performance goal the bidding strategy will attempt to

888

# meet or beat, in micros of the advertiser's currency.

889

# Must be greater than or equal to a billable unit of the given currency and

890

# smaller or equal to upper bounds. Each

891

# performance_goal_type

892

# has its upper bound:

893

#

894

# * when

895

# performance_goal_type

896

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`,

897

# upper bound is 10000.00 USD.

898

# * when

899

# performance_goal_type

900

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`,

901

# upper bound is 1000.00 USD.

902

# * when

903

# performance_goal_type

904

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`, upper bound is

# 1000.00 USD.

#

# Example: If set to

# `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`, the bid price will

909

# be based on the probability that each available impression will be

910

# viewable. For example, if viewable CPM target is $2 and an impression is

911

# 40% likely to be viewable, the bid price will be $0.80 CPM (40% of $2).

912

#

913

# For example, 1500000 represents 1.5 standard units of the currency.

914

},

915

},

916

"frequencyCap": { # Settings that control the number of times a user may be shown with the same # Required. The frequency capping setting of the insertion order.

917

# ad during a given time period.

918

"unlimited": True or False, # Whether unlimited frequency capping is applied. When this field is set to

919

# `true`, the remaining frequency cap fields are not applicable.

920

"maxImpressions": 42, # The maximum number of times a user may be shown with the same ad

921

# during this period. Must be greater than 0.

922

#

923

# Applicable when unlimited is `false`.

924

"timeUnit": "A String", # The time unit in which the frequency cap will be applied.

925

#

926

# Applicable when unlimited is `false`.

927

"timeUnitCount": 42, # The number of time_unit the frequency cap will

928

# last.

929

#

930

# Applicable when unlimited is `false`.

931

# The following restrictions apply based on the value of

932

# time_unit:

933

#

934

# * `TIME_UNIT_LIFETIME` - this field is output only and will

935

# default to 1

936

# * `TIME_UNIT_MONTHS` - must be between 1 and 2

937

# * `TIME_UNIT_WEEKS` - must be between 1 and 4

938

# * `TIME_UNIT_DAYS` - must be between 1 and 6

939

# * `TIME_UNIT_HOURS` - must be between 1 and 23

940

# * `TIME_UNIT_MINUTES` - must be between 1 and 59

941

},

942

"displayName": "A String", # Required. The display name of the insertion order.

943

#

944

# Must be UTF-8 encoded with a maximum size of 240 bytes.

945

"partnerCosts": [ # The partner costs associated with the insertion order.

946

#

947

# If absent or empty in

948

# CreateInsertionOrder

949

# method, the newly created insertion order will inherit partner costs from

950

# the partner settings.

951

{ # Settings that control a partner cost.

952

#

953

# A partner cost is any type of expense involved in running a campaign, other

954

# than the costs of purchasing impressions (which is called the media cost)

955

# and using third-party audience segment data (data fee). Some examples of

956

# partner costs include the fees for using DV360, a third-party ad server,

957

# or a third-party ad serving verification service.

958

"feeAmount": "A String", # The CPM fee amount in micros of advertiser's currency.

959

#

960

# Applicable when the fee_type is

961

# `PARTNER_FEE_TYPE_CPM_FEE`. Must be greater than or equal to 0.

962

#

963

# For example, for 1.5 standard unit of the advertiser's currency, set

964

# this field to 1500000.

965

"costType": "A String", # Required. The type of the partner cost.

966

"feeType": "A String", # Required. The fee type for this partner cost.

967

"feePercentageMillis": "A String", # The media fee percentage in millis (1/1000 of a percent).

968

#

969

# Applicable when the fee_type is

970

# `PARTNER_FEE_TYPE_MEDIA_FEE`. Must be greater than or equal to 0.

971

#

972

# For example: 100 represents 0.1%.

973

"invoiceType": "A String", # The invoice type for this partner cost.

974

#

975

# * Required when cost_type is one of:

976

# - `PARTNER_COST_TYPE_ADLOOX`

977

# - `PARTNER_COST_TYPE_DOUBLE_VERIFY`

978

# - `PARTNER_COST_TYPE_INTEGRAL_AD_SCIENCE`.

979

# * Output only for other types.

980

},

981

],

982

"updateTime": "A String", # Output only. The timestamp when the insertion order was last updated.

983

# Assigned by the system.

984

"advertiserId": "A String", # Output only. The unique ID of the advertiser the insertion order belongs to.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

985

"budget": { # Settings that control how insertion order budget is allocated. # Required. The budget allocation settings of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

986

"budgetSegments": [ # Required. The list of budget segments. Use a budget segment to specify

987

# a specific budget for a given period of time an insertion order is running.

988

{ # Settings that control the budget of a single budget segment.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

989

"budgetAmountMicros": "A String", # Required. The budget amount the insertion order will spend for the given

990

# date_range.

991

# The amount is in micros. Must be greater than 0. For example, 500000000

992

# represents 500 standard units of the currency.

993

"dateRange": { # A date range. # Required. The start and end date settings of the budget segment. They are resolved

994

# relative to the parent advertiser's time zone.

995

#

996

# * When creating a new budget segment, both `start_date` and `end_date`

997

# must be in the future.

998

# * An existing budget segment with a `start_date` in the past has a mutable

999

# `end_date` but an immutable `start_date`.

1000

# * `end_date` must be the `start_date` or later, both before the year 2037.

1001

"endDate": { # Represents a whole or partial calendar date, e.g. a birthday. The time of day # The upper bound of the date range, inclusive. Must specify a positive value

1002

# for `year`, `month`, and `day`.

1003

# and time zone are either specified elsewhere or are not significant. The date

1004

# is relative to the Proleptic Gregorian Calendar. This can represent:

1005

#

1006

# * A full date, with non-zero year, month and day values

1007

# * A month and day value, with a zero year, e.g. an anniversary

1008

# * A year on its own, with zero month and day values

1009

# * A year and month value, with a zero day, e.g. a credit card expiration date

1010

#

1011

# Related types are google.type.TimeOfDay and `google.protobuf.Timestamp`.

1012

"year": 42, # Year of date. Must be from 1 to 9999, or 0 if specifying a date without

1013

# a year.

1014

"day": 42, # Day of month. Must be from 1 to 31 and valid for the year and month, or 0

1015

# if specifying a year by itself or a year and month where the day is not

1016

# significant.

1017

"month": 42, # Month of year. Must be from 1 to 12, or 0 if specifying a year without a

1018

# month and day.

1019

},

1020

"startDate": { # Represents a whole or partial calendar date, e.g. a birthday. The time of day # The lower bound of the date range, inclusive. Must specify a positive value

1021

# for `year`, `month`, and `day`.

1022

# and time zone are either specified elsewhere or are not significant. The date

1023

# is relative to the Proleptic Gregorian Calendar. This can represent:

1024

#

1025

# * A full date, with non-zero year, month and day values

1026

# * A month and day value, with a zero year, e.g. an anniversary

1027

# * A year on its own, with zero month and day values

1028

# * A year and month value, with a zero day, e.g. a credit card expiration date

1029

#

1030

# Related types are google.type.TimeOfDay and `google.protobuf.Timestamp`.

1031

"year": 42, # Year of date. Must be from 1 to 9999, or 0 if specifying a date without

1032

# a year.

1033

"day": 42, # Day of month. Must be from 1 to 31 and valid for the year and month, or 0

1034

# if specifying a year by itself or a year and month where the day is not

1035

# significant.

1036

"month": 42, # Month of year. Must be from 1 to 12, or 0 if specifying a year without a

# month and day.

},

},

"description": "A String", # The budget segment description. It can be used to enter Purchase Order

1041

# information for each budget segment and have that information printed on

1042

# the invoices.

1043

#

1044

# Must be UTF-8 encoded with a length of no more than 80 characters.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1045

"campaignBudgetId": "A String", # The ID of the campaign budget linked to this insertion order budget

1046

# segment.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1047

},

1048

],

1049

"automationType": "A String", # The type of automation used to manage bid and budget for

1050

# the insertion order.

1051

#

1052

# If this field is unspecified in creation, the value defaults to

1053

# `INSERTION_ORDER_AUTOMATION_TYPE_NONE`.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1054

"budgetUnit": "A String", # Required. Immutable. The budget unit specifies whether the budget is currency based or

1055

# impression based.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1056

},

1057

"entityStatus": "A String", # Required. Controls whether or not the insertion order can spend its budget

1058

# and bid on inventory.

1059

#

1060

# * For

1061

# CreateInsertionOrder method,

1062

# only `ENTITY_STATUS_DRAFT` is allowed. To activate an insertion order, use

1063

# UpdateInsertionOrder method

1064

# and update the status to `ENTITY_STATUS_ACTIVE` after creation.

1065

# * An insertion order cannot be changed back to `ENTITY_STATUS_DRAFT` status

1066

# from any other status.

1067

# * An insertion order cannot be set to `ENTITY_STATUS_ACTIVE` if its parent

1068

# campaign is not active.

1069

"pacing": { # Settings that control the rate at which a budget is spent. # Required. The budget spending speed setting of the insertion order.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1070

"pacingPeriod": "A String", # Required. The time period in which the pacing budget will be spent.

1071

#

1072

# When automatic budget allocation is enabled at the insertion order via

1073

# auto_budget_allocation, this

1074

# field is output only and defaults to `PACING_PERIOD_FLIGHT`.

1075

"pacingType": "A String", # Required. The type of pacing that defines how the budget amount will be

1076

# spent across the pacing_period.

1077

"dailyMaxImpressions": "A String", # Maximum number of impressions to serve every day.

1078

#

1079

# Applicable when the budget is impression based. Must be greater than 0.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1080

"dailyMaxMicros": "A String", # Maximum currency amount to spend every day in micros of

1081

# advertiser's currency.

1082

#

1083

# Applicable when the budget is currency based. Must be greater than 0.

1084

# For example, for 1.5 standard unit of the currency, set this field to

1085

# 1500000.

1086

#

1087

# The value assigned will be rounded to whole billable units for the

1088

# relevant currency by the following rules: any positive value less than a

1089

# single billable unit will be rounded up to one billable unit and any

1090

# value larger than a single billable unit will be rounded down to the

1091

# nearest billable value. For example, if the currency's billable unit is

1092

# 0.01, and this field is set to 10257770, it will round down to 10250000,

1093

# a value of 10.25. If set to 505, it will round up to 10000, a value of

1094

# 0.01.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1095

},

1096

"performanceGoal": { # Settings that control the performance goal of a campaign or insertion order. # Required. Performance goal of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1097

"performanceGoalAmountMicros": "A String", # The goal amount, in micros of the advertiser's currency.

1098

#

1099

# Applicable when

1100

# performance_goal_type is one of:

1101

#

1102

# * `PERFORMANCE_GOAL_TYPE_CPM`

1103

# * `PERFORMANCE_GOAL_TYPE_CPC`

1104

# * `PERFORMANCE_GOAL_TYPE_CPA`

1105

# * `PERFORMANCE_GOAL_TYPE_CPIAVC`

1106

#

1107

# For example 1500000 represents 1.5 standard units of the currency.

1108

"performanceGoalPercentageMicros": "A String", # The decimal representation of the goal percentage in micros.

1109

#

1110

# Applicable when

1111

# performance_goal_type is one of:

1112

#

1113

# * `PERFORMANCE_GOAL_TYPE_CTR`

1114

# * `PERFORMANCE_GOAL_TYPE_VIEWABILITY`

1115

#

1116

# For example, 70000 represents 7% (decimal 0.07).

1117

"performanceGoalString": "A String", # A key performance indicator (KPI) string, which can be empty.

1118

# Must be UTF-8 encoded with a length of no more than 100 characters.

1119

#

1120

# Applicable when

1121

# performance_goal_type is set to

1122

# `PERFORMANCE_GOAL_TYPE_OTHER`.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1123

"performanceGoalType": "A String", # Required. The type of the performance goal.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1124

},

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1125

"insertionOrderId": "A String", # Output only. The unique ID of the insertion order. Assigned by the system.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1126

"campaignId": "A String", # Required. Immutable. The unique ID of the campaign that the insertion order belongs to.

1127

"name": "A String", # Output only. The resource name of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1128

"integrationDetails": { # Integration details of an entry. # Additional integration details of the insertion order.

1129

"details": "A String", # Additional details of the entry in string format.

1130

#

1131

# Must be UTF-8 encoded with a length of no more than 1000 characters.

1132

"integrationCode": "A String", # An external identifier to be associated with the entry.

1133

# The integration code will show up together with the entry in many

1134

# places in the system, for example, reporting.

1135

#

1136

# Must be UTF-8 encoded with a length of no more than 500 characters.

1137

},

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

}</pre>

</div>

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

1142

<code class="details" id="list">list(advertiserId, filter=None, pageToken=None, orderBy=None, pageSize=None, x__xgafv=None)</code>

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1143

<pre>Lists insertion orders in an advertiser.

1144

1145

The order is defined by the order_by

1146

parameter.

1147

If a filter by

1148

entity_status is not specified, insertion

1149

orders with `ENTITY_STATUS_ARCHIVED` will not be included in the results.

1150

1151

Args:

1152

advertiserId: string, Required. The ID of the advertiser to list insertion orders for. (required)

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1153

filter: string, Allows filtering by insertion order properties.

Supported syntax:

* Filter expressions are made up of one or more restrictions.

1158

* Restrictions can be combined by `AND` or `OR` logical operators. A

1159

sequence of restrictions implicitly uses `AND`.

1160

* A restriction has the form of `{field} {operator} {value}`.

1161

* The operator must be `EQUALS (=)`.

* Supported fields:

- `campaignId`

- `entityStatus`

Examples:

* All insertion orders under a campaign: `campaignId="1234"`

1169

* All `ENTITY_STATUS_ACTIVE` or `ENTITY_STATUS_PAUSED` insertion orders

1170

under an advertiser:

1171

`(entityStatus="ENTITY_STATUS_ACTIVE" OR

1172

entityStatus="ENTITY_STATUS_PAUSED")`

1173

1174

The length of this field should be no more than 500 characters.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1175

pageToken: string, A token identifying a page of results the server should return.

1176

Typically, this is the value of

1177

next_page_token returned

1178

from the previous call to `ListInsertionOrders` method. If not specified,

1179

the first page of results will be returned.

1180

orderBy: string, Field by which to sort the list.

1181

Acceptable values are:

1182

1183

* "displayName" (default)

1184

* "entityStatus"

1185

1186

The default sorting order is ascending. To specify descending order for

1187

a field, a suffix "desc" should be added to the field name. Example:

1188

`displayName desc`.

1189

pageSize: integer, Requested page size. Must be between `1` and `100`. If unspecified will

1190

default to `100`. Returns error code `INVALID_ARGUMENT` if an invalid value

1191

is specified.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1192

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1199

1200

{

1201

"insertionOrders": [ # The list of insertion orders.

1202

#

1203

# This list will be absent if empty.

1204

{ # A single insertion order.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1205

"bidStrategy": { # Settings that control the bid strategy. # Optional. The bidding strategy of the insertion order. By default,

1206

# fixed_bid is set.

1207

# Bid strategy determines the bid price.

1208

"fixedBid": { # A strategy that uses a fixed bidding price. # A strategy that uses a fixed bid price.

1209

"bidAmountMicros": "A String", # The fixed bid amount, in micros of the advertiser's currency.

1210

# For insertion order entity,

1211

# bid_amount_micros should be set as 0.

1212

# For line item entity,

1213

# bid_amount_micros must be greater

1214

# than or equal to billable unit of the given currency and smaller than or

1215

# equal to the upper limit 1000000000.

1216

#

1217

# For example, 1500000 represents 1.5 standard units of the currency.

1218

},

1219

"maximizeSpendAutoBid": { # A strategy that automatically adjusts the bid to optimize a specified # A strategy that automatically adjusts the bid to optimize to your

1220

# performance goal while spending the full budget.

1221

#

1222

# At insertion order level, the

1223

# markup_type of line items

1224

# cannot be set to `PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM`. In addition,

1225

# when

1226

# performance_goal_type

1227

# is one of:

1228

#

1229

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`

1230

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`

1231

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_AV_VIEWED` ,

1232

#

1233

# the line_item_type

1234

# of the insertion order line items must be either:

1235

#

1236

# * `LINE_ITEM_TYPE_DISPLAY_DEFAULT`

1237

# * `LINE_ITEM_TYPE_VIDEO_DEFAULT` ,

1238

#

1239

# and when

1240

# performance_goal_type

1241

# is either:

1242

#

1243

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CIVA`

1244

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_IVO_TEN`

1245

#

1246

# the line_item_type

1247

# of the insertion order line items must be `LINE_ITEM_TYPE_VIDEO_DEFAULT`.

1248

# performance goal while spending the full budget.

1249

"performanceGoalType": "A String", # Required. The type of the performance goal that the bidding strategy

1250

# tries to minimize while spending the full budget.

1251

# `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM` is not supported for

1252

# this strategy.

1253

"maxAverageCpmBidAmountMicros": "A String", # The maximum average CPM that may be bid, in micros of the advertiser's

1254

# currency. Must be greater than or equal to a billable unit of the given

1255

# currency.

1256

#

1257

# For example, 1500000 represents 1.5 standard units of the currency.

1258

},

1259

"performanceGoalAutoBid": { # A strategy that automatically adjusts the bid to meet or beat a specified # A strategy that automatically adjusts the bid to meet or beat a specified

1260

# performance goal. It is to be used only for a line item entity.

1261

# performance goal.

1262

"performanceGoalType": "A String", # Required. The type of the performance goal that the bidding strategy

1263

# will try to meet or beat.

1264

#

1265

# For line item level usage, the value must be one of:

1266

#

1267

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`

1268

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`

1269

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`.

1270

"maxAverageCpmBidAmountMicros": "A String", # The maximum average CPM that may be bid, in micros of the advertiser's

1271

# currency. Must be greater than or equal to a billable unit of the given

1272

# currency. Not applicable when

1273

# performance_goal_type

1274

# is set to `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`.

1275

#

1276

# For example, 1500000 represents 1.5 standard units of the currency.

1277

"performanceGoalAmountMicros": "A String", # Required. The performance goal the bidding strategy will attempt to

1278

# meet or beat, in micros of the advertiser's currency.

1279

# Must be greater than or equal to a billable unit of the given currency and

1280

# smaller or equal to upper bounds. Each

1281

# performance_goal_type

1282

# has its upper bound:

1283

#

1284

# * when

1285

# performance_goal_type

1286

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`,

1287

# upper bound is 10000.00 USD.

1288

# * when

1289

# performance_goal_type

1290

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`,

1291

# upper bound is 1000.00 USD.

1292

# * when

1293

# performance_goal_type

1294

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`, upper bound is

# 1000.00 USD.

#

# Example: If set to

# `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`, the bid price will

1299

# be based on the probability that each available impression will be

1300

# viewable. For example, if viewable CPM target is $2 and an impression is

1301

# 40% likely to be viewable, the bid price will be $0.80 CPM (40% of $2).

1302

#

1303

# For example, 1500000 represents 1.5 standard units of the currency.

1304

},

1305

},

1306

"frequencyCap": { # Settings that control the number of times a user may be shown with the same # Required. The frequency capping setting of the insertion order.

1307

# ad during a given time period.

1308

"unlimited": True or False, # Whether unlimited frequency capping is applied. When this field is set to

1309

# `true`, the remaining frequency cap fields are not applicable.

1310

"maxImpressions": 42, # The maximum number of times a user may be shown with the same ad

1311

# during this period. Must be greater than 0.

1312

#

1313

# Applicable when unlimited is `false`.

1314

"timeUnit": "A String", # The time unit in which the frequency cap will be applied.

1315

#

1316

# Applicable when unlimited is `false`.

1317

"timeUnitCount": 42, # The number of time_unit the frequency cap will

1318

# last.

1319

#

1320

# Applicable when unlimited is `false`.

1321

# The following restrictions apply based on the value of

1322

# time_unit:

1323

#

1324

# * `TIME_UNIT_LIFETIME` - this field is output only and will

1325

# default to 1

1326

# * `TIME_UNIT_MONTHS` - must be between 1 and 2

1327

# * `TIME_UNIT_WEEKS` - must be between 1 and 4

1328

# * `TIME_UNIT_DAYS` - must be between 1 and 6

1329

# * `TIME_UNIT_HOURS` - must be between 1 and 23

1330

# * `TIME_UNIT_MINUTES` - must be between 1 and 59

1331

},

1332

"displayName": "A String", # Required. The display name of the insertion order.

1333

#

1334

# Must be UTF-8 encoded with a maximum size of 240 bytes.

1335

"partnerCosts": [ # The partner costs associated with the insertion order.

1336

#

1337

# If absent or empty in

1338

# CreateInsertionOrder

1339

# method, the newly created insertion order will inherit partner costs from

1340

# the partner settings.

1341

{ # Settings that control a partner cost.

1342

#

1343

# A partner cost is any type of expense involved in running a campaign, other

1344

# than the costs of purchasing impressions (which is called the media cost)

1345

# and using third-party audience segment data (data fee). Some examples of

1346

# partner costs include the fees for using DV360, a third-party ad server,

1347

# or a third-party ad serving verification service.

1348

"feeAmount": "A String", # The CPM fee amount in micros of advertiser's currency.

1349

#

1350

# Applicable when the fee_type is

1351

# `PARTNER_FEE_TYPE_CPM_FEE`. Must be greater than or equal to 0.

1352

#

1353

# For example, for 1.5 standard unit of the advertiser's currency, set

1354

# this field to 1500000.

1355

"costType": "A String", # Required. The type of the partner cost.

1356

"feeType": "A String", # Required. The fee type for this partner cost.

1357

"feePercentageMillis": "A String", # The media fee percentage in millis (1/1000 of a percent).

1358

#

1359

# Applicable when the fee_type is

1360

# `PARTNER_FEE_TYPE_MEDIA_FEE`. Must be greater than or equal to 0.

1361

#

1362

# For example: 100 represents 0.1%.

1363

"invoiceType": "A String", # The invoice type for this partner cost.

1364

#

1365

# * Required when cost_type is one of:

1366

# - `PARTNER_COST_TYPE_ADLOOX`

1367

# - `PARTNER_COST_TYPE_DOUBLE_VERIFY`

1368

# - `PARTNER_COST_TYPE_INTEGRAL_AD_SCIENCE`.

1369

# * Output only for other types.

1370

},

1371

],

1372

"updateTime": "A String", # Output only. The timestamp when the insertion order was last updated.

1373

# Assigned by the system.

1374

"advertiserId": "A String", # Output only. The unique ID of the advertiser the insertion order belongs to.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1375

"budget": { # Settings that control how insertion order budget is allocated. # Required. The budget allocation settings of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1376

"budgetSegments": [ # Required. The list of budget segments. Use a budget segment to specify

1377

# a specific budget for a given period of time an insertion order is running.

1378

{ # Settings that control the budget of a single budget segment.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1379

"budgetAmountMicros": "A String", # Required. The budget amount the insertion order will spend for the given

1380

# date_range.

1381

# The amount is in micros. Must be greater than 0. For example, 500000000

1382

# represents 500 standard units of the currency.

1383

"dateRange": { # A date range. # Required. The start and end date settings of the budget segment. They are resolved

1384

# relative to the parent advertiser's time zone.

1385

#

1386

# * When creating a new budget segment, both `start_date` and `end_date`

1387

# must be in the future.

1388

# * An existing budget segment with a `start_date` in the past has a mutable

1389

# `end_date` but an immutable `start_date`.

1390

# * `end_date` must be the `start_date` or later, both before the year 2037.

1391

"endDate": { # Represents a whole or partial calendar date, e.g. a birthday. The time of day # The upper bound of the date range, inclusive. Must specify a positive value

1392

# for `year`, `month`, and `day`.

1393

# and time zone are either specified elsewhere or are not significant. The date

1394

# is relative to the Proleptic Gregorian Calendar. This can represent:

1395

#

1396

# * A full date, with non-zero year, month and day values

1397

# * A month and day value, with a zero year, e.g. an anniversary

1398

# * A year on its own, with zero month and day values

1399

# * A year and month value, with a zero day, e.g. a credit card expiration date

1400

#

1401

# Related types are google.type.TimeOfDay and `google.protobuf.Timestamp`.

1402

"year": 42, # Year of date. Must be from 1 to 9999, or 0 if specifying a date without

1403

# a year.

1404

"day": 42, # Day of month. Must be from 1 to 31 and valid for the year and month, or 0

1405

# if specifying a year by itself or a year and month where the day is not

1406

# significant.

1407

"month": 42, # Month of year. Must be from 1 to 12, or 0 if specifying a year without a

1408

# month and day.

1409

},

1410

"startDate": { # Represents a whole or partial calendar date, e.g. a birthday. The time of day # The lower bound of the date range, inclusive. Must specify a positive value

1411

# for `year`, `month`, and `day`.

1412

# and time zone are either specified elsewhere or are not significant. The date

1413

# is relative to the Proleptic Gregorian Calendar. This can represent:

1414

#

1415

# * A full date, with non-zero year, month and day values

1416

# * A month and day value, with a zero year, e.g. an anniversary

1417

# * A year on its own, with zero month and day values

1418

# * A year and month value, with a zero day, e.g. a credit card expiration date

1419

#

1420

# Related types are google.type.TimeOfDay and `google.protobuf.Timestamp`.

1421

"year": 42, # Year of date. Must be from 1 to 9999, or 0 if specifying a date without

1422

# a year.

1423

"day": 42, # Day of month. Must be from 1 to 31 and valid for the year and month, or 0

1424

# if specifying a year by itself or a year and month where the day is not

1425

# significant.

1426

"month": 42, # Month of year. Must be from 1 to 12, or 0 if specifying a year without a

# month and day.

},

},

"description": "A String", # The budget segment description. It can be used to enter Purchase Order

1431

# information for each budget segment and have that information printed on

1432

# the invoices.

1433

#

1434

# Must be UTF-8 encoded with a length of no more than 80 characters.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1435

"campaignBudgetId": "A String", # The ID of the campaign budget linked to this insertion order budget

1436

# segment.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1437

},

1438

],

1439

"automationType": "A String", # The type of automation used to manage bid and budget for

1440

# the insertion order.

1441

#

1442

# If this field is unspecified in creation, the value defaults to

1443

# `INSERTION_ORDER_AUTOMATION_TYPE_NONE`.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1444

"budgetUnit": "A String", # Required. Immutable. The budget unit specifies whether the budget is currency based or

1445

# impression based.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1446

},

1447

"entityStatus": "A String", # Required. Controls whether or not the insertion order can spend its budget

1448

# and bid on inventory.

1449

#

1450

# * For

1451

# CreateInsertionOrder method,

1452

# only `ENTITY_STATUS_DRAFT` is allowed. To activate an insertion order, use

1453

# UpdateInsertionOrder method

1454

# and update the status to `ENTITY_STATUS_ACTIVE` after creation.

1455

# * An insertion order cannot be changed back to `ENTITY_STATUS_DRAFT` status

1456

# from any other status.

1457

# * An insertion order cannot be set to `ENTITY_STATUS_ACTIVE` if its parent

1458

# campaign is not active.

1459

"pacing": { # Settings that control the rate at which a budget is spent. # Required. The budget spending speed setting of the insertion order.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1460

"pacingPeriod": "A String", # Required. The time period in which the pacing budget will be spent.

1461

#

1462

# When automatic budget allocation is enabled at the insertion order via

1463

# auto_budget_allocation, this

1464

# field is output only and defaults to `PACING_PERIOD_FLIGHT`.

1465

"pacingType": "A String", # Required. The type of pacing that defines how the budget amount will be

1466

# spent across the pacing_period.

1467

"dailyMaxImpressions": "A String", # Maximum number of impressions to serve every day.

1468

#

1469

# Applicable when the budget is impression based. Must be greater than 0.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1470

"dailyMaxMicros": "A String", # Maximum currency amount to spend every day in micros of

1471

# advertiser's currency.

1472

#

1473

# Applicable when the budget is currency based. Must be greater than 0.

1474

# For example, for 1.5 standard unit of the currency, set this field to

1475

# 1500000.

1476

#

1477

# The value assigned will be rounded to whole billable units for the

1478

# relevant currency by the following rules: any positive value less than a

1479

# single billable unit will be rounded up to one billable unit and any

1480

# value larger than a single billable unit will be rounded down to the

1481

# nearest billable value. For example, if the currency's billable unit is

1482

# 0.01, and this field is set to 10257770, it will round down to 10250000,

1483

# a value of 10.25. If set to 505, it will round up to 10000, a value of

1484

# 0.01.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1485

},

1486

"performanceGoal": { # Settings that control the performance goal of a campaign or insertion order. # Required. Performance goal of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1487

"performanceGoalAmountMicros": "A String", # The goal amount, in micros of the advertiser's currency.

1488

#

1489

# Applicable when

1490

# performance_goal_type is one of:

1491

#

1492

# * `PERFORMANCE_GOAL_TYPE_CPM`

1493

# * `PERFORMANCE_GOAL_TYPE_CPC`

1494

# * `PERFORMANCE_GOAL_TYPE_CPA`

1495

# * `PERFORMANCE_GOAL_TYPE_CPIAVC`

1496

#

1497

# For example 1500000 represents 1.5 standard units of the currency.

1498

"performanceGoalPercentageMicros": "A String", # The decimal representation of the goal percentage in micros.

1499

#

1500

# Applicable when

1501

# performance_goal_type is one of:

1502

#

1503

# * `PERFORMANCE_GOAL_TYPE_CTR`

1504

# * `PERFORMANCE_GOAL_TYPE_VIEWABILITY`

1505

#

1506

# For example, 70000 represents 7% (decimal 0.07).

1507

"performanceGoalString": "A String", # A key performance indicator (KPI) string, which can be empty.

1508

# Must be UTF-8 encoded with a length of no more than 100 characters.

1509

#

1510

# Applicable when

1511

# performance_goal_type is set to

1512

# `PERFORMANCE_GOAL_TYPE_OTHER`.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1513

"performanceGoalType": "A String", # Required. The type of the performance goal.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1514

},

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1515

"insertionOrderId": "A String", # Output only. The unique ID of the insertion order. Assigned by the system.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1516

"campaignId": "A String", # Required. Immutable. The unique ID of the campaign that the insertion order belongs to.

1517

"name": "A String", # Output only. The resource name of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1518

"integrationDetails": { # Integration details of an entry. # Additional integration details of the insertion order.

1519

"details": "A String", # Additional details of the entry in string format.

1520

#

1521

# Must be UTF-8 encoded with a length of no more than 1000 characters.

1522

"integrationCode": "A String", # An external identifier to be associated with the entry.

1523

# The integration code will show up together with the entry in many

1524

# places in the system, for example, reporting.

1525

#

1526

# Must be UTF-8 encoded with a length of no more than 500 characters.

1527

},

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1528

},

1529

],

1530

"nextPageToken": "A String", # A token to retrieve the next page of results.

1531

# Pass this value in the page_token

1532

# field in the subsequent call to `ListInsertionOrders` method to retrieve

1533

# the next page of results.

}</pre>

</div>

<code class="details" id="list_next">list_next(previous_request, previous_response)</code>

1539

<pre>Retrieves the next page of results.

1540

1541

Args:

1542

previous_request: The request for the previous page. (required)

1543

previous_response: The response from the request for the previous page. (required)

1544

1545

Returns:

1546

A request object that you can call 'execute()' on to request the next

1547

page. Returns None if there are no more items in the collection.

</pre>

</div>

<code class="details" id="patch">patch(advertiserId, insertionOrderId, body=None, updateMask=None, x__xgafv=None)</code>

1553

<pre>Updates an existing insertion order.

1554

Returns the updated insertion order if successful.

1555

1556

Args:

1557

advertiserId: string, Output only. The unique ID of the advertiser the insertion order belongs to. (required)

1558

insertionOrderId: string, Output only. The unique ID of the insertion order. Assigned by the system. (required)

1559

body: object, The request body.

1560

The object takes the form of:

1561

1562

{ # A single insertion order.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1563

"bidStrategy": { # Settings that control the bid strategy. # Optional. The bidding strategy of the insertion order. By default,

1564

# fixed_bid is set.

1565

# Bid strategy determines the bid price.

1566

"fixedBid": { # A strategy that uses a fixed bidding price. # A strategy that uses a fixed bid price.

1567

"bidAmountMicros": "A String", # The fixed bid amount, in micros of the advertiser's currency.

1568

# For insertion order entity,

1569

# bid_amount_micros should be set as 0.

1570

# For line item entity,

1571

# bid_amount_micros must be greater

1572

# than or equal to billable unit of the given currency and smaller than or

1573

# equal to the upper limit 1000000000.

1574

#

1575

# For example, 1500000 represents 1.5 standard units of the currency.

1576

},

1577

"maximizeSpendAutoBid": { # A strategy that automatically adjusts the bid to optimize a specified # A strategy that automatically adjusts the bid to optimize to your

1578

# performance goal while spending the full budget.

1579

#

1580

# At insertion order level, the

1581

# markup_type of line items

1582

# cannot be set to `PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM`. In addition,

1583

# when

1584

# performance_goal_type

1585

# is one of:

1586

#

1587

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`

1588

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`

1589

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_AV_VIEWED` ,

1590

#

1591

# the line_item_type

1592

# of the insertion order line items must be either:

1593

#

1594

# * `LINE_ITEM_TYPE_DISPLAY_DEFAULT`

1595

# * `LINE_ITEM_TYPE_VIDEO_DEFAULT` ,

1596

#

1597

# and when

1598

# performance_goal_type

1599

# is either:

1600

#

1601

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CIVA`

1602

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_IVO_TEN`

1603

#

1604

# the line_item_type

1605

# of the insertion order line items must be `LINE_ITEM_TYPE_VIDEO_DEFAULT`.

1606

# performance goal while spending the full budget.

1607

"performanceGoalType": "A String", # Required. The type of the performance goal that the bidding strategy

1608

# tries to minimize while spending the full budget.

1609

# `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM` is not supported for

1610

# this strategy.

1611

"maxAverageCpmBidAmountMicros": "A String", # The maximum average CPM that may be bid, in micros of the advertiser's

1612

# currency. Must be greater than or equal to a billable unit of the given

1613

# currency.

1614

#

1615

# For example, 1500000 represents 1.5 standard units of the currency.

1616

},

1617

"performanceGoalAutoBid": { # A strategy that automatically adjusts the bid to meet or beat a specified # A strategy that automatically adjusts the bid to meet or beat a specified

1618

# performance goal. It is to be used only for a line item entity.

1619

# performance goal.

1620

"performanceGoalType": "A String", # Required. The type of the performance goal that the bidding strategy

1621

# will try to meet or beat.

1622

#

1623

# For line item level usage, the value must be one of:

1624

#

1625

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`

1626

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`

1627

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`.

1628

"maxAverageCpmBidAmountMicros": "A String", # The maximum average CPM that may be bid, in micros of the advertiser's

1629

# currency. Must be greater than or equal to a billable unit of the given

1630

# currency. Not applicable when

1631

# performance_goal_type

1632

# is set to `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`.

1633

#

1634

# For example, 1500000 represents 1.5 standard units of the currency.

1635

"performanceGoalAmountMicros": "A String", # Required. The performance goal the bidding strategy will attempt to

1636

# meet or beat, in micros of the advertiser's currency.

1637

# Must be greater than or equal to a billable unit of the given currency and

1638

# smaller or equal to upper bounds. Each

1639

# performance_goal_type

1640

# has its upper bound:

1641

#

1642

# * when

1643

# performance_goal_type

1644

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`,

1645

# upper bound is 10000.00 USD.

1646

# * when

1647

# performance_goal_type

1648

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`,

1649

# upper bound is 1000.00 USD.

1650

# * when

1651

# performance_goal_type

1652

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`, upper bound is

# 1000.00 USD.

#

# Example: If set to

# `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`, the bid price will

1657

# be based on the probability that each available impression will be

1658

# viewable. For example, if viewable CPM target is $2 and an impression is

1659

# 40% likely to be viewable, the bid price will be $0.80 CPM (40% of $2).

1660

#

1661

# For example, 1500000 represents 1.5 standard units of the currency.

1662

},

1663

},

1664

"frequencyCap": { # Settings that control the number of times a user may be shown with the same # Required. The frequency capping setting of the insertion order.

1665

# ad during a given time period.

1666

"unlimited": True or False, # Whether unlimited frequency capping is applied. When this field is set to

1667

# `true`, the remaining frequency cap fields are not applicable.

1668

"maxImpressions": 42, # The maximum number of times a user may be shown with the same ad

1669

# during this period. Must be greater than 0.

1670

#

1671

# Applicable when unlimited is `false`.

1672

"timeUnit": "A String", # The time unit in which the frequency cap will be applied.

1673

#

1674

# Applicable when unlimited is `false`.

1675

"timeUnitCount": 42, # The number of time_unit the frequency cap will

1676

# last.

1677

#

1678

# Applicable when unlimited is `false`.

1679

# The following restrictions apply based on the value of

1680

# time_unit:

1681

#

1682

# * `TIME_UNIT_LIFETIME` - this field is output only and will

1683

# default to 1

1684

# * `TIME_UNIT_MONTHS` - must be between 1 and 2

1685

# * `TIME_UNIT_WEEKS` - must be between 1 and 4

1686

# * `TIME_UNIT_DAYS` - must be between 1 and 6

1687

# * `TIME_UNIT_HOURS` - must be between 1 and 23

1688

# * `TIME_UNIT_MINUTES` - must be between 1 and 59

1689

},

1690

"displayName": "A String", # Required. The display name of the insertion order.

1691

#

1692

# Must be UTF-8 encoded with a maximum size of 240 bytes.

1693

"partnerCosts": [ # The partner costs associated with the insertion order.

1694

#

1695

# If absent or empty in

1696

# CreateInsertionOrder

1697

# method, the newly created insertion order will inherit partner costs from

1698

# the partner settings.

1699

{ # Settings that control a partner cost.

1700

#

1701

# A partner cost is any type of expense involved in running a campaign, other

1702

# than the costs of purchasing impressions (which is called the media cost)

1703

# and using third-party audience segment data (data fee). Some examples of

1704

# partner costs include the fees for using DV360, a third-party ad server,

1705

# or a third-party ad serving verification service.

1706

"feeAmount": "A String", # The CPM fee amount in micros of advertiser's currency.

1707

#

1708

# Applicable when the fee_type is

1709

# `PARTNER_FEE_TYPE_CPM_FEE`. Must be greater than or equal to 0.

1710

#

1711

# For example, for 1.5 standard unit of the advertiser's currency, set

1712

# this field to 1500000.

1713

"costType": "A String", # Required. The type of the partner cost.

1714

"feeType": "A String", # Required. The fee type for this partner cost.

1715

"feePercentageMillis": "A String", # The media fee percentage in millis (1/1000 of a percent).

1716

#

1717

# Applicable when the fee_type is

1718

# `PARTNER_FEE_TYPE_MEDIA_FEE`. Must be greater than or equal to 0.

1719

#

1720

# For example: 100 represents 0.1%.

1721

"invoiceType": "A String", # The invoice type for this partner cost.

1722

#

1723

# * Required when cost_type is one of:

1724

# - `PARTNER_COST_TYPE_ADLOOX`

1725

# - `PARTNER_COST_TYPE_DOUBLE_VERIFY`

1726

# - `PARTNER_COST_TYPE_INTEGRAL_AD_SCIENCE`.

1727

# * Output only for other types.

1728

},

1729

],

1730

"updateTime": "A String", # Output only. The timestamp when the insertion order was last updated.

1731

# Assigned by the system.

1732

"advertiserId": "A String", # Output only. The unique ID of the advertiser the insertion order belongs to.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1733

"budget": { # Settings that control how insertion order budget is allocated. # Required. The budget allocation settings of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1734

"budgetSegments": [ # Required. The list of budget segments. Use a budget segment to specify

1735

# a specific budget for a given period of time an insertion order is running.

1736

{ # Settings that control the budget of a single budget segment.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1737

"budgetAmountMicros": "A String", # Required. The budget amount the insertion order will spend for the given

1738

# date_range.

1739

# The amount is in micros. Must be greater than 0. For example, 500000000

1740

# represents 500 standard units of the currency.

1741

"dateRange": { # A date range. # Required. The start and end date settings of the budget segment. They are resolved

1742

# relative to the parent advertiser's time zone.

1743

#

1744

# * When creating a new budget segment, both `start_date` and `end_date`

1745

# must be in the future.

1746

# * An existing budget segment with a `start_date` in the past has a mutable

1747

# `end_date` but an immutable `start_date`.

1748

# * `end_date` must be the `start_date` or later, both before the year 2037.

1749

"endDate": { # Represents a whole or partial calendar date, e.g. a birthday. The time of day # The upper bound of the date range, inclusive. Must specify a positive value

1750

# for `year`, `month`, and `day`.

1751

# and time zone are either specified elsewhere or are not significant. The date

1752

# is relative to the Proleptic Gregorian Calendar. This can represent:

1753

#

1754

# * A full date, with non-zero year, month and day values

1755

# * A month and day value, with a zero year, e.g. an anniversary

1756

# * A year on its own, with zero month and day values

1757

# * A year and month value, with a zero day, e.g. a credit card expiration date

1758

#

1759

# Related types are google.type.TimeOfDay and `google.protobuf.Timestamp`.

1760

"year": 42, # Year of date. Must be from 1 to 9999, or 0 if specifying a date without

1761

# a year.

1762

"day": 42, # Day of month. Must be from 1 to 31 and valid for the year and month, or 0

1763

# if specifying a year by itself or a year and month where the day is not

1764

# significant.

1765

"month": 42, # Month of year. Must be from 1 to 12, or 0 if specifying a year without a

1766

# month and day.

1767

},

1768

"startDate": { # Represents a whole or partial calendar date, e.g. a birthday. The time of day # The lower bound of the date range, inclusive. Must specify a positive value

1769

# for `year`, `month`, and `day`.

1770

# and time zone are either specified elsewhere or are not significant. The date

1771

# is relative to the Proleptic Gregorian Calendar. This can represent:

1772

#

1773

# * A full date, with non-zero year, month and day values

1774

# * A month and day value, with a zero year, e.g. an anniversary

1775

# * A year on its own, with zero month and day values

1776

# * A year and month value, with a zero day, e.g. a credit card expiration date

1777

#

1778

# Related types are google.type.TimeOfDay and `google.protobuf.Timestamp`.

1779

"year": 42, # Year of date. Must be from 1 to 9999, or 0 if specifying a date without

1780

# a year.

1781

"day": 42, # Day of month. Must be from 1 to 31 and valid for the year and month, or 0

1782

# if specifying a year by itself or a year and month where the day is not

1783

# significant.

1784

"month": 42, # Month of year. Must be from 1 to 12, or 0 if specifying a year without a

# month and day.

},

},

"description": "A String", # The budget segment description. It can be used to enter Purchase Order

1789

# information for each budget segment and have that information printed on

1790

# the invoices.

1791

#

1792

# Must be UTF-8 encoded with a length of no more than 80 characters.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1793

"campaignBudgetId": "A String", # The ID of the campaign budget linked to this insertion order budget

1794

# segment.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1795

},

1796

],

1797

"automationType": "A String", # The type of automation used to manage bid and budget for

1798

# the insertion order.

1799

#

1800

# If this field is unspecified in creation, the value defaults to

1801

# `INSERTION_ORDER_AUTOMATION_TYPE_NONE`.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1802

"budgetUnit": "A String", # Required. Immutable. The budget unit specifies whether the budget is currency based or

1803

# impression based.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1804

},

1805

"entityStatus": "A String", # Required. Controls whether or not the insertion order can spend its budget

1806

# and bid on inventory.

1807

#

1808

# * For

1809

# CreateInsertionOrder method,

1810

# only `ENTITY_STATUS_DRAFT` is allowed. To activate an insertion order, use

1811

# UpdateInsertionOrder method

1812

# and update the status to `ENTITY_STATUS_ACTIVE` after creation.

1813

# * An insertion order cannot be changed back to `ENTITY_STATUS_DRAFT` status

1814

# from any other status.

1815

# * An insertion order cannot be set to `ENTITY_STATUS_ACTIVE` if its parent

1816

# campaign is not active.

1817

"pacing": { # Settings that control the rate at which a budget is spent. # Required. The budget spending speed setting of the insertion order.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1818

"pacingPeriod": "A String", # Required. The time period in which the pacing budget will be spent.

1819

#

1820

# When automatic budget allocation is enabled at the insertion order via

1821

# auto_budget_allocation, this

1822

# field is output only and defaults to `PACING_PERIOD_FLIGHT`.

1823

"pacingType": "A String", # Required. The type of pacing that defines how the budget amount will be

1824

# spent across the pacing_period.

1825

"dailyMaxImpressions": "A String", # Maximum number of impressions to serve every day.

1826

#

1827

# Applicable when the budget is impression based. Must be greater than 0.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1828

"dailyMaxMicros": "A String", # Maximum currency amount to spend every day in micros of

1829

# advertiser's currency.

1830

#

1831

# Applicable when the budget is currency based. Must be greater than 0.

1832

# For example, for 1.5 standard unit of the currency, set this field to

1833

# 1500000.

1834

#

1835

# The value assigned will be rounded to whole billable units for the

1836

# relevant currency by the following rules: any positive value less than a

1837

# single billable unit will be rounded up to one billable unit and any

1838

# value larger than a single billable unit will be rounded down to the

1839

# nearest billable value. For example, if the currency's billable unit is

1840

# 0.01, and this field is set to 10257770, it will round down to 10250000,

1841

# a value of 10.25. If set to 505, it will round up to 10000, a value of

1842

# 0.01.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1843

},

1844

"performanceGoal": { # Settings that control the performance goal of a campaign or insertion order. # Required. Performance goal of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1845

"performanceGoalAmountMicros": "A String", # The goal amount, in micros of the advertiser's currency.

1846

#

1847

# Applicable when

1848

# performance_goal_type is one of:

1849

#

1850

# * `PERFORMANCE_GOAL_TYPE_CPM`

1851

# * `PERFORMANCE_GOAL_TYPE_CPC`

1852

# * `PERFORMANCE_GOAL_TYPE_CPA`

1853

# * `PERFORMANCE_GOAL_TYPE_CPIAVC`

1854

#

1855

# For example 1500000 represents 1.5 standard units of the currency.

1856

"performanceGoalPercentageMicros": "A String", # The decimal representation of the goal percentage in micros.

1857

#

1858

# Applicable when

1859

# performance_goal_type is one of:

1860

#

1861

# * `PERFORMANCE_GOAL_TYPE_CTR`

1862

# * `PERFORMANCE_GOAL_TYPE_VIEWABILITY`

1863

#

1864

# For example, 70000 represents 7% (decimal 0.07).

1865

"performanceGoalString": "A String", # A key performance indicator (KPI) string, which can be empty.

1866

# Must be UTF-8 encoded with a length of no more than 100 characters.

1867

#

1868

# Applicable when

1869

# performance_goal_type is set to

1870

# `PERFORMANCE_GOAL_TYPE_OTHER`.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1871

"performanceGoalType": "A String", # Required. The type of the performance goal.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1872

},

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1873

"insertionOrderId": "A String", # Output only. The unique ID of the insertion order. Assigned by the system.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1874

"campaignId": "A String", # Required. Immutable. The unique ID of the campaign that the insertion order belongs to.

1875

"name": "A String", # Output only. The resource name of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1876

"integrationDetails": { # Integration details of an entry. # Additional integration details of the insertion order.

1877

"details": "A String", # Additional details of the entry in string format.

1878

#

1879

# Must be UTF-8 encoded with a length of no more than 1000 characters.

1880

"integrationCode": "A String", # An external identifier to be associated with the entry.

1881

# The integration code will show up together with the entry in many

1882

# places in the system, for example, reporting.

1883

#

1884

# Must be UTF-8 encoded with a length of no more than 500 characters.

1885

},

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

1886

}

1887

1888

updateMask: string, Required. The mask to control which fields to update.

1889

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1896

1897

{ # A single insertion order.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

1898

"bidStrategy": { # Settings that control the bid strategy. # Optional. The bidding strategy of the insertion order. By default,

1899

# fixed_bid is set.

1900

# Bid strategy determines the bid price.

1901

"fixedBid": { # A strategy that uses a fixed bidding price. # A strategy that uses a fixed bid price.

1902

"bidAmountMicros": "A String", # The fixed bid amount, in micros of the advertiser's currency.

1903

# For insertion order entity,

1904

# bid_amount_micros should be set as 0.

1905

# For line item entity,

1906

# bid_amount_micros must be greater

1907

# than or equal to billable unit of the given currency and smaller than or

1908

# equal to the upper limit 1000000000.

1909

#

1910

# For example, 1500000 represents 1.5 standard units of the currency.

1911

},

1912

"maximizeSpendAutoBid": { # A strategy that automatically adjusts the bid to optimize a specified # A strategy that automatically adjusts the bid to optimize to your

1913

# performance goal while spending the full budget.

1914

#

1915

# At insertion order level, the

1916

# markup_type of line items

1917

# cannot be set to `PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM`. In addition,

1918

# when

1919

# performance_goal_type

1920

# is one of:

1921

#

1922

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`

1923

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`

1924

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_AV_VIEWED` ,

1925

#

1926

# the line_item_type

1927

# of the insertion order line items must be either:

1928

#

1929

# * `LINE_ITEM_TYPE_DISPLAY_DEFAULT`

1930

# * `LINE_ITEM_TYPE_VIDEO_DEFAULT` ,

1931

#

1932

# and when

1933

# performance_goal_type

1934

# is either:

1935

#

1936

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CIVA`

1937

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_IVO_TEN`

1938

#

1939

# the line_item_type

1940

# of the insertion order line items must be `LINE_ITEM_TYPE_VIDEO_DEFAULT`.

1941

# performance goal while spending the full budget.

1942

"performanceGoalType": "A String", # Required. The type of the performance goal that the bidding strategy

1943

# tries to minimize while spending the full budget.

1944

# `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM` is not supported for

1945

# this strategy.

1946

"maxAverageCpmBidAmountMicros": "A String", # The maximum average CPM that may be bid, in micros of the advertiser's

1947

# currency. Must be greater than or equal to a billable unit of the given

1948

# currency.

1949

#

1950

# For example, 1500000 represents 1.5 standard units of the currency.

1951

},

1952

"performanceGoalAutoBid": { # A strategy that automatically adjusts the bid to meet or beat a specified # A strategy that automatically adjusts the bid to meet or beat a specified

1953

# performance goal. It is to be used only for a line item entity.

1954

# performance goal.

1955

"performanceGoalType": "A String", # Required. The type of the performance goal that the bidding strategy

1956

# will try to meet or beat.

1957

#

1958

# For line item level usage, the value must be one of:

1959

#

1960

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`

1961

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`

1962

# * `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`.

1963

"maxAverageCpmBidAmountMicros": "A String", # The maximum average CPM that may be bid, in micros of the advertiser's

1964

# currency. Must be greater than or equal to a billable unit of the given

1965

# currency. Not applicable when

1966

# performance_goal_type

1967

# is set to `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`.

1968

#

1969

# For example, 1500000 represents 1.5 standard units of the currency.

1970

"performanceGoalAmountMicros": "A String", # Required. The performance goal the bidding strategy will attempt to

1971

# meet or beat, in micros of the advertiser's currency.

1972

# Must be greater than or equal to a billable unit of the given currency and

1973

# smaller or equal to upper bounds. Each

1974

# performance_goal_type

1975

# has its upper bound:

1976

#

1977

# * when

1978

# performance_goal_type

1979

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPA`,

1980

# upper bound is 10000.00 USD.

1981

# * when

1982

# performance_goal_type

1983

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CPC`,

1984

# upper bound is 1000.00 USD.

1985

# * when

1986

# performance_goal_type

1987

# is `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`, upper bound is

# 1000.00 USD.

#

# Example: If set to

# `BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_VIEWABLE_CPM`, the bid price will

1992

# be based on the probability that each available impression will be

1993

# viewable. For example, if viewable CPM target is $2 and an impression is

1994

# 40% likely to be viewable, the bid price will be $0.80 CPM (40% of $2).

1995

#

1996

# For example, 1500000 represents 1.5 standard units of the currency.

1997

},

1998

},

1999

"frequencyCap": { # Settings that control the number of times a user may be shown with the same # Required. The frequency capping setting of the insertion order.

2000

# ad during a given time period.

2001

"unlimited": True or False, # Whether unlimited frequency capping is applied. When this field is set to

2002

# `true`, the remaining frequency cap fields are not applicable.

2003

"maxImpressions": 42, # The maximum number of times a user may be shown with the same ad

2004

# during this period. Must be greater than 0.

2005

#

2006

# Applicable when unlimited is `false`.

2007

"timeUnit": "A String", # The time unit in which the frequency cap will be applied.

2008

#

2009

# Applicable when unlimited is `false`.

2010

"timeUnitCount": 42, # The number of time_unit the frequency cap will

2011

# last.

2012

#

2013

# Applicable when unlimited is `false`.

2014

# The following restrictions apply based on the value of

2015

# time_unit:

2016

#

2017

# * `TIME_UNIT_LIFETIME` - this field is output only and will

2018

# default to 1

2019

# * `TIME_UNIT_MONTHS` - must be between 1 and 2

2020

# * `TIME_UNIT_WEEKS` - must be between 1 and 4

2021

# * `TIME_UNIT_DAYS` - must be between 1 and 6

2022

# * `TIME_UNIT_HOURS` - must be between 1 and 23

2023

# * `TIME_UNIT_MINUTES` - must be between 1 and 59

2024

},

2025

"displayName": "A String", # Required. The display name of the insertion order.

2026

#

2027

# Must be UTF-8 encoded with a maximum size of 240 bytes.

2028

"partnerCosts": [ # The partner costs associated with the insertion order.

2029

#

2030

# If absent or empty in

2031

# CreateInsertionOrder

2032

# method, the newly created insertion order will inherit partner costs from

2033

# the partner settings.

2034

{ # Settings that control a partner cost.

2035

#

2036

# A partner cost is any type of expense involved in running a campaign, other

2037

# than the costs of purchasing impressions (which is called the media cost)

2038

# and using third-party audience segment data (data fee). Some examples of

2039

# partner costs include the fees for using DV360, a third-party ad server,

2040

# or a third-party ad serving verification service.

2041

"feeAmount": "A String", # The CPM fee amount in micros of advertiser's currency.

2042

#

2043

# Applicable when the fee_type is

2044

# `PARTNER_FEE_TYPE_CPM_FEE`. Must be greater than or equal to 0.

2045

#

2046

# For example, for 1.5 standard unit of the advertiser's currency, set

2047

# this field to 1500000.

2048

"costType": "A String", # Required. The type of the partner cost.

2049

"feeType": "A String", # Required. The fee type for this partner cost.

2050

"feePercentageMillis": "A String", # The media fee percentage in millis (1/1000 of a percent).

2051

#

2052

# Applicable when the fee_type is

2053

# `PARTNER_FEE_TYPE_MEDIA_FEE`. Must be greater than or equal to 0.

2054

#

2055

# For example: 100 represents 0.1%.

2056

"invoiceType": "A String", # The invoice type for this partner cost.

2057

#

2058

# * Required when cost_type is one of:

2059

# - `PARTNER_COST_TYPE_ADLOOX`

2060

# - `PARTNER_COST_TYPE_DOUBLE_VERIFY`

2061

# - `PARTNER_COST_TYPE_INTEGRAL_AD_SCIENCE`.

2062

# * Output only for other types.

2063

},

2064

],

2065

"updateTime": "A String", # Output only. The timestamp when the insertion order was last updated.

2066

# Assigned by the system.

2067

"advertiserId": "A String", # Output only. The unique ID of the advertiser the insertion order belongs to.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

2068

"budget": { # Settings that control how insertion order budget is allocated. # Required. The budget allocation settings of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

2069

"budgetSegments": [ # Required. The list of budget segments. Use a budget segment to specify

2070

# a specific budget for a given period of time an insertion order is running.

2071

{ # Settings that control the budget of a single budget segment.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

2072

"budgetAmountMicros": "A String", # Required. The budget amount the insertion order will spend for the given

2073

# date_range.

2074

# The amount is in micros. Must be greater than 0. For example, 500000000

2075

# represents 500 standard units of the currency.

2076

"dateRange": { # A date range. # Required. The start and end date settings of the budget segment. They are resolved

2077

# relative to the parent advertiser's time zone.

2078

#

2079

# * When creating a new budget segment, both `start_date` and `end_date`

2080

# must be in the future.

2081

# * An existing budget segment with a `start_date` in the past has a mutable

2082

# `end_date` but an immutable `start_date`.

2083

# * `end_date` must be the `start_date` or later, both before the year 2037.

2084

"endDate": { # Represents a whole or partial calendar date, e.g. a birthday. The time of day # The upper bound of the date range, inclusive. Must specify a positive value

2085

# for `year`, `month`, and `day`.

2086

# and time zone are either specified elsewhere or are not significant. The date

2087

# is relative to the Proleptic Gregorian Calendar. This can represent:

2088

#

2089

# * A full date, with non-zero year, month and day values

2090

# * A month and day value, with a zero year, e.g. an anniversary

2091

# * A year on its own, with zero month and day values

2092

# * A year and month value, with a zero day, e.g. a credit card expiration date

2093

#

2094

# Related types are google.type.TimeOfDay and `google.protobuf.Timestamp`.

2095

"year": 42, # Year of date. Must be from 1 to 9999, or 0 if specifying a date without

2096

# a year.

2097

"day": 42, # Day of month. Must be from 1 to 31 and valid for the year and month, or 0

2098

# if specifying a year by itself or a year and month where the day is not

2099

# significant.

2100

"month": 42, # Month of year. Must be from 1 to 12, or 0 if specifying a year without a

2101

# month and day.

2102

},

2103

"startDate": { # Represents a whole or partial calendar date, e.g. a birthday. The time of day # The lower bound of the date range, inclusive. Must specify a positive value

2104

# for `year`, `month`, and `day`.

2105

# and time zone are either specified elsewhere or are not significant. The date

2106

# is relative to the Proleptic Gregorian Calendar. This can represent:

2107

#

2108

# * A full date, with non-zero year, month and day values

2109

# * A month and day value, with a zero year, e.g. an anniversary

2110

# * A year on its own, with zero month and day values

2111

# * A year and month value, with a zero day, e.g. a credit card expiration date

2112

#

2113

# Related types are google.type.TimeOfDay and `google.protobuf.Timestamp`.

2114

"year": 42, # Year of date. Must be from 1 to 9999, or 0 if specifying a date without

2115

# a year.

2116

"day": 42, # Day of month. Must be from 1 to 31 and valid for the year and month, or 0

2117

# if specifying a year by itself or a year and month where the day is not

2118

# significant.

2119

"month": 42, # Month of year. Must be from 1 to 12, or 0 if specifying a year without a

# month and day.

},

},

"description": "A String", # The budget segment description. It can be used to enter Purchase Order

2124

# information for each budget segment and have that information printed on

2125

# the invoices.

2126

#

2127

# Must be UTF-8 encoded with a length of no more than 80 characters.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

2128

"campaignBudgetId": "A String", # The ID of the campaign budget linked to this insertion order budget

2129

# segment.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

2130

},

2131

],

2132

"automationType": "A String", # The type of automation used to manage bid and budget for

2133

# the insertion order.

2134

#

2135

# If this field is unspecified in creation, the value defaults to

2136

# `INSERTION_ORDER_AUTOMATION_TYPE_NONE`.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

2137

"budgetUnit": "A String", # Required. Immutable. The budget unit specifies whether the budget is currency based or

2138

# impression based.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

2139

},

2140

"entityStatus": "A String", # Required. Controls whether or not the insertion order can spend its budget

2141

# and bid on inventory.

2142

#

2143

# * For

2144

# CreateInsertionOrder method,

2145

# only `ENTITY_STATUS_DRAFT` is allowed. To activate an insertion order, use

2146

# UpdateInsertionOrder method

2147

# and update the status to `ENTITY_STATUS_ACTIVE` after creation.

2148

# * An insertion order cannot be changed back to `ENTITY_STATUS_DRAFT` status

2149

# from any other status.

2150

# * An insertion order cannot be set to `ENTITY_STATUS_ACTIVE` if its parent

2151

# campaign is not active.

2152

"pacing": { # Settings that control the rate at which a budget is spent. # Required. The budget spending speed setting of the insertion order.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

2153

"pacingPeriod": "A String", # Required. The time period in which the pacing budget will be spent.

2154

#

2155

# When automatic budget allocation is enabled at the insertion order via

2156

# auto_budget_allocation, this

2157

# field is output only and defaults to `PACING_PERIOD_FLIGHT`.

2158

"pacingType": "A String", # Required. The type of pacing that defines how the budget amount will be

2159

# spent across the pacing_period.

2160

"dailyMaxImpressions": "A String", # Maximum number of impressions to serve every day.

2161

#

2162

# Applicable when the budget is impression based. Must be greater than 0.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

2163

"dailyMaxMicros": "A String", # Maximum currency amount to spend every day in micros of

2164

# advertiser's currency.

2165

#

2166

# Applicable when the budget is currency based. Must be greater than 0.

2167

# For example, for 1.5 standard unit of the currency, set this field to

2168

# 1500000.

2169

#

2170

# The value assigned will be rounded to whole billable units for the

2171

# relevant currency by the following rules: any positive value less than a

2172

# single billable unit will be rounded up to one billable unit and any

2173

# value larger than a single billable unit will be rounded down to the

2174

# nearest billable value. For example, if the currency's billable unit is

2175

# 0.01, and this field is set to 10257770, it will round down to 10250000,

2176

# a value of 10.25. If set to 505, it will round up to 10000, a value of

2177

# 0.01.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

2178

},

2179

"performanceGoal": { # Settings that control the performance goal of a campaign or insertion order. # Required. Performance goal of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

2180

"performanceGoalAmountMicros": "A String", # The goal amount, in micros of the advertiser's currency.

2181

#

2182

# Applicable when

2183

# performance_goal_type is one of:

2184

#

2185

# * `PERFORMANCE_GOAL_TYPE_CPM`

2186

# * `PERFORMANCE_GOAL_TYPE_CPC`

2187

# * `PERFORMANCE_GOAL_TYPE_CPA`

2188

# * `PERFORMANCE_GOAL_TYPE_CPIAVC`

2189

#

2190

# For example 1500000 represents 1.5 standard units of the currency.

2191

"performanceGoalPercentageMicros": "A String", # The decimal representation of the goal percentage in micros.

2192

#

2193

# Applicable when

2194

# performance_goal_type is one of:

2195

#

2196

# * `PERFORMANCE_GOAL_TYPE_CTR`

2197

# * `PERFORMANCE_GOAL_TYPE_VIEWABILITY`

2198

#

2199

# For example, 70000 represents 7% (decimal 0.07).

2200

"performanceGoalString": "A String", # A key performance indicator (KPI) string, which can be empty.

2201

# Must be UTF-8 encoded with a length of no more than 100 characters.

2202

#

2203

# Applicable when

2204

# performance_goal_type is set to

2205

# `PERFORMANCE_GOAL_TYPE_OTHER`.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

2206

"performanceGoalType": "A String", # Required. The type of the performance goal.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

2207

},

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

2208

"insertionOrderId": "A String", # Output only. The unique ID of the insertion order. Assigned by the system.

Bu Sun Kim

4ed7d3f

2020-05-27 12:20:54 -0700

[diff] [blame]

2209

"campaignId": "A String", # Required. Immutable. The unique ID of the campaign that the insertion order belongs to.

2210

"name": "A String", # Output only. The resource name of the insertion order.

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

2211

"integrationDetails": { # Integration details of an entry. # Additional integration details of the insertion order.

2212

"details": "A String", # Additional details of the entry in string format.

2213

#

2214

# Must be UTF-8 encoded with a length of no more than 1000 characters.

2215

"integrationCode": "A String", # An external identifier to be associated with the entry.

2216

# The integration code will show up together with the entry in many

2217

# places in the system, for example, reporting.

2218

#

2219

# Must be UTF-8 encoded with a length of no more than 500 characters.

2220

},

Bu Sun Kim

6502091

2020-05-20 12:08:20 -0700

[diff] [blame]

}</pre>

</div>

</body></html>