Cette page a été traduite par l'API Cloud Translation.

API Video Creative Ingest

L'API Video Creative Ingest permet aux systèmes publicitaires tiers d'ingérer de manière proactive des créations dans les produits YouTube et DAI. Ce processus garantit que lorsqu'une annonce est prise de décision à partir d'un ad server autre que Google, les créations renvoyées sont prêtes et disponibles pour être diffusées dans un flux vidéo YouTube ou DAI.

Le processus d'ingestion proactive des créations à partir de systèmes publicitaires tiers comporte deux parties principales. La première partie permet au système publicitaire tiers de fournir des créations à Google et de surveiller leur progression à mesure qu'elles sont ingérées dans l'infrastructure vidéo Google. Une fois les créations ingérées, les identifiants sont renvoyés au système publicitaire.

La deuxième étape consiste à ce que le système publicitaire récupère ces identifiants et les inclue dans les documents VAST qui font référence à la création envoyée, à l'aide de l'identifiant d'annonce universel (VAST 4.0 et versions ultérieures) ou d'une extension de création de type "UniversalAdId". Lorsqu'un document VAST du système publicitaire est rencontré au moment de la prise de décision dans la diffusion d'annonces en direct ou sur YouTube, le système de création extrait ces identifiants du VAST et récupère la création appropriée à partir de l'infrastructure vidéo Google pour l'insérer à la lecture.

Exigences pour le contenu multimédia

Les contenus multimédias de la création envoyés à l'API doivent répondre aux critères suivants pour que le système puisse les traiter correctement.

Types de contenu

Google accepte les types de fichiers multimédias suivants. Tout autre type de contenu multimédia peut être refusé lors de l'envoi.

video/mp4
video/webm
video/quicktime
video/avi
video/mpeg
video/x-flv
flv-application/octet-stream
application/octet-stream
video/3gpp
video/ogg
audio/mp4
audio/mpeg

Propriétés multimédias

Les supports envoyés doivent répondre aux critères suivants:

Le contenu multimédia doit comporter au moins une piste audio ou vidéo.
Les contenus multimédias doivent avoir une durée raisonnable. Rien qui ne dépasse quelques minutes.
Les fichiers multimédias doivent comporter une piste audio ou vidéo d'une durée supérieure à une seconde.
Si le contenu multimédia comporte de l'audio, il doit avoir une configuration de canaux audio standard, comme le son mono, stéréo ou surround.

Envoyer des créations pour ingestion

Schéma illustrant le processus d'ingestion

Un système publicitaire tiers envoie une requête HTTP à l'API Video Creative Ingest avec une liste des fichiers multimédias associés à la création.
L'API Video Creative Ingest sélectionne la création de la plus haute qualité dans la liste fournie et la télécharge depuis le CDN.
L'API Video Creative Ingest ingère la création téléchargée dans l'infrastructure vidéo Google, la rendant disponible à la fois pour les produits YouTube et DAI.
Une notification Pub/Sub est renvoyée au système publicitaire tiers avec l'état de la création. La notification indique si la vidéo a bien été importée pour YouTube et la publicité display. Si le chargement de la création a échoué, la notification indique la cause de l'échec.

Suivez ces consignes lorsque vous envoyez des créations.

Authentification

Vous devez accéder à l'API à l'aide d'un compte de service Google Cloud. Au moment de l'intégration, vous devez fournir à Google des informations de compte pour obtenir l'autorisation appropriée.

Une fois les informations du compte fournies à Google via creativeingestion@google.com, l'accès sera accordé aux points de terminaison de l'API et aux sujets Cloud PubSub utilisés pour publier des notifications.

Pour lancer le processus d'authentification, procédez comme suit:

Créez un compte Google Cloud.
Configurez un projet avec le compte pour envoyer des requêtes à l'API DAI.
Dans le projet, accédez à l'onglet IAM et administration à gauche, puis créez un compte de service. Les requêtes sont envoyées à l'aide du compte de service.
Activez l'API Pub/Sub et créez un seul sujet de notification partenaire auquel l'API publie toutes les notifications de réussite et d'échec de l'ingestion.

Si vous avez mis en place une règle d'administration de l'organisation concernant la restriction de domaine, vous devez ajouter l'ID client Google à la liste des clients autorisés. Contactez creativeingestion@google.com pour obtenir l'ID. Une fois cette opération effectuée, vous pouvez ajouter des principaux (notre compte robot) à partir de listes de clients autorisées (ID client de l'API) aux stratégies IAM (PubSub Publisher).

Ajoutez video-creative-library-discovery@system.gserviceaccount.com en tant qu'éditeur PubSub au sujet.
Fournissez à creativeingestion@google.com l'adresse e-mail du compte de service et le sujet PubSub pour enregistrer ces informations auprès de l'API.
Activez l'API DAI une fois le compte ajouté en tant que client de service.
Pour définir vos identifiants d'accès à l'API:
- Télécharger les identifiants du compte de service: cliquez sur le compte de service dans la section Service accounts (Comptes de service) de l'onglet IAM & Admin (IAM et administration), cliquez sur Create Key (Créer une clé) et stockez les identifiants.
- Authentifiez l'appelant de l'API. Définissez GOOGLE_APPLICATION_CREDENTIALS sur le chemin d'accès du fichier JSON. Consultez les exemples de code pour authentifier les clients gRPC dans les langages courants.

Ingestion des créations

Chaque fois qu'une nouvelle création est disponible dans le système publicitaire d'un partenaire, le système du partenaire doit l'envoyer à l'API Creative Ingest.

Lorsque de nouvelles créations sont envoyées à Google pour être chargées dans l'infrastructure vidéo, les mêmes données de création que celles incluses dans le document VAST généré par le système publicitaire doivent être fournies. Cela garantit que l'ingestion proactive des créations dans Google a le même comportement que le chargement des créations lorsqu'elles sont découvertes pour la première fois dans une réponse d'annonce.

Chaque création envoyée crée une opération d'ingestion de longue durée sur le serveur, dont l'état peut être interrogé. Une fois l'opération terminée, une ressource de création est créée dans le système. La réponse à l'envoi d'une création contient l'ID de l'opération issue de la demande. L'ID d'opération obtenu est inclus dans les notifications Cloud PubSub envoyées à la fin de l'opération pour la mettre en correspondance avec la création d'origine envoyée. L'ID d'opération peut également être utilisé pour vérifier la progression de l'opération à tout moment.

Demandes de créations

Les données sont envoyées à l'API sous forme de tampons de protocole ou d'objets JSON. Les tampons de protocole, envoyés à l'aide de gRPC, sont recommandés, car ils sont nécessaires pour consommer les notifications Pub/Sub. Le désamorçage du fichier JSON présente des complications supplémentaires en raison des champs google.protobuf.Any dans la réponse.

Réponses créatives

En cas de réussite, le serveur renvoie une réponse Protocol Buffer ou JSON, en fonction du type de requête. La réponse contient le nom de l'opération d'ingestion nouvellement créée et les détails de l'opération.

Lors de l'envoi initial, certaines des métadonnées associées à l'opération peuvent être vides et le résultat peut ne pas être présent. Une fois l'opération terminée, le résultat est renseigné avec la ressource de création (ou une erreur), et les métadonnées contiennent des informations sur l'état de l'ingestion.

Notez que les métadonnées doivent être désencodées à partir d'un proto Any dans le proto CreateCreativeOperationMetadata, et que la réponse (le cas échéant) doit être désencodée dans le proto Creative.

Bibliothèque cliente pour accéder à l'API

Pour intégrer l'API, procédez comme suit:

Téléchargez les dépendances des protocoles de tampon et déplacez l'intégralité du dossier google dans votre répertoire src. Vous pouvez ignorer cette étape si vous utilisez Google Cloud App Engine.
Utilisez le plug-in protoc pour générer du code gRPC à partir du fichier proto et placez le code généré dans le répertoire approprié.
Créez un fichier proto pour le proto renvoyé dans la notification PubSub. Répétez l'étape précédente pour générer du code à partir du proto.
Utilisez gRPC pour envoyer des requêtes à l'API:
1. Obtenez les identifiants par défaut avec les champs d'application suivants:
https://www.googleapis.com/auth/video-ads,

https://www.googleapis.com/auth/pubsub
1. Envoyez la requête à l'importation des créations.
- Connectez-vous à dai.googleapis.com:443 à l'aide des identifiants par défaut.
- Créez un bouchon client pour le service d'ingestion de créations à l'aide du code généré par le protocole gRPC.
- Appelez CreateCreative à l'aide du bouchon client.
Vous pouvez éventuellement créer un bouchon pour le service Operations à l'aide du code gRPC des opérations de longue durée (inclus dans le répertoire googleapis téléchargé à l'étape 2), qui peut être utilisé pour obtenir l'état d'une opération donnée (GetOperation).
Vérifiez les notifications Pub/Sub:
1. Utilisez la bibliothèque cliente PubSub ou gRPC pour vous connecter au service PubSub et interroger les notifications PubSub publiées sur le sujet fourni.
2. Désérialisez le message PubSub dans le proto de l'étape 4.
3. Chaque fois qu'une opération de longue durée est renvoyée à partir d'appels à CreateCreative, GetOperation ou dans une notification Pub/Sub, désassemblez les métadonnées dans CreateCreativeOperationMetadata dans discovery.proto à partir du proto google.protobuf.Any et de toute réponse dans Creative dans discovery.proto.

Exemple de code client Go

// Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package main

import (
  dai "google.golang.org/genproto/googleapis/ads/dai/v1"
  psnotif "protos/dai"
  "google.golang.org/genproto/googleapis/longrunning"
  "cloud.google.com/go/pubsub"
  "golang.org/x/net/context"
  "google.golang.org/grpc"
  "google.golang.org/grpc/credentials"
  "google.golang.org/grpc/credentials/oauth"
  "github.com/golang/protobuf/proto"
  anypb "github.com/golang/protobuf/ptypes/any"
)

var scopes = []string{"https://www.googleapis.com/auth/video-ads", "https://www.googleapis.com/auth/pubsub"}

const (
  subID = "sub-id" // The ID for the subscription to the topic you provided us (projects/<project ID>/subscriptions/<subscription ID>)
  project = "your-project-id" // Your Google Cloud Project ID
)

func main() {
  ctx := context.Background()
  crpc, err := oauth.NewApplicationDefault(ctx, scopes...)
  if err != nil {
    // TODO: Handle error
  }

  conn, err := grpc.Dial("dai.googleapis.com:443",
    grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")),
    grpc.WithPerRPCCredentials(crpc))
  if err != nil {
    // TODO: Handle error 
  }

  apiclient := dai.NewPartnerDiscoveryServiceClient(conn)
  opclient := longrunning.NewOperationsClient(conn)

  op, err := apiclient.CreateCreative(ctx, &dai.CreateCreativeRequest{
    // TODO: Add Creative with metadata and media files.
  })
  if err != nil {
    // TODO: Handle error
  }

  pubsubClient, err := pubsub.NewClient(ctx, project)
  if err != nil {
    // TODO: Handle error
  }
  sub := pubsubClient.Subscription(subID)

  // TODO: Pull from Pub/Sub subscription to receive messages, and acknowledge them
  var msg *pubsub.Message // Assume msg = a received Pub/Sub message

  // Unmarshal the Pub/Sub message into the proto created in step 9a of guide
  var n psnotif.CreateCreativeStatus
  if err := proto.Unmarshal(msg.Data, &n); err != nil {
    // TODO: Handle error
  }
  op = n.GetDetails()
  md, err = anyToMetadata(op.GetMetadata())
  if err != nil {
    // TODO: Handle error
  }
  // TODO: Check if ingest was successful and get Google Video ID from md.GetGvRegistryId()
  // TODO: Enable serving of creative using Google Video ID in VAST document

  // Optionally check the status of an ingest request using the status endpoint
  op, err = opclient.GetOperation(ctx, &longrunning.GetOperationRequest{Name:   op.Name})
  if err != nil {
    // TODO: Handle error
  }
}

// anyToMetadata converts the metadata Any field in an Operation message to
// CreateCreativeOperationMetadata.
func anyToMetadata(msg *anypb.Any) (*dai.CreateCreativeOperationMetadata, error) {
  var md dai.CreateCreativeOperationMetadata
  return &md, proto.Unmarshal(msg.Value, &md)
}

// anyToCreative converts the response Any field in an Operation message to
// Creative.
func anyToCreative(msg *anypb.Any) (*dai.Creative, error) {
  var cr dai.Creative
  return &cr, proto.Unmarshal(msg.Value, &cr)
}

Recherche de créations pendant la lecture

Organigramme du processus de recherche de créations

Demandes de l'utilisateur pour afficher du contenu dans YouTube ou dans la diffusion d'annonces in-stream
YouTube / DAI obtient une réponse VAST d'un système publicitaire tiers pour les annonces à insérer dans le contenu.
Les annonces renvoyées sont mappées aux créations précédemment ingérées. Ces créations sont prêtes à être lues. Elles sont extraites de l'infrastructure vidéo Google et diffusées pour l'utilisateur.

Documents VAST modifiés par le partenaire

Lorsqu'une réponse VAST est renvoyée par le système publicitaire après le chargement réussi de la création dans l'infrastructure vidéo Google, le document doit contenir une référence à la création traitée. Le document VAST doit continuer à inclure les fichiers multimédias d'une création donnée, mais il n'est pas garanti que ces fichiers multimédias seront utilisés par le système.

Il existe deux façons de faire référence à une création traitée dans un document VAST: ajouter un nouvel élément UniversalAdId au document VAST 4 ou ajouter une extension personnalisée.

Identifiant d'annonce universel

Le gvRegistryID renvoyé par l'API Video Creative Ingest est un identifiant public universel utilisé pour identifier de manière unique une création vidéo dans plusieurs systèmes publicitaires. Cet ID doit être ajouté aux documents VAST 4 ou version ultérieure du système publicitaire afin que, lorsqu'un document VAST est reçu par YouTube ou par la diffusion d'annonces instream, l'ID puisse être utilisé pour faire correspondre la création envoyée à l'origine.

Les systèmes publicitaires doivent ajouter un élément UniversalAdId à leurs documents VAST 4 et versions ultérieures sous le nœud "Creative". L'attribut idRegistry doit être défini sur "googlevideo" et la valeur doit être celle fournie dans l'état de la notification de création traitée avec succès.

Voici un exemple de document VAST 4 avec le nouvel identifiant d'annonce universel ajouté:

<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="4.0">
  <Ad id="318230556">
    <InLine>
      <AdSystem>DCM</AdSystem>
      <AdTitle>In-Stream Video</AdTitle>
      <Creatives>
        <Creative id="79534759" AdID="" sequence="1">
          <UniversalAdId idRegistry="googlevideo">dQw4w9WgXcQ</UniversalAdId>
          <Linear>
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <Mezzanine>
                <![CDATA[https://cdn.com/media.mp4]]>
              </Mezzanine>
              <MediaFile delivery="progressive" width="640" height="360" type="video/mp4" bitrate="313">
                <![CDATA[https://cdn.com/low-res-media.mp4]]>
              </MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

CreativeExtension

Étant donné que l'élément "Universal Ad ID" n'a été introduit que dans VAST 4.0, les mêmes données nécessitent une extension personnalisée pour être exposées dans les documents VAST dont la version est inférieure à 4.0. Pour ce faire, utilisez un élément CreativeExtension sous l'élément Creative de la spécification VAST.

La nouvelle extension introduite est une extension générique qui permet de renseigner n'importe quelle valeur d'identifiant AD Universel. Dans ce cas particulier, l'identifiant d'annonce universel appartient au registre googlevideo et l'ID correspond à l'ID de la vidéo Google.

<VAST version="3.0">
  <Ad id="318230556">
    <InLine>
      <AdSystem>My Ad Server</AdSystem>
      <AdTitle>Car Company</AdTitle>
      <Creatives>
        <Creative id="79534759" AdID="" sequence="1">
          <Linear>...</Linear>
          <CreativeExtensions>
            <CreativeExtension type="UniversalAdId">
              <UniversalAdId idRegistry="googlevideo">dQw4w9WgXcQ</UniversalAdId>
            </CreativeExtension>
          </CreativeExtensions>
        </Creative>
      </Creative>
    </InLine>
  </Ad>
</VAST>

L'approche CreativeExtension peut également être utilisée dans VAST 4 et versions ultérieures si l'ID UniversalAdId est déjà renseigné par un ID pour un autre registre UniversalAdId:

<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="4.0">
  <Ad id="318230556">
    <InLine>
      <AdSystem>DCM</AdSystem>
      <AdTitle>In-Stream Video</AdTitle>
      <Creatives>
        <Creative id="79534759" AdID="" sequence="1">
          <UniversalAdId idRegistry="other-registry">other-id</UniversalAdId>
          <Linear>
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <Mezzanine>
                <![CDATA[https://cdn.com/media.mp4]]>
              </Mezzanine>
              <MediaFile delivery="progressive" width="640" height="360" type="video/mp4" bitrate="313">
                <![CDATA[https://cdn.com/low-res-media.mp4]]>
              </MediaFile>
            </MediaFiles>
          </Linear>
          <CreativeExtensions>
            <CreativeExtension type="UniversalAdId">
              <UniversalAdId idRegistry="googlevideo">dQw4w9WgXcQ</UniversalAdId>
            </CreativeExtension>
          </CreativeExtensions>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

API Video Creative Ingest Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.