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 le timing des blocs d'annonces dans vos diffusions en direct.

Ce guide explique comment utiliser l'API Ad Break 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 clé d'asset générée par le système pour l'événement ou par votre clé d'asset personnalisée.

L'API DAI Ad Break 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.
  • 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.

La requête d'exemple suivante 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 l'insertion 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 bloc d'annonces créé via l'API avant le début de la diffusion du bloc d'annonces.

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 pauses publicitaires

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