REST Resource: advertisers.insertionOrders

Zasób: InsertionOrder

pojedyncze zamówienie reklamowe,

Zapis 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)
}
Pola
name

string

Tylko dane wyjściowe. Nazwa zasobu zamówienia reklamowego.
advertiserId

string (int64 format)

Tylko dane wyjściowe. Unikalny identyfikator reklamodawcy, do którego należy zamówienie.
campaignId

string (int64 format)

Wymagany. Niezmienne. Unikalny identyfikator kampanii, do której należy zamówienie reklamowe.
insertionOrderId

string (int64 format)

Tylko dane wyjściowe. Unikalny identyfikator zamówienia reklamowego. Przypisany przez system.
displayName

string

Wymagany. Wyświetlana nazwa zamówienia reklamowego.

Musi być zakodowany w formacie UTF-8 i mieć maksymalny rozmiar 240 bajtów.
insertionOrderType

enum (InsertionOrderType)

Opcjonalnie. Typ zamówienia reklamowego.

Jeśli to pole nie zostanie określone podczas tworzenia, domyślnie przyjmie wartość RTB.
entityStatus

enum (EntityStatus)

Wymagany. Określa, czy zamówienie reklamowe może wykorzystać budżet i ustalać stawki za zasoby reklamowe.

  • W przypadku metody insertionOrders.create dozwolona jest tylko wartość ENTITY_STATUS_DRAFT. Aby aktywować zamówienie reklamowe, użyj metody insertionOrders.patch i po utworzeniu zamówienia zmień jego stan na ENTITY_STATUS_ACTIVE.
  • Nie można zmienić stanu zamówienia reklamowego z innego stanu z powrotem na stan ENTITY_STATUS_DRAFT.
  • Zamówienia reklamowego nie można ustawić na stan ENTITY_STATUS_ACTIVE, jeśli jego kampania nadrzędna nie jest aktywna.
updateTime

string (Timestamp format)

Tylko dane wyjściowe. Sygnatura czasowa ostatniej aktualizacji zlecenia wstawienia. Przypisany przez system.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".
partnerCosts[]

object (PartnerCost)

Opcjonalnie. Koszty partnera powiązane z zamówieniem reklamowym.

Jeśli w metodzie insertionOrders.create nie ma wartości lub jest ona pusta, nowo utworzone zamówienie reklamowe odziedziczy koszty partnera z ustawień partnera.
pacing

object (Pacing)

Wymagany. Ustawienie szybkości wydawania budżetu w zamówieniu reklamowym.

Opcja PACING_TYPE_ASAP usługi pacingType nie jest zgodna z opcją PACING_PERIOD_FLIGHT usługi pacingPeriod.
frequencyCap

object (FrequencyCap)

Wymagany. Ustawienie limitu wyświetleń na użytkownika w zamówieniu reklamowym.
integrationDetails

object (IntegrationDetails)

Opcjonalnie. Dodatkowe szczegóły integracji zamówienia reklamowego.
kpi

object (Kpi)

Wymagany. Kluczowy wskaźnik wydajności (KPI) zamówienia reklamowego.

W interfejsie Display & Video 360 jest to określane jako „Cel”.
budget

object (InsertionOrderBudget)

Wymagany. Ustawienia alokacji budżetu zamówienia reklamowego.
bidStrategy

object (BiddingStrategy)

Opcjonalnie. Strategia ustalania stawek zamówienia reklamowego. Domyślnie ustawiona jest wartość fixedBid.
reservationType

enum (ReservationType)

Tylko dane wyjściowe. Typ rezerwacji zamówienia reklamowego.
optimizationObjective

enum (OptimizationObjective)

Wymagany. Cel optymalizacji zamówienia reklamowego.

InsertionOrderType

Możliwe typy zamówień reklamowych.

Typ zamówienia reklamowego określa, które ustawienia i opcje mają zastosowanie, np. format reklam lub opcje kierowania.

Wartości w polu enum
INSERTION_ORDER_TYPE_UNSPECIFIED Typ zamówienia reklamowego nie jest określony lub jest nieznany.
RTB określanie stawek w czasie rzeczywistym,
OVER_THE_TOP Over-The-Top.

KPI

Ustawienia, które kontrolują kluczowy wskaźnik wydajności (KPI) zamówienia reklamowego.

Zapis JSON 
{
  "kpiType": enum (KpiType),
  "kpiAlgorithmId": string,

  // Union field kpi_value can be only one of the following:
  "kpiAmountMicros": string,
  "kpiPercentageMicros": string,
  "kpiString": string
  // End of list of possible types for union field kpi_value.
}
Pola
kpiType

enum (KpiType)

Wymagany. Typ KPI.
kpiAlgorithmId

string (int64 format)

Opcjonalnie. Identyfikator algorytmu ustalania stawek niestandardowych powiązany z wartością KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST. To pole jest ignorowane, jeśli nie wybrano odpowiedniego wskaźnika KPI.
Pole unii kpi_value. Wymagany. Wartość KPI. Odpowiednie pole odpowiada elementowi kpi_type. kpi_value może mieć tylko jedną z tych wartości:
kpiAmountMicros

string (int64 format)

Kwota celu w milionowych częściach waluty reklamodawcy.

Ma zastosowanie, gdy kpiType ma jedną z tych wartości:

  • KPI_TYPE_CPM
  • KPI_TYPE_CPC
  • KPI_TYPE_CPA
  • KPI_TYPE_CPIAVC
  • KPI_TYPE_VCPM

Przykład: 1500000 oznacza 1,5 jednostki standardowej waluty.
kpiPercentageMicros

string (int64 format)

Dziesiętna reprezentacja docelowego odsetka w mikrojednostkach.

Ma zastosowanie, gdy kpiType ma jedną z tych wartości:

  • 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

Na przykład 70000 oznacza 7% (w postaci dziesiętnej 0,07).
kpiString

string

Ciąg znaków KPI, który może być pusty. Musi być zakodowany w formacie UTF-8 i mieć maksymalnie 100 znaków.

Ma zastosowanie, gdy wartość parametru kpiType to KPI_TYPE_OTHER.

KpiType

Możliwe typy kluczowych wskaźników wydajności (KPI).

Wartości w polu enum
KPI_TYPE_UNSPECIFIED Typ kluczowego wskaźnika wydajności nie jest określony lub jest nieznany w tej wersji.
KPI_TYPE_CPM Kluczowym wskaźnikiem wydajności jest CPM (koszt tysiąca wyświetleń).
KPI_TYPE_CPC KPI to CPC (koszt kliknięcia).
KPI_TYPE_CPA Kluczowym wskaźnikiem wydajności jest CPA (koszt działania).
KPI_TYPE_CTR Kluczowym wskaźnikiem wydajności jest odsetek CTR (współczynnik klikalności).
KPI_TYPE_VIEWABILITY KPI to procent widoczności.
KPI_TYPE_CPIAVC Kluczowym wskaźnikiem wydajności jest CPIAVC (koszt wyświetlenia z włączonym dźwiękiem, widocznego w momencie zakończenia).
KPI_TYPE_CPE Kluczowym wskaźnikiem wydajności jest CPE (koszt zaangażowania).
KPI_TYPE_CPV KPI jest ustawiony na CPV (koszt obejrzenia).
KPI_TYPE_CLICK_CVR Kluczowym wskaźnikiem wydajności jest współczynnik konwersji po kliknięciu (konwersje na kliknięcie) wyrażony w procentach.
KPI_TYPE_IMPRESSION_CVR Kluczowym wskaźnikiem wydajności jest współczynnik konwersji po wyświetleniu (konwersje na wyświetlenie) wyrażony w procentach.
KPI_TYPE_VCPM Kluczowym wskaźnikiem wydajności jest VCPM (koszt tysiąca widocznych wyświetleń).
KPI_TYPE_VTR Kluczowym wskaźnikiem wydajności jest odsetek wyświetleń w YouTube (wyświetlenia w YouTube na wyświetlenie).
KPI_TYPE_AUDIO_COMPLETION_RATE Kluczowym wskaźnikiem wydajności jest odsetek pełnych odtworzeń (pełne odsłuchania reklamy audio na wyświetlenie).
KPI_TYPE_VIDEO_COMPLETION_RATE Kluczowym wskaźnikiem wydajności jest odsetek pełnych obejrzeń filmu (pełne obejrzenia filmu na wyświetlenie).
KPI_TYPE_CPCL KPI jest ustawiony w CPCL (koszt odsłuchania w całości).
KPI_TYPE_CPCV KPI jest ustawiony na CPCV (koszt obejrzenia w całości).
KPI_TYPE_TOS10 Wskaźnik KPI jest określany jako odsetek czasu wyświetlania na ekranie równy 10 s lub dłuższy (odsetek mierzalnych wyświetleń reklam niemożliwych do pominięcia, które były widoczne na ekranie przez co najmniej 10 sekund).
KPI_TYPE_MAXIMIZE_PACING Wskaźnik KPI jest ustawiony tak, aby maksymalizować wpływ marki, nadając priorytet wykorzystaniu całego budżetu.
KPI_TYPE_CUSTOM_IMPRESSION_VALUE_OVER_COST Wskaźnik KPI jest ustawiony jako niestandardowa wartość wyświetlenia podzielona przez koszt.
KPI_TYPE_OTHER KPI to inna wartość.

InsertionOrderBudget

Ustawienia określające sposób przydzielania budżetu zamówienia reklamowego.

Zapis JSON 
{
  "budgetUnit": enum (BudgetUnit),
  "automationType": enum (InsertionOrderAutomationType),
  "budgetSegments": [
    {
      object (InsertionOrderBudgetSegment)
    }
  ]
}
Pola
budgetUnit

enum (BudgetUnit)

Wymagany. Niezmienne. Jednostka budżetu określa, czy budżet jest oparty na walucie, czy na wyświetleniach.
automationType

enum (InsertionOrderAutomationType)

Opcjonalnie. Rodzaj automatyzacji używanej do zarządzania stawką i budżetem zamówienia reklamowego.

Jeśli to pole nie zostanie określone podczas tworzenia, domyślnie przyjmie wartość INSERTION_ORDER_AUTOMATION_TYPE_NONE.
budgetSegments[]

object (InsertionOrderBudgetSegment)

Wymagany. Lista segmentów budżetu. Możesz wykorzystać segment budżetu, aby przeznaczyć określoną kwotę do wydania w wybranym okresie wyświetlania zamówienia reklamowego.

InsertionOrderAutomationType

Możliwe opcje automatyzacji stawek i budżetu zamówienia reklamowego.

Wartości w polu enum
INSERTION_ORDER_AUTOMATION_TYPE_UNSPECIFIED W tej wersji opcja automatyzacji zamówienia reklamowego nie jest określona lub jest nieznana.
INSERTION_ORDER_AUTOMATION_TYPE_BUDGET Automatyczne przydzielanie budżetu. Zezwalaj systemowi na automatyczne przenoszenie budżetu na elementy zamówienia, które są jego właścicielami, aby optymalizować skuteczność określoną przez kpi. Brak automatyzacji w ustawieniach stawek.
INSERTION_ORDER_AUTOMATION_TYPE_NONE Brak automatyzacji stawek lub budżetu na poziomie zamówienia reklamowego. Stawkę i budżet należy skonfigurować ręcznie na poziomie elementu zamówienia.
INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET Zezwalaj systemowi na automatyczne dostosowywanie stawek i przesuwanie budżetu na elementy zamówienia, które są właścicielami, w celu optymalizacji skuteczności określonej przez kpi.

InsertionOrderBudgetSegment

Ustawienia, które kontrolują budżet pojedynczego segmentu budżetu.

Zapis JSON 
{
  "budgetAmountMicros": string,
  "description": string,
  "dateRange": {
    object (DateRange)
  },
  "campaignBudgetId": string
}
Pola
budgetAmountMicros

string (int64 format)

Wymagany. Kwota budżetu, jaką zamówienie reklamowe wyda na podany dateRange. Kwota jest podana w mikro. Musi być większy niż 0. Na przykład 500000000 oznacza 500 jednostek standardowych waluty.
description

string

Opcjonalnie. Opis segmentu budżetu. Możesz go używać do wprowadzania informacji o zamówieniach w przypadku każdego segmentu budżetu, a następnie drukować te informacje na fakturach.

Musi być zakodowany w formacie UTF-8.
dateRange

object (DateRange)

Wymagany. Ustawienia daty rozpoczęcia i zakończenia segmentu budżetu. Są one rozwiązywane w odniesieniu do strefy czasowej reklamodawcy nadrzędnego.

  • Podczas tworzenia nowego segmentu budżetu zarówno startDate, jak i endDate muszą być datami w przyszłości.
  • Istniejący segment budżetu z wartością startDate w przeszłości ma modyfikowalną wartość endDate, ale niemodyfikowalną wartość startDate.
  • W polu endDate musi występować data startDate lub późniejsza, ale przed rokiem 2037.
campaignBudgetId

string (int64 format)

Opcjonalnie. budgetId budżetu kampanii, którego częścią jest ten segment budżetu zamówienia reklamowego.

OptimizationObjective

Możliwe typy celów optymalizacji.

Wartości w polu enum
OPTIMIZATION_OBJECTIVE_UNSPECIFIED Wartość typu nie jest określona lub jest nieznana w tej wersji.
CONVERSION Nadawanie priorytetu wyświetleniom, które zwiększają sprzedaż i liczbę konwersji.
CLICK Nadawanie priorytetu wyświetleniom, które zwiększają ruch w witrynie, aplikacji lub sklepie z aplikacjami.
BRAND_AWARENESS Nadawanie priorytetu wyświetleniom o określonej jakości.
CUSTOM Cel jest określany przez przypisany algorytm ustalania stawek niestandardowych.
NO_OBJECTIVE Cel nie jest zdefiniowany. Możesz używać dowolnego KPI lub strategii ustalania stawek.

Metody

create

 Tworzy nowe zamówienie reklamowe.

delete

 Usuwa zamówienie reklamowe.

get

 Pobiera zamówienie reklamowe.

list

 Wyświetla listę zamówień reklamowych w ramach reklamodawcy.

listAssignedTargetingOptions

 Wyświetla przypisane opcje kierowania zamówienia reklamowego w różnych typach kierowania.

patch

 Aktualizuje istniejące zamówienie reklamowe.