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)

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

string (int64 format)

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

string

Wymagane. 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 wartość RTB.
entityStatus

enum (EntityStatus)

Wymagane. Określa, czy zamówienie reklamowe może wykorzystać budżet i określać 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 ENTITY_STATUS_ACTIVE, jeśli jego kampania nadrzędna nie jest aktywna.
updateTime

string (Timestamp format)

Tylko dane wyjściowe. Sygnatura czasowa ostatniej aktualizacji zamówienia. 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 na zamieszczanie reklam.

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

object (Pacing)

Wymagane. 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)

Wymagane. Ustawienie ograniczenia liczby wyświetleń w zamówieniu reklamowym.
integrationDetails

object (IntegrationDetails)

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

object (Kpi)

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

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

object (InsertionOrderBudget)

Wymagane. Ustawienia przydzielania budżetu w zamówieniu reklamowym.
bidStrategy

object (BiddingStrategy)

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

Jeśli w polu budget automationType ustawiono wartość INSERTION_ORDER_AUTOMATION_TYPE_BUDGET lub INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET, zamówienie reklamowe narzuci tę strategię ustalania stawek na swoje elementy zamówienia. Jeśli narzucona strategia ustalania stawek jest niezgodna z ustawieniem enableOptimizedTargeting elementu zamówienia, ustawienie kierowania zoptymalizowanego zostanie zaktualizowane.
reservationType

enum (ReservationType)

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

enum (OptimizationObjective)

Wymagane. Cel optymalizacji zamówienia reklamowego.

InsertionOrderType

Możliwe typy zamówienia reklamowego.

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,

  // 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.
}
Pola
kpiType

enum (KpiType)

Wymagane. 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.
Wymagane. Wartość KPI. Odpowiednie pole odpowiada wartości kpi_type. Poniżej znajduje się lista pól, które się wzajemnie wykluczają. W odpowiedzi zostanie ustawione co najwyżej jedno z tych pól:
kpiAmountMicros

string (int64 format)

Kwota docelowa w mikro jednostkach waluty reklamodawcy.

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

  • KPI_TYPE_CPM
  • KPI_TYPE_CPC
  • KPI_TYPE_CPA
  • KPI_TYPE_CPIAVC
  • KPI_TYPE_VCPM

Na przykład 1500000 oznacza 1,5 jednostki standardowej waluty.
kpiPercentageMicros

string (int64 format)

Dziesiętna reprezentacja docelowego odsetka w mikrojednostkach.

Dotyczy, 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ć długość nie większą niż 100 znaków.

Obowiązuje, gdy wartość właściwości kpiType to KPI_TYPE_OTHER.
Koniec pól wykluczających się nawzajem.

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 Kluczowym wskaźnikiem wydajności jest 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 pełnego wyświetlenia reklamy wideo z dźwiękiem).
KPI_TYPE_CPE KPI to CPE (koszt zaangażowania).
KPI_TYPE_CPV KPI jest ustawiony na CPV (koszt obejrzenia).
KPI_TYPE_CLICK_CVR Kluczowym wskaźnikiem wydajności jest procentowy współczynnik konwersji po kliknięciu (konwersje na kliknięcie).
KPI_TYPE_IMPRESSION_CVR Kluczowym wskaźnikiem wydajności jest współczynnik konwersji wyświetleń (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 współczynnika pełnych odtworzeń (pełne odtworzenia reklamy audio na wyświetlenie).
KPI_TYPE_VIDEO_COMPLETION_RATE Kluczowym wskaźnikiem wydajności jest współczynnik pełnych obejrzeń filmu (odsetek pełnych obejrzeń filmu na wyświetlenie).
KPI_TYPE_CPCL KPI jest ustawiony w CPCL (koszt pełnego odsłuchania reklamy audio).
KPI_TYPE_CPCV KPI jest ustawiony na CPCV (koszt pełnego obejrzenia filmu).
KPI_TYPE_TOS10 Wskaźnik KPI jest ustawiony jako odsetek czasu wyświetlania na ekranie przez co najmniej 10 sekund (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 kampanii na markę przy priorytetowym traktowaniu wykorzystania całego budżetu.
KPI_TYPE_CUSTOM_IMPRESSION_VALUE_OVER_COST Wskaźnik KPI jest ustawiany jako niestandardowa wartość wyświetleń podzielona przez koszt.
KPI_TYPE_OTHER KPI to inna wartość.

InsertionOrderBudget

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

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

enum (BudgetUnit)

Wymagane. 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 jest określone podczas tworzenia, domyślnie przyjmuje wartość INSERTION_ORDER_AUTOMATION_TYPE_NONE.
budgetSegments[]

object (InsertionOrderBudgetSegment)

Wymagane. 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 Opcja automatyzacji zamówienia reklamowego nie jest określona lub jest nieznana w tej wersji.
INSERTION_ORDER_AUTOMATION_TYPE_BUDGET Automatyczne przydzielanie budżetu. Zezwól 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 ustawień stawek.
INSERTION_ORDER_AUTOMATION_TYPE_NONE Brak automatyzacji stawek i 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 bidStrategy.

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)

Wymagane. Kwota budżetu, jaką zamówienie reklamowe wyda w przypadku danego dateRange. Kwota jest podana w wartości 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ówieniu w przypadku każdego segmentu budżetu i wyświetlania tych informacji na fakturach.

Musi być zakodowany w formacie UTF-8.
dateRange

object (DateRange)

Wymagane. 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ą przypadać 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.
  • endDate musi przypadać w dniu startDate lub później, ale przed rokiem 2037.
campaignBudgetId

string (int64 format)

Opcjonalnie: budgetId budżetu kampanii, z którego pochodzi 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 przypadku reklamodawcy.

patch

 Aktualizuje istniejące zamówienie reklamowe.