Utiliser l'API DAI Ad Break

L'API Google Dynamic Ad Insertion (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 DAI Ad Break pour créer, modifier et supprimer une coupure publicitaire pour un événement de diffusion en direct Google DAI.

Prérequis

Pour utiliser l'API de coupure publicitaire DAI, 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 de compte de service pour l'accès à l'API.
  3. Communiquez 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 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 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 une coupure publicitaire qui devrait commencer le 3 juin 2025 à 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"
  }'

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 de la coupure publicitaire créée 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 une coupure publicitaire créée via l'API avant le début de la diffusion de la coupure.

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 coupures publicitaires, découvrez les fonctionnalités suivantes de l'API DAI Ad Break :