REST Resource: advertisers.insertionOrders

Tài nguyên: InsertionOrder

Một đơn đặt hàng quảng cáo.

Biểu diễn dưới dạng JSON 
{
  "name": string,
  "advertiserId": string,
  "campaignId": string,
  "insertionOrderId": string,
  "displayName": string,
  "insertionOrderType": enum (InsertionOrderType),
  "entityStatus": enum (EntityStatus),
  "updateTime": string,
  "partnerCosts": [
    {
      object (PartnerCost)
    }
  ],
  "pacing": {
    object (Pacing)
  },
  "frequencyCap": {
    object (FrequencyCap)
  },
  "integrationDetails": {
    object (IntegrationDetails)
  },
  "kpi": {
    object (Kpi)
  },
  "budget": {
    object (InsertionOrderBudget)
  },
  "bidStrategy": {
    object (BiddingStrategy)
  },
  "reservationType": enum (ReservationType),
  "optimizationObjective": enum (OptimizationObjective)
}
Trường
name

string

Chỉ có đầu ra. Tên tài nguyên của đơn đặt hàng quảng cáo.
advertiserId

string (int64 format)

Chỉ có đầu ra. Mã nhận dạng duy nhất của nhà quảng cáo sở hữu đơn đặt hàng quảng cáo.
campaignId

string (int64 format)

Bắt buộc. Không thể thay đổi. Mã nhận dạng duy nhất của chiến dịch chứa đơn đặt hàng quảng cáo.
insertionOrderId

string (int64 format)

Chỉ có đầu ra. Mã nhận dạng duy nhất của đơn đặt hàng quảng cáo. Do hệ thống chỉ định.
displayName

string

Bắt buộc. Tên hiển thị của đơn đặt hàng quảng cáo.

Phải được mã hoá theo UTF-8 với kích thước tối đa là 240 byte.
insertionOrderType

enum (InsertionOrderType)

Không bắt buộc. Loại đơn đặt hàng quảng cáo.

Nếu bạn không chỉ định trường này khi tạo, thì giá trị sẽ được đặt mặc định là RTB.
entityStatus

enum (EntityStatus)

Bắt buộc. Kiểm soát việc đơn đặt hàng quảng cáo có thể chi tiêu ngân sách và đặt giá thầu cho khoảng không quảng cáo hay không.

  • Đối với phương thức insertionOrders.create, chỉ cho phép ENTITY_STATUS_DRAFT. Để kích hoạt đơn đặt hàng quảng cáo, hãy sử dụng phương thức insertionOrders.patch và cập nhật trạng thái thành ENTITY_STATUS_ACTIVE sau khi tạo.
  • Bạn không thể thay đổi trạng thái của đơn đặt hàng quảng cáo từ bất kỳ trạng thái nào khác về trạng thái ENTITY_STATUS_DRAFT.
  • Bạn không thể đặt đơn đặt hàng quảng cáo thành ENTITY_STATUS_ACTIVE nếu chiến dịch mẹ của đơn đặt hàng quảng cáo đó không hoạt động.
updateTime

string (Timestamp format)

Chỉ có đầu ra. Dấu thời gian khi đơn đặt hàng quảng cáo được cập nhật lần gần đây nhất. Do hệ thống chỉ định.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
partnerCosts[]

object (PartnerCost)

Không bắt buộc. Chi phí đối tác liên quan đến đơn đặt hàng quảng cáo.

Nếu không có hoặc để trống trong phương thức insertionOrders.create, thì đơn đặt hàng quảng cáo mới tạo sẽ kế thừa chi phí của đối tác từ chế độ cài đặt đối tác.
pacing

object (Pacing)

Bắt buộc. Chế độ cài đặt tốc độ chi tiêu ngân sách của đơn đặt hàng quảng cáo.

pacingType PACING_TYPE_ASAP không tương thích với pacingPeriod PACING_PERIOD_FLIGHT.
frequencyCap

object (FrequencyCap)

Bắt buộc. Chế độ cài đặt giới hạn tần suất của đơn đặt hàng quảng cáo.
integrationDetails

object (IntegrationDetails)

Không bắt buộc. Thông tin chi tiết khác về việc tích hợp của đơn đặt hàng quảng cáo.
kpi

object (Kpi)

Bắt buộc. Chỉ báo hiệu suất chính (KPI) của đơn đặt hàng quảng cáo.

Mục tiêu này được gọi là "Mục tiêu" trong giao diện Display & Video 360.
budget

object (InsertionOrderBudget)

Bắt buộc. Chế độ cài đặt thông tin phân bổ ngân sách của đơn đặt hàng quảng cáo.
bidStrategy

object (BiddingStrategy)

Không bắt buộc. Chiến lược đặt giá thầu của đơn đặt hàng quảng cáo. Theo mặc định, fixedBid được đặt.

Nếu trường budget automationType được đặt thành INSERTION_ORDER_AUTOMATION_TYPE_BUDGET hoặc INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET, thì đơn đặt hàng quảng cáo sẽ áp dụng chiến lược đặt giá thầu này cho các mục hàng của đơn đặt hàng quảng cáo đó. Nếu chiến lược đặt giá thầu được áp dụng không tương thích với chế độ cài đặt enableOptimizedTargeting của một mục hàng, thì chế độ cài đặt tối ưu hoá tiêu chí nhắm mục tiêu sẽ được cập nhật.
reservationType

enum (ReservationType)

Chỉ có đầu ra. Loại đặt trước của đơn đặt hàng quảng cáo.
optimizationObjective

enum (OptimizationObjective)

Bắt buộc. Mục tiêu tối ưu hoá của đơn đặt hàng quảng cáo.

InsertionOrderType

Các loại Đơn đặt hàng quảng cáo có thể có.

Loại Đơn đặt hàng quảng cáo xác định chế độ cài đặt và lựa chọn nào có thể áp dụng, chẳng hạn như định dạng quảng cáo hoặc lựa chọn nhắm mục tiêu.

Enum
INSERTION_ORDER_TYPE_UNSPECIFIED Loại đơn đặt hàng quảng cáo không được chỉ định hoặc không xác định.
RTB Đặt giá thầu theo thời gian thực.
OVER_THE_TOP Quá đà.
OUT_OF_HOME Quảng cáo ngoài trời.

Kpi

Chế độ cài đặt kiểm soát chỉ báo hiệu suất chính (KPI) của một đơn đặt hàng quảng cáo.

Biểu diễn dưới dạng JSON 
{
  "kpiType": enum (KpiType),
  "kpiAlgorithmId": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "kpiAmountMicros": string,
  "kpiPercentageMicros": string,
  "kpiString": string
  // End of mutually exclusive fields.
}
Trường
kpiType

enum (KpiType)

Bắt buộc. Loại KPI.
kpiAlgorithmId

string (int64 format)

Không bắt buộc. Mã nhận dạng thuật toán đặt giá thầu tùy chỉnh liên kết với KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST. Trường này sẽ bị bỏ qua nếu bạn không chọn KPI thích hợp.
Bắt buộc. Giá trị của KPI. Trường liên quan tương ứng với kpi_type. Sau đây là danh sách các trường loại trừ lẫn nhau. Tối đa một trong các trường sẽ được đặt trong phản hồi:
kpiAmountMicros

string (int64 format)

Số tiền mục tiêu, tính bằng đơn vị micro theo đơn vị tiền tệ của nhà quảng cáo.

Áp dụng khi kpiType là một trong những giá trị sau:

  • KPI_TYPE_CPM
  • KPI_TYPE_CPC
  • KPI_TYPE_CPA
  • KPI_TYPE_CPIAVC
  • KPI_TYPE_VCPM

Ví dụ: 1500000 tương ứng với 1,5 đơn vị tiền tệ tiêu chuẩn.
kpiPercentageMicros

string (int64 format)

Biểu thị thập phân của tỷ lệ phần trăm mục tiêu theo phần triệu.

Áp dụng khi kpiType là một trong những giá trị sau:

  • KPI_TYPE_CTR
  • KPI_TYPE_VIEWABILITY
  • KPI_TYPE_CLICK_CVR
  • KPI_TYPE_IMPRESSION_CVR
  • KPI_TYPE_VTR
  • KPI_TYPE_AUDIO_COMPLETION_RATE
  • KPI_TYPE_VIDEO_COMPLETION_RATE

Ví dụ: 70000 đại diện cho 7% (số thập phân 0,07).
kpiString

string

Một chuỗi KPI, có thể để trống. Phải được mã hoá UTF-8 với độ dài không quá 100 ký tự.

Áp dụng khi kpiType là KPI_TYPE_OTHER.
Kết thúc các trường loại trừ lẫn nhau.

KpiType

Các loại chỉ báo hiệu suất chính (KPI) có thể có.

Enum
KPI_TYPE_UNSPECIFIED Loại KPI không được chỉ định hoặc không xác định được trong phiên bản này.
KPI_TYPE_CPM KPI là CPM (chi phí mỗi nghìn lượt hiển thị).
KPI_TYPE_CPC KPI là CPC (chi phí mỗi lượt nhấp).
KPI_TYPE_CPA KPI là CPA (chi phí mỗi hành động).
KPI_TYPE_CTR KPI là tỷ lệ phần trăm CTR (tỷ lệ nhấp).
KPI_TYPE_VIEWABILITY KPI là Tỷ lệ phần trăm khả năng xem.
KPI_TYPE_CPIAVC KPI là CPIAVC (chi phí mỗi lượt hiển thị có thể nghe và xem khi hoàn thành).
KPI_TYPE_CPE KPI là CPE (chi phí mỗi lượt tương tác).
KPI_TYPE_CPV KPI được đặt theo CPV (chi phí mỗi lượt xem).
KPI_TYPE_CLICK_CVR KPI là tỷ lệ chuyển đổi từ lượt nhấp (số lượt chuyển đổi trên mỗi lượt nhấp) tính theo phần trăm.
KPI_TYPE_IMPRESSION_CVR KPI là tỷ lệ chuyển đổi từ lượt hiển thị (số lượt chuyển đổi trên mỗi lượt hiển thị) tính theo tỷ lệ phần trăm.
KPI_TYPE_VCPM KPI là VCPM (chi phí mỗi nghìn lượt hiển thị có thể xem).
KPI_TYPE_VTR KPI là tỷ lệ xem trên YouTube (số lượt xem trên YouTube trên mỗi lượt hiển thị).
KPI_TYPE_AUDIO_COMPLETION_RATE KPI là tỷ lệ hoàn thành âm thanh (số lượt nghe hết âm thanh trên mỗi lượt hiển thị).
KPI_TYPE_VIDEO_COMPLETION_RATE KPI là tỷ lệ xem hết video (số lượt xem hết video trên mỗi lượt hiển thị).
KPI_TYPE_CPCL KPI được đặt theo CPCL (chi phí cho mỗi lượt nghe hết nội dung âm thanh).
KPI_TYPE_CPCV KPI được đặt theo CPCV (chi phí cho mỗi lượt xem hết video).
KPI_TYPE_TOS10 KPI được đặt theo tỷ lệ thời gian trên màn hình từ 10 giây trở lên (Tỷ lệ phần trăm số lượt hiển thị có thể đo lường, không thể bỏ qua xuất hiện trên màn hình trong ít nhất 10 giây).
KPI_TYPE_MAXIMIZE_PACING KPI được đặt để tối đa hoá mức tác động của thương hiệu, đồng thời ưu tiên chi tiêu toàn bộ ngân sách.
KPI_TYPE_CUSTOM_IMPRESSION_VALUE_OVER_COST KPI được đặt bằng giá trị lượt hiển thị tuỳ chỉnh chia cho chi phí.
KPI_TYPE_OTHER KPI là một giá trị khác.

InsertionOrderBudget

Chế độ cài đặt kiểm soát cách phân bổ ngân sách của đơn đặt hàng quảng cáo.

Biểu diễn dưới dạng JSON 
{
  "budgetUnit": enum (BudgetUnit),
  "automationType": enum (InsertionOrderAutomationType),
  "budgetSegments": [
    {
      object (InsertionOrderBudgetSegment)
    }
  ]
}
Trường
budgetUnit

enum (BudgetUnit)

Bắt buộc. Không thể thay đổi. Đơn vị ngân sách chỉ định ngân sách dựa trên đơn vị tiền tệ hay dựa trên lượt hiển thị.
automationType

enum (InsertionOrderAutomationType)

Không bắt buộc. Loại tính năng tự động hoá dùng để quản lý giá thầu và ngân sách cho đơn đặt hàng quảng cáo.

Nếu bạn không chỉ định trường này khi tạo, thì giá trị sẽ được đặt mặc định là INSERTION_ORDER_AUTOMATION_TYPE_NONE.
budgetSegments[]

object (InsertionOrderBudgetSegment)

Bắt buộc. Danh sách phân đoạn ngân sách. Sử dụng phân đoạn ngân sách để chỉ định một ngân sách cụ thể cho một khoảng thời gian nhất định mà đơn đặt hàng quảng cáo đang chạy.

InsertionOrderAutomationType

Các lựa chọn có thể dùng để tự động hoá giá thầu và ngân sách của đơn đặt hàng quảng cáo.

Enum
INSERTION_ORDER_AUTOMATION_TYPE_UNSPECIFIED Lựa chọn tự động hoá đơn đặt hàng quảng cáo không được chỉ định hoặc không xác định trong phiên bản này.
INSERTION_ORDER_AUTOMATION_TYPE_BUDGET Tự động phân bổ ngân sách. Cho phép hệ thống tự động chuyển ngân sách sang các mục hàng sở hữu để tối ưu hoá hiệu suất do kpi xác định. Không có chế độ tự động hoá cho chế độ cài đặt giá thầu.
INSERTION_ORDER_AUTOMATION_TYPE_NONE Không tự động hoá giá thầu hoặc ngân sách ở cấp đơn đặt hàng quảng cáo. Bạn phải định cấu hình giá thầu và ngân sách theo cách thủ công ở cấp mục hàng.
INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET Cho phép hệ thống tự động điều chỉnh giá thầu và chuyển ngân sách sang các mục hàng sở hữu để tối ưu hoá hiệu suất do bidStrategy xác định.

InsertionOrderBudgetSegment

Chế độ cài đặt kiểm soát ngân sách của một phân đoạn ngân sách.

Biểu diễn dưới dạng JSON 
{
  "budgetAmountMicros": string,
  "description": string,
  "dateRange": {
    object (DateRange)
  },
  "campaignBudgetId": string
}
Trường
budgetAmountMicros

string (int64 format)

Bắt buộc. Số tiền ngân sách mà đơn đặt hàng quảng cáo sẽ chi tiêu cho dateRange nhất định. Số tiền được tính theo đơn vị micro. Phải lớn hơn 0. Ví dụ: 500000000 đại diện cho 500 đơn vị tiền tệ tiêu chuẩn.
description

string

Không bắt buộc. Nội dung mô tả phân đoạn ngân sách. Bạn có thể sử dụng trường này để nhập thông tin Đơn đặt hàng cho từng phân khúc ngân sách và in thông tin đó trên hoá đơn.

Phải được mã hoá theo UTF-8.
dateRange

object (DateRange)

Bắt buộc. Chế độ cài đặt ngày bắt đầu và ngày kết thúc của phân đoạn ngân sách. Các giá trị này được phân giải theo múi giờ của nhà quảng cáo mẹ.

  • Khi tạo một phân đoạn ngân sách mới, cả startDate và endDate đều phải là thời gian trong tương lai.
  • Một phân đoạn ngân sách hiện có với startDate trong quá khứ có endDate có thể thay đổi nhưng startDate không thể thay đổi.
  • endDate phải là startDate trở lên, cả hai đều trước năm 2037.
campaignBudgetId

string (int64 format)

Không bắt buộc. budgetId của ngân sách chiến dịch mà phân khúc ngân sách của đơn đặt hàng quảng cáo này thuộc về.

OptimizationObjective

Các loại mục tiêu tối ưu hoá có thể có.

Enum
OPTIMIZATION_OBJECTIVE_UNSPECIFIED Giá trị loại không được chỉ định hoặc không xác định trong phiên bản này.
CONVERSION Ưu tiên những lượt hiển thị giúp tăng doanh số và lượt chuyển đổi.
CLICK Ưu tiên những lượt hiển thị giúp tăng lưu lượng truy cập vào trang web, ứng dụng, cửa hàng ứng dụng.
BRAND_AWARENESS Ưu tiên lượt hiển thị có chất lượng cụ thể.
CUSTOM Mục tiêu được xác định theo thuật toán đặt giá thầu tuỳ chỉnh được chỉ định.
NO_OBJECTIVE Mục tiêu chưa được xác định. Bạn có thể sử dụng bất kỳ KPI hoặc chiến lược đặt giá thầu nào.

Phương thức

create

 Tạo đơn đặt hàng quảng cáo mới.

delete

 Xoá đơn đặt hàng quảng cáo.

get

 Lấy một đơn đặt hàng quảng cáo.

list

 Liệt kê các đơn đặt hàng quảng cáo trong một nhà quảng cáo.

patch

 Cập nhật đơn đặt hàng quảng cáo hiện có.