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 na wstawianie reklam.

campaignId

string (int64 format)

Wymagany. Niezmienna. 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 jest określone podczas tworzenia, domyślnie przyjmuje się 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 żadnego innego stanu na ENTITY_STATUS_DRAFT.
  • Zamówienia reklamowego nie można ustawić jako ENTITY_STATUS_ACTIVE, jeśli jego kampania nadrzędna jest nieaktywna.
updateTime

string (Timestamp format)

Tylko dane wyjściowe. Sygnatura czasowa ostatniej aktualizacji zamówienia na wstawione treści. Przypisany przez system.

Używa standardu RFC 3339, w którym wygenerowany wynik jest zawsze znormalizowany według normy Z i zawiera 0, 3, 6 lub 9 cyfr ułamkowych. 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 jego ustawień.

pacing

object (Pacing)

Wymagany. Ustawienie tempa 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 ona określana 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)

Opcjonalnie: Cel optymalizacji zamówienia reklamowego.

InsertionOrderType

Możliwe typy zamówienia reklamowego.

Typ zamówienia reklamowego określa, które ustawienia i opcje są dostępne, np. format reklamy lub opcje kierowania.

Wartości w polu enum
INSERTION_ORDER_TYPE_UNSPECIFIED Typ zamówienia reklamowego nie został 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 KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST. To pole jest ignorowane, jeśli nie wybierzesz odpowiedniego wskaźnika KPI.

Pole unii kpi_value. Wymagany. Wartość KPI. Odpowiednie pole odpowiada kpi_type. kpi_value może być tylko jednym z tych elementów:
kpiAmountMicros

string (int64 format)

Wartość celu w milionowych częściach waluty reklamodawcy.

Dotyczy, gdy kpiType jest jedną z tych wartości:

  • KPI_TYPE_CPM
  • KPI_TYPE_CPC
  • KPI_TYPE_CPA
  • KPI_TYPE_CPIAVC
  • KPI_TYPE_VCPM

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

kpiPercentageMicros

string (int64 format)

Ułamek dziesiętny odsetka celu w mikro.

Dotyczy, gdy kpiType jest 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

Przykład: 70000 oznacza 7% (cyfra dziesiętna 0,07).

kpiString

string

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

Dotyczy to sytuacji, gdy kpiType ma wartość KPI_TYPE_OTHER.

KpiType

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

Wartości w polu enum
KPI_TYPE_UNSPECIFIED W tej wersji nie podano typu KPI lub jest on nieznany.
KPI_TYPE_CPM Wskaźnik KPI to CPM (koszt tysiąca wyświetleń).
KPI_TYPE_CPC Wskaźnik KPI to CPC (koszt kliknięcia).
KPI_TYPE_CPA Wskaźnik KPI to CPA (koszt działania).
KPI_TYPE_CTR Wskaźnik KPI to współczynnik klikalności (CTR).
KPI_TYPE_VIEWABILITY KPI to Współczynnik widoczności.
KPI_TYPE_CPIAVC Wskaźnik KPI to CPIAVC (koszt wyświetlenia z włączonym dźwiękiem, widocznego w momencie zakończenia).
KPI_TYPE_CPE Wskaźnikiem KPI jest CPE (koszt zaangażowania).
KPI_TYPE_CPV Wskaźnik KPI jest ustawiany w sekcji CPV (koszt obejrzenia).
KPI_TYPE_CLICK_CVR Wskaźnik KPI to współczynnik konwersji po kliknięciu (konwersje na kliknięcie) wyrażony w procentach.
KPI_TYPE_IMPRESSION_CVR Wskaźnik KPI to współczynnik konwersji po wyświetleniu (konwersje na wyświetlenie) wyrażony w procentach.
KPI_TYPE_VCPM Wskaźnikiem KPI jest VCPM (koszt tysiąca widocznych wyświetleń).
KPI_TYPE_VTR Wskaźnik KPI to odsetek wyświetleń w YouTube (wyświetlenia w YouTube na wyświetlenie).
KPI_TYPE_AUDIO_COMPLETION_RATE Wskaźnik KPI to odsetek odtworzeń w całości (pełne odsłuchania reklamy audio na wyświetlenie).
KPI_TYPE_VIDEO_COMPLETION_RATE Wskaźnik KPI to współczynnik pełnych obejrzeń (pełne obejrzenia na wyświetlenie).
KPI_TYPE_CPCL Wskaźnik KPI jest ustawiany w CPCL (koszt odsłuchania w całości).
KPI_TYPE_CPCV Wskaźnik KPI jest ustawiany w CPCV (koszt obejrzenia w całości).
KPI_TYPE_TOS10 Wskaźnik ten jest ustawiany w formie współczynnika czasu wyświetlania na ekranie równego 10 s lub dłuższemu (odsetek mierzalnych, niemożliwych do pominięcia wyświetleń, które były widoczne na ekranie przez co najmniej 10 sekund).
KPI_TYPE_MAXIMIZE_PACING 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 ustawiany na podstawie niestandardowej wartości wyświetlenia podzielonej przez koszt.
KPI_TYPE_OTHER Wskaźnik KPI ma inną wartość.

InsertionOrderBudget

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

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

enum (BudgetUnit)

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

automationType

enum (InsertionOrderAutomationType)

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

Jeśli to pole nie jest określone podczas tworzenia, domyślnie przyjmuje się wartość INSERTION_ORDER_AUTOMATION_TYPE_NONE.

budgetSegments[]

object (InsertionOrderBudgetSegment)

Wymagany. Lista segmentów budżetu. Segment budżetu umożliwia określenie konkretnego budżetu na dany okres wyświetlania zamówienia reklamowego.

InsertionOrderAutomationType

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

Wartości w polu enum
INSERTION_ORDER_AUTOMATION_TYPE_UNSPECIFIED Opcja automatyzacji zamówienia reklamowego nie jest określona lub jest nieznana w tej wersji.
INSERTION_ORDER_AUTOMATION_TYPE_BUDGET Automatyczne przydzielanie budżetu. Zezwalaj systemowi na automatyczne przenoszenie budżetu do elementów zamówienia, które je obejmują, aby optymalizować skuteczność zdefiniowaną przez kpi. Brak automatyzacji ustawień stawek.
INSERTION_ORDER_AUTOMATION_TYPE_NONE Brak automatyzacji stawek ani budżetu na poziomie zamówienia reklamowego. Stawka i budżet muszą być skonfigurowane ręcznie na poziomie elementu zamówienia.
INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET Zezwalaj systemowi na automatyczne dostosowywanie stawek i przesuwanie budżetu do elementów zamówienia, które je obejmują, aby optymalizować skuteczność określoną 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 daną dateRange. Kwota jest wyrażona w mikro. Musi być większy niż 0. Na przykład 500000000 reprezentuje 500 standardowych jednostek waluty.

description

string

Opcjonalnie: Opis segmentu budżetu. Możesz go używać do wpisywania informacji o zamówieniu dla każdego segmentu budżetu, które będą drukowane 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 zależności od strefy czasowej reklamodawcy nadrzędnego.

  • Podczas tworzenia nowego segmentu budżetu zarówno startDate, jak i endDate muszą być w przyszłości.
  • Istniejący segment budżetu z wartością startDate w przeszłości ma zmienną wartość endDate, ale niezmienną wartość startDate.
  • Wartość endDate musi być równa startDate lub większa, ale nie może być większa niż 2037.
campaignBudgetId

string (int64 format)

Opcjonalnie: budgetId budżetu kampanii, którego jest częścią 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 została 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 nadawać priorytet wyświetleniom o określonej jakości;
CUSTOM Cel jest definiowany przez przypisany algorytm ustalania stawek niestandardowych.
NO_OBJECTIVE Niezdefiniowany cel. Możesz użyć dowolnego KPI lub dowolnej strategii ustalania stawek.

Metody

create

Tworzy nowe zamówienie reklamowe.

delete

Usuwa zamówienie reklamowe.

get

Pobiera zamówienie reklamowe.

list

Wyświetla zamówienia reklamowe w reklamodawcy.

listAssignedTargetingOptions

Wyświetla przypisane opcje kierowania zamówienia reklamowego według typów kierowania.

patch

Aktualizuje dotychczasowe zamówienie reklamowe.