Utilizzare l'API DAI Ad Break

L'API Google Dynamic Ad Insertion (DAI) Ad Break ti consente di creare e gestire i dati di targeting degli annunci e la tempistica delle interruzioni pubblicitarie nei tuoi live streaming.

Questa guida illustra l'utilizzo dell'API DAI Ad Break per creare, aggiornare ed eliminare un'interruzione pubblicitaria per un evento live streaming Google DAI.

Prerequisiti

Per utilizzare l'API DAI per le interruzioni pubblicitarie, devi disporre di quanto segue:

Configurare l'accesso API

Per abilitare l'API, completa i seguenti passaggi:

  1. Creare un service account. Per saperne di più, vedi Creare un service account.
  2. Aggiungi il service account alla tua rete Google Ad Manager. Per ulteriori informazioni, vedi Aggiungere un utente dell'account di servizio per l'accesso tramite API.
  3. Fornisci l'indirizzo email dell'account di servizio e il codice di rete Google Ad Manager al tuo account manager Google.
  4. Abilita l'API Google Ad Manager Video nel tuo progetto Google Cloud. Per maggiori informazioni, vedi Abilitare "API e servizi" per la tua app.

Autenticarsi con OAuth2

Per autorizzare le richieste API, segui questi passaggi:

  1. Genera il token di accesso con l'ambito https://www.googleapis.com/auth/video-ads.
  2. In ogni richiesta, includi il token di accesso all'API come valore dell'intestazione HTTP Authorization Bearer. Per saperne di più, consulta Chiama le API di Google.

L'esempio seguente genera un token OAuth con l'ambito dell'API DAI Ad Break: interruzione pubblicitaria

gcloud auth print-access-token --scopes='https://www.googleapis.com/auth/video-ads'

Se l'operazione ha esito positivo, viene visualizzato il seguente token di accesso:

ya29.c.c0ASRK0GYUYU0...

Effettuare la prima richiesta

Per recuperare le interruzioni pubblicitarie per un evento live streaming, utilizza il metodo GET per elencare tutte le entità AdBreak in base alla chiave asset generata dal sistema dell'evento o alla tua chiave asset personalizzata.

L'API DAI Ad Break restituisce solo le entità AdBreak create tramite l'API, escludendo le interruzioni pubblicitarie create dal manifest, dalla richiesta di segmento di pod o dalla richiesta di manifest di pod.

La seguente richiesta di esempio elenca le entità AdBreak in base a un valore assetKey:

curl -X GET "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN"

In caso di esito positivo, viene visualizzata la seguente risposta JSON:

{
 "adBreaks": []
}

Man mano che crei altre entità AdBreak tramite l'API e richiedi l'elenco, visualizzi la seguente risposta JSON:

{
 "adBreaks": [
    {
      "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T15:00:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate",
      "breakState": "BREAK_STATE_SCHEDULED"
    },
    {
      "name": "networks/.../assets/.../adBreaks/cc68b0df-0257-46e7-8193-254060b6256c",
      "breakSequence": "1",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T14:30:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate",
      "breakState": "BREAK_STATE_COMPLETE"
    },
    ...
  ],
  "nextPageToken": "ChAIARIMCNDn97IGEJbhhYUC"
}

Crea un'entità AdBreak

Per comunicare a Google DAI un'interruzione pubblicitaria imminente per un evento in live streaming, utilizza il metodo POST.

  • Per creare una nuova entità AdBreak, devi attendere che quella precedente passi allo stato BREAK_STATE_COMPLETE.
  • In alternativa, puoi eliminare l'entità AdBreak in attesa per crearne una nuova.
  • Per creare più di un'entità AdBreak per un singolo evento live streaming, contatta il tuo account manager per la configurazione avanzata.

La seguente richiesta di esempio crea un'interruzione pubblicitaria prevista per l'inizio del 3 giugno 2025 alle ore 15:00:00 UTC:

curl -X POST "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN" \
  -d '{
    "expectedDuration": "30s",
    "expectedStartTime": "2025-06-03T15:00:00Z",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
  }'

In caso di esito positivo, viene visualizzata la seguente risposta JSON:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:00:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate",
  "breakState": "BREAK_STATE_SCHEDULED"
}

Il risultato contiene l'ID interruzione pubblicitaria necessario per recuperare, modificare o eliminare l'interruzione pubblicitaria. Nella risposta di esempio, l'ID interruzione pubblicitaria creato è bcc402a6-9880-4b8b-8e4a-a8cd3688f854.

Recuperare un'entità AdBreak

Utilizza il metodo GET per recuperare i dettagli di una specifica entità AdBreak, inclusi i metadati relativi allo stato e alla tempistica dell'interruzione pubblicitaria.

curl -X GET \
'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

In caso di esito positivo, viene visualizzata la seguente risposta JSON:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate",
  "breakState": "BREAK_STATE_SCHEDULED"
}

Aggiorna un'entità AdBreak

Per modificare un'interruzione pubblicitaria imminente prima dell'inizio della decisione pubblicitaria, utilizza il metodo PATCH:

curl -X PATCH 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN' \
  -d '{"expectedStartTime": "2025-06-03T15:10:00Z"}'

In caso di esito positivo, viene visualizzata la seguente risposta JSON:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate",
  "breakState": "BREAK_STATE_SCHEDULED"
}

Eliminare un'entità Interruzione pubblicitaria

Utilizza il metodo DELETE per annullare la decisione pubblicitaria per un'interruzione pubblicitaria creata tramite l'API prima che l'interruzione pubblicitaria inizi a essere pubblicata.

La seguente richiesta di esempio elimina un'interruzione pubblicitaria:

curl -X DELETE 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

In caso di esito positivo, viene visualizzata la risposta HTTP/1.1 200 OK.

Scopri le funzionalità avanzate delle interruzioni pubblicitarie

Dopo aver creato e gestito le interruzioni pubblicitarie, esplora queste funzionalità dell'API DAI Ad Break: