Utilizzare l'API DAI Ad Break

L'API 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 una pausa pubblicitaria per un evento live streaming di inserimento di annunci dinamici (DAI) di Google.

Prerequisiti

Per utilizzare l'API DAI Ad Break, devi disporre di quanto segue:

Configurare l'accesso API

Per abilitare l'API, completa i seguenti passaggi:

  1. Crea un account di servizio. Per ulteriori informazioni, vedi Creare un service account.
  2. Aggiungi l'account di servizio alla tua rete Google Ad Manager. Per ulteriori informazioni, vedi Aggiungere un utente con relativo service account 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:

  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ù, vedi Chiama le API di Google.

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

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

Se l'operazione riesce, 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, escluse 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"
}

Creare 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 dell'interruzione dell'annuncio 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",
}

Aggiornare 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à AdBreak

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: