REST Resource: advertisers.insertionOrders

Risorsa: InsertionOrder

Un singolo ordine di inserzione.

Rappresentazione 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)
}
Campi
name

string

Solo output. Il nome della risorsa dell'ordine di inserzione.
advertiserId

string (int64 format)

Solo output. L'ID univoco dell'inserzionista a cui appartiene l'ordine di inserzione.
campaignId

string (int64 format)

Obbligatorio. Immutabile. L'ID univoco della campagna a cui appartiene l'ordine di inserzione.
insertionOrderId

string (int64 format)

Solo output. L'ID univoco dell'ordine di inserzione. Assegnato dal sistema.
displayName

string

Obbligatorio. Il nome visualizzato dell'ordine di inserzione.

Deve essere codificata in UTF-8 con una dimensione massima di 240 byte.
insertionOrderType

enum (InsertionOrderType)

Facoltativo. Il tipo di ordine di inserzione.

Se questo campo non è specificato al momento della creazione, il valore predefinito è RTB.
entityStatus

enum (EntityStatus)

Obbligatorio. Controlla se l'ordine di inserzione può spendere il budget e fare offerte per l'inventario.

  • Per il metodo insertionOrders.create, è consentito solo ENTITY_STATUS_DRAFT. Per attivare un ordine di inserzione, utilizza il metodo insertionOrders.patch e aggiorna lo stato a ENTITY_STATUS_ACTIVE dopo la creazione.
  • Un ordine di inserzione non può essere riportato allo stato ENTITY_STATUS_DRAFT da nessun altro stato.
  • Un ordine di inserzione non può essere impostato su ENTITY_STATUS_ACTIVE se la campagna principale non è attiva.
updateTime

string (Timestamp format)

Solo output. Timestamp dell'ultimo aggiornamento dell'ordine di inserimento. Assegnato dal sistema.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
partnerCosts[]

object (PartnerCost)

Facoltativo. I costi partner associati all'ordine di inserzione.

Se assente o vuoto nel metodo insertionOrders.create, l'ordine di inserzione appena creato erediterà i costi dei partner dalle impostazioni del partner.
pacing

object (Pacing)

Obbligatorio. L'impostazione della velocità di spesa del budget dell'ordine di inserzione.

pacingType PACING_TYPE_ASAP non è compatibile con pacingPeriod PACING_PERIOD_FLIGHT.
frequencyCap

object (FrequencyCap)

Obbligatorio. L'impostazione della quota limite dell'ordine di inserzione.
integrationDetails

object (IntegrationDetails)

Facoltativo. Dettagli aggiuntivi dell'integrazione dell'ordine di inserzione.
kpi

object (Kpi)

Obbligatorio. L'indicatore chiave di prestazione (KPI) dell'ordine di inserzione.

Questo valore viene indicato come "Obiettivo" nell'interfaccia di Display & Video 360.
budget

object (InsertionOrderBudget)

Obbligatorio. Le impostazioni di allocazione del budget dell'ordine di inserzione.
bidStrategy

object (BiddingStrategy)

Facoltativo. La strategia di offerta dell'ordine di inserzione. Per impostazione predefinita, è impostato fixedBid.
reservationType

enum (ReservationType)

Solo output. Il tipo di prenotazione dell'ordine di inserzione.
optimizationObjective

enum (OptimizationObjective)

Facoltativo. Lo scopo dell'ottimizzazione dell'ordine di inserzione.

InsertionOrderType

Possibili tipi di ordine di inserzione.

Il tipo di ordine di inserzione determina le impostazioni e le opzioni applicabili, ad esempio il formato degli annunci o le opzioni di targeting.

Enum
INSERTION_ORDER_TYPE_UNSPECIFIED Il tipo di ordine di inserzione non è specificato o è sconosciuto.
RTB Offerte in tempo reale.
OVER_THE_TOP Over-the-top.

KPI

Impostazioni che controllano l'indicatore chiave di prestazione (KPI) di un ordine di inserzione.

Rappresentazione 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.
}
Campi
kpiType

enum (KpiType)

Obbligatorio. Il tipo di KPI.
kpiAlgorithmId

string (int64 format)

Facoltativo. ID algoritmo offerte personalizzate associato a KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST. Questo campo viene ignorato se non viene selezionato il KPI corretto.
Campo unione kpi_value. Obbligatorio. Il valore del KPI. Il campo pertinente corrisponde a kpi_type. kpi_value può essere solo uno dei seguenti:
kpiAmountMicros

string (int64 format)

L'importo dell'obiettivo, in micro della valuta dell'inserzionista.

Applicabile quando kpiType è uno dei seguenti:

  • KPI_TYPE_CPM
  • KPI_TYPE_CPC
  • KPI_TYPE_CPA
  • KPI_TYPE_CPIAVC
  • KPI_TYPE_VCPM

Ad esempio: 1500000 rappresenta 1,5 unità standard della valuta.
kpiPercentageMicros

string (int64 format)

La rappresentazione decimale della percentuale dell'obiettivo in micro.

Applicabile quando kpiType è uno dei seguenti:

  • 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

Ad esempio, 70000 rappresenta il 7% (decimale 0,07).
kpiString

string

Una stringa KPI, che può essere vuota. Deve essere codificato in UTF-8 e non deve contenere più di 100 caratteri.

Applicabile quando kpiType è KPI_TYPE_OTHER.

KpiType

Possibili tipi di indicatori chiave di prestazione (KPI).

Enum
KPI_TYPE_UNSPECIFIED Il tipo di KPI non è specificato o è sconosciuto in questa versione.
KPI_TYPE_CPM L'indicatore chiave di rendimento è il CPM (costo per mille impressioni).
KPI_TYPE_CPC Il KPI è il CPC (costo per clic).
KPI_TYPE_CPA Il KPI è il CPA (costo per azione).
KPI_TYPE_CTR Il KPI è la percentuale di CTR (percentuale di clic).
KPI_TYPE_VIEWABILITY Il KPI è la percentuale di visibilità.
KPI_TYPE_CPIAVC Il KPI è CPIAVC (costo per impressione udibile e visibile al termine).
KPI_TYPE_CPE L'KPI è il CPE (costo per interazione).
KPI_TYPE_CPV Il KPI è impostato in CPV (costo per visualizzazione).
KPI_TYPE_CLICK_CVR L'KPI è la percentuale del tasso di conversione dei clic (conversioni per clic).
KPI_TYPE_IMPRESSION_CVR L'KPI è la percentuale del tasso di conversione delle impressioni (conversioni per impressione).
KPI_TYPE_VCPM Il KPI è il VCPM (costo per mille impressioni visibili).
KPI_TYPE_VTR Il KPI è la percentuale del tasso di visualizzazione di YouTube (visualizzazioni di YouTube per impressione).
KPI_TYPE_AUDIO_COMPLETION_RATE L'indicatore chiave di rendimento è la percentuale di completamento audio (ascolti audio completi per impressione).
KPI_TYPE_VIDEO_COMPLETION_RATE Il KPI è la percentuale di completamento video (visualizzazioni di video complete per impressione).
KPI_TYPE_CPCL Il KPI è impostato in CPCL (costo per ascolto audio completo).
KPI_TYPE_CPCV Il KPI è impostato in CPCV (costo per visualizzazione di video completa).
KPI_TYPE_TOS10 Il KPI è impostato in base alla percentuale di tempo sullo schermo di almeno 10 secondi (percentuale di impressioni misurabili e non ignorabili visualizzate sullo schermo per almeno 10 secondi).
KPI_TYPE_MAXIMIZE_PACING Il KPI è impostato per massimizzare l'impatto del brand dando la priorità all'utilizzo dell'intero budget.
KPI_TYPE_CUSTOM_IMPRESSION_VALUE_OVER_COST Il KPI è impostato sul valore delle impressioni personalizzate diviso per il costo.
KPI_TYPE_OTHER Il KPI è un altro valore.

InsertionOrderBudget

Impostazioni che controllano la modalità di allocazione del budget dell'ordine di inserzione.

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

enum (BudgetUnit)

Obbligatorio. Immutabile. L'unità di budget specifica se il budget è basato sulla valuta o sulle impressioni.
automationType

enum (InsertionOrderAutomationType)

Facoltativo. Il tipo di automazione utilizzato per gestire l'offerta e il budget per l'ordine di inserzione.

Se questo campo non è specificato al momento della creazione, il valore predefinito è INSERTION_ORDER_AUTOMATION_TYPE_NONE.
budgetSegments[]

object (InsertionOrderBudgetSegment)

Obbligatorio. L'elenco dei segmenti di budget. Utilizza un segmento di budget per specificare un budget specifico per un determinato periodo di tempo durante cui un ordine di inserzione è in esecuzione.

InsertionOrderAutomationType

Opzioni possibili per automatizzare l'offerta e il budget dell'ordine di inserzione.

Enum
INSERTION_ORDER_AUTOMATION_TYPE_UNSPECIFIED L'opzione di automazione dell'ordine di inserzione non è specificata o è sconosciuta in questa versione.
INSERTION_ORDER_AUTOMATION_TYPE_BUDGET Allocazione automatica del budget. Consenti al sistema di trasferire automaticamente il budget agli elementi pubblicitari proprietari per ottimizzare il rendimento definito da kpi. Nessuna automazione delle impostazioni di offerta.
INSERTION_ORDER_AUTOMATION_TYPE_NONE Nessuna automazione dell'offerta o del budget a livello di ordine di inserzione. L'offerta e il budget devono essere configurati manualmente a livello di elemento pubblicitario.
INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET Consenti al sistema di aggiustare automaticamente le offerte e spostare il budget sugli elementi pubblicitari proprietari per ottimizzare il rendimento definito da kpi.

InsertionOrderBudgetSegment

Impostazioni che controllano il budget di un singolo segmento di budget.

Rappresentazione JSON 
{
  "budgetAmountMicros": string,
  "description": string,
  "dateRange": {
    object (DateRange)
  },
  "campaignBudgetId": string
}
Campi
budgetAmountMicros

string (int64 format)

Obbligatorio. L'importo del budget che l'ordine di inserzione spenderà per il dateRange specificato. L'importo è in micro. Deve essere maggiore di 0. Ad esempio, 500000000 rappresenta 500 unità standard della valuta.
description

string

Facoltativo. La descrizione del segmento di budget. Può essere utilizzato per inserire le informazioni sull'ordine di acquisto per ogni segmento di budget e stamparle sulle fatture.

Deve essere codificato in UTF-8.
dateRange

object (DateRange)

Obbligatorio. Le impostazioni delle date di inizio e di fine del segmento di budget. Vengono risolti in relazione al fuso orario dell'inserzionista principale.

  • Quando crei un nuovo segmento di budget, sia startDate che endDate devono essere nel futuro.
  • Un segmento di budget esistente con un startDate in passato ha un endDate modificabile, ma un startDate non modificabile.
  • endDate deve essere startDate o versioni successive, entrambe precedenti all'anno 2037.
campaignBudgetId

string (int64 format)

Facoltativo. Il budgetId del budget della campagna di cui fa parte questo segmento di budget dell'ordine di inserzione.

OptimizationObjective

Possibili tipi di obiettivi di ottimizzazione.

Enum
OPTIMIZATION_OBJECTIVE_UNSPECIFIED Il valore del tipo non è specificato o è sconosciuto in questa versione.
CONVERSION Dai la priorità alle impressioni che aumentano le vendite e le conversioni.
CLICK Dai la priorità alle impressioni che aumentano il traffico sul sito web, nelle app e negli store.
BRAND_AWARENESS Dai la priorità alle impressioni di una qualità specifica.
CUSTOM L'obiettivo è definito dall'algoritmo di offerte personalizzate assegnato.
NO_OBJECTIVE L'obiettivo non è definito. È possibile utilizzare qualsiasi KPI o strategia di offerta.

Metodi

create

 Crea un nuovo ordine di inserzione.

delete

 Elimina un ordine di inserzione.

get

 Recupera un ordine di inserzione.

list

 Elenca gli ordini di inserzione di un inserzionista.

listAssignedTargetingOptions

 Elenca le opzioni di targeting assegnate di un ordine di inserzione nei vari tipi di targeting.

patch

 Aggiorna un ordine di inserzione esistente.