Utiliser l'API DAI Ad Break

L'API DAI Ad Break vous permet de créer et de gérer les données de ciblage des annonces et de timing des pauses publicitaires dans vos diffusions en direct.

Ce guide explique comment utiliser l'API Ad Break de DAI pour créer, modifier et supprimer un bloc d'annonces pour un événement de diffusion en direct Google Dynamic Ads Insertion (DAI).

Prérequis

Pour utiliser l'API DAI Ad Break, vous devez disposer des éléments suivants :

Configurer l'accès à l'API

Pour activer l'API, procédez comme suit :

  1. Créez un compte de service. Pour en savoir plus, consultez Créer un compte de service.
  2. Ajoutez le compte de service à votre réseau Google Ad Manager. Pour en savoir plus, consultez Ajouter un utilisateur à un compte de service afin d'accéder à l'API.
  3. Fournissez l'adresse e-mail du compte de service et votre code de réseau Google Ad Manager à votre responsable de compte Google.
  4. Activez l'API Google Ad Manager Video dans votre projet Google Cloud. Pour en savoir plus, consultez Activer "API et services" pour votre application.

S'authentifier avec OAuth2

Pour autoriser vos requêtes API, procédez comme suit :

  1. Générez le jeton d'accès avec le champ d'application https://www.googleapis.com/auth/video-ads.
  2. Dans chaque requête, incluez le jeton d'accès à l'API en tant que valeur Bearer de l'en-tête HTTP Authorization. Pour en savoir plus, consultez Appeler les API Google.

L'exemple suivant génère un jeton OAuth avec le champ d'application de l'API DAI Ad Break :

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

Si l'opération réussit, le jeton d'accès suivant s'affiche :

ya29.c.c0ASRK0GYUYU0...

Envoyer la première requête

Pour récupérer les pauses publicitaires d'un événement en direct, utilisez la méthode GET pour lister toutes les entités AdBreak par la clé d'asset générée par le système de l'événement ou votre clé d'asset personnalisée.

L'API Ad Break DAI ne renvoie que les entités AdBreak créées via l'API, à l'exclusion des pauses publicitaires créées à partir de la demande de fichier manifeste, de la demande de segment de série d'annonces ou de la demande de fichier manifeste de série d'annonces.

L'exemple de requête suivant liste les entités AdBreak par valeur 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"

Si l'opération réussit, la réponse JSON suivante s'affiche :

{
 "adBreaks": []
}

Lorsque vous créez des entités AdBreak supplémentaires via l'API et que vous demandez la liste, la réponse JSON suivante s'affiche :

{
 "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"
}

Créer une entité AdBreak

Pour informer Google DAI d'une coupure publicitaire à venir pour un événement de diffusion en direct, utilisez la méthode POST.

  • Pour créer une entité AdBreak, vous devez attendre que la précédente passe à l'état BREAK_STATE_COMPLETE.
  • Vous pouvez également supprimer l'entité AdBreak en attente pour en créer une autre.
  • Pour créer plusieurs entités AdBreak pour un même événement en direct, contactez votre responsable de compte pour obtenir une configuration avancée.

L'exemple de requête suivant crée un break publicitaire qui devrait commencer le 3 juin 2025 à 15h00: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"
  }'

Si l'opération réussit, la réponse JSON suivante s'affiche :

{
  "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",
}

Le résultat contient l'ID de la coupure publicitaire requis pour récupérer, modifier ou supprimer la coupure publicitaire. Dans l'exemple de réponse, l'ID du point d'insertion d'annonce créé est bcc402a6-9880-4b8b-8e4a-a8cd3688f854.

Récupérer une entité AdBreak

Utilisez la méthode GET pour récupérer les détails d'une entité AdBreak spécifique, y compris l'état de la coupure publicitaire et les métadonnées de timing.

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'

Si l'opération réussit, la réponse JSON suivante s'affiche :

{
  "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",
}

Mettre à jour une entité AdBreak

Pour modifier une coupure publicitaire à venir avant le début de la décision publicitaire, utilisez la méthode 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"}'

Si l'opération réussit, la réponse JSON suivante s'affiche :

{
  "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",
}

Supprimer une entité AdBreak

Utilisez la méthode DELETE pour annuler la décision publicitaire pour un emplacement publicitaire créé via l'API avant le début de la diffusion de l'emplacement publicitaire.

L'exemple de requête suivant supprime une coupure publicitaire :

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

Si l'opération réussit, la réponse HTTP/1.1 200 OK s'affiche.

Découvrir les fonctionnalités avancées des coupures publicitaires

Après avoir créé et géré des pauses publicitaires, découvrez les fonctionnalités suivantes de l'API DAI Ad Break :