Rejoignez-nous en direct sur Discord sur le serveur de la communauté Google Advertising and Measurement et sur YouTube le 26 février à 10h EST ! Nous allons aborder les nouvelles fonctionnalités ajoutées à la version 23.1 de l'API Google Ads.

Mettre des vidéos en ligne

YouTubeVideoUploadService vous permet d'importer des vidéos directement sur YouTube à l'aide de l'API Google Ads. Ces vidéos peuvent ensuite être utilisées comme composants dans différents types d'annonces, comme les campagnes Performance Max ou les campagnes de génération de la demande.

Ce service simplifie le processus de création d'annonces vidéo en gérant le processus d'importation sur YouTube et en s'assurant que les vidéos sont correctement associées à votre compte.

Concepts clés

Avant de commencer, il est important de comprendre comment les mises en ligne de vidéos sont gérées et les différents états qu'elles peuvent prendre.

Propriété de la chaîne

Lorsque vous mettez en ligne une vidéo, vous pouvez spécifier la chaîne YouTube de destination à l'aide du champ channel_id dans la ressource YouTubeVideoUpload :

Chaîne (de marque) appartenant à l'annonceur : indiquez l'channel_id d'une chaîne YouTube appartenant à l'annonceur. Importer une vidéo sur une chaîne de marque permet de mieux contrôler sa confidentialité et sa visibilité.
Chaîne gérée par Google : si channel_id est omis, la vidéo est mise en ligne sur une chaîne YouTube gérée par Google et associée au compte Google Ads.

États d'importation

Le cycle de vie d'une vidéo YouTube mise en ligne est suivi par le champ state. L'énumération YouTubeVideoUploadState définit les états suivants :

État	Description
`PENDING`	La vidéo est en cours d'importation.
`UPLOADED`	La vidéo a bien été mise en ligne et est en cours de traitement par YouTube.
`PROCESSED`	La vidéo a bien été traitée et est prête à être utilisée.
`FAILED`	L'importation ou le traitement ont échoué et ne peuvent pas être effectués.
`REJECTED`	La vidéo a été refusée pour des raisons de validation ou de non-respect des règles.
`UNAVAILABLE`	L'état de la vidéo n'est pas disponible. Il est possible qu'elle ait été supprimée de YouTube.

Paramètres de confidentialité

Le champ video_privacy permet de contrôler qui peut voir la vidéo mise en ligne. L'enum YouTubeVideoPrivacy est compatible avec les éléments suivants :

PUBLIC : la vidéo est disponible pour tous les utilisateurs de YouTube. (Autorisé uniquement pour les chaînes de marques)
UNLISTED : la vidéo n'est pas disponible dans la recherche, mais toute personne disposant du lien peut la regarder. Il s'agit de l'option par défaut et de la seule option disponible pour les chaînes gérées par Google.

Mettre en ligne une vidéo

Pour importer une vidéo, vous devez utiliser une requête en plusieurs parties à la méthode CreateYouTubeVideoUpload. La requête contient à la fois les métadonnées de l'importation et le fichier vidéo lui-même.

1. Lancer l'importation

Créez un CreateYouTubeVideoUploadRequest en spécifiant les éléments suivants :

customer_id : votre numéro client Google Ads.
you_tube_video_upload : objet YouTubeVideoUpload avec video_title, video_description et, éventuellement, channel_id et video_privacy.

Si vous utilisez une bibliothèque cliente, appelez la méthode CreateYouTubeVideoUpload en transmettant votre fichier vidéo. L'importation de la vidéo sera gérée en interne.

Java

This example is not yet available in Java; you can take a look at the other languages.

C#

This example is not yet available in C#; you can take a look at the other languages.

PHP

This example is not yet available in PHP; you can take a look at the other languages.

Python

yt_service: YouTubeVideoUploadServiceClient = client.get_service(
    "YouTubeVideoUploadService"
)

create_upload_request: CreateYouTubeVideoUploadRequest = (
    youtube_video_upload_service.CreateYouTubeVideoUploadRequest()
)
create_upload_request.customer_id = customer_id
create_upload_request.you_tube_video_upload.video_title = "Test Video"
create_upload_request.you_tube_video_upload.video_description = (
    "Test Video Description"
)
create_upload_request.you_tube_video_upload.video_privacy = (
    client.enums.YouTubeVideoPrivacyEnum.UNLISTED
)

video_upload_resource_name: str
with open(video_file_path, "rb") as stream:
    response: CreateYouTubeVideoUploadResponse = (
        yt_service.create_you_tube_video_upload(
            stream=stream,
            request=create_upload_request,
            retry=None,
        )
    )
    print(f"Created YouTube video upload: {response.resource_name}")upload_video.py

Ruby

This example is not yet available in Ruby; you can take a look at the other languages.

Perl

This example is not yet available in Perl; you can take a look at the other languages.

curl

# 
# Use the --i curl parameter to capture response headers in the $RESPONSE
# variable.
FILE_SIZE=$(wc -c < "${VIDEO_FILE_NAME}" | tr -d '\r')
RESPONSE=$(curl -i -f -v -s --request POST \
"https://googleads.googleapis.com/resumable/upload/v${API_VERSION}/customers/${CUSTOMER_ID}:youTubeVideoUploads:create" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--header "X-Goog-Upload-Protocol: resumable" \
--header "X-Goog-Upload-Command: start" \
--header "X-Goog-Upload-Header-Content-Length: ${FILE_SIZE}" \
--data @- <<EOF
{
  "customer_id": "${CUSTOMER_ID}",
  "you_tube_video_upload": {
    "video_title": "${VIDEO_TITLE}",
    "video_description": "${VIDEO_DESCRIPTION}",
    "video_privacy": "UNLISTED"
  }
}
EOF
)

# Extract the value of the "x-goog-upload-url" header from the HTTP response.
UPLOAD_URL=$(echo "${RESPONSE}" \
  | grep -i '^x-goog-upload-url' \
  | awk '{print $2}' \
  | tr -d '\r')
CHUNK_SIZE=$(echo "${RESPONSE}" \
  | grep -i '^x-goog-upload-chunk-granularity' \
  | awk '{print $2}' \
  | tr -d '\r')upload_video.sh

Si vous utilisez REST, la section suivante décrit comment gérer l'importation de vidéos.

2. Mettre en ligne la vidéo

Lorsque vous envoyez une requête REST à la méthode CreateYouTubeVideoUpload, la réponse contient l'URL à utiliser pour importer les octets vidéo dans l'en-tête de réponse HTTP x-goog-upload-url, ainsi que d'autres métadonnées telles que la taille attendue de chaque bloc pour les importations par blocs.

Vous pouvez également déclarer la taille de la vidéo que vous allez mettre en ligne au début du processus, avec l'en-tête de requête HTTP x-goog-upload-header-content-length.

Pour obtenir une description complète des en-têtes HTTP utilisés dans le protocole d'importation de vidéos, consultez l'exemple de code suivant :

# Take the first ${CHUNK_SIZE} bytes of the video file and upload them.
head -c ${CHUNK_SIZE} ${VIDEO_FILE_NAME} | curl -i -v -X PUT "${UPLOAD_URL}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--header "X-Goog-Upload-Offset: 0" \
--header "X-Goog-Upload-Command: upload" \
--header "Content-Length: ${CHUNK_SIZE}" \
--data-binary @-

# Query the status of the upload.
QUERY_RESPONSE=$(curl -i -s -X POST "${UPLOAD_URL}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--header "X-Goog-Upload-Command: query")

# Extract the value of the "x-goog-upload-size-received" header from the HTTP
# response.
UPLOADED_BYTES=$(echo "${QUERY_RESPONSE}" \
  | grep -i '^x-goog-upload-size-received' \
  | awk '{print $2}' \
  | tr -d '\r')

echo "Uploaded ${UPLOADED_BYTES} bytes."

REMAINING_BYTES=$((FILE_SIZE - UPLOADED_BYTES))
echo "${REMAINING_BYTES} bytes remaining to upload."

FINALIZE_RESPONSE=$(tail -c ${REMAINING_BYTES} ${VIDEO_FILE_NAME} | curl -v -X PUT "${UPLOAD_URL}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--header "X-Goog-Upload-Offset: ${UPLOADED_BYTES}" \
--header "X-Goog-Upload-Command: upload, finalize" \
--data-binary @-)
UPLOADED_VIDEO_RESOURCE_NAME=$(echo $FINALIZE_RESPONSE | jq -r '.resourceName')upload_video.sh

3. Récupérer l'état de la mise en ligne de la vidéo

Une fois que vous avez commencé à importer une vidéo, vous pouvez récupérer son état en interrogeant la ressource you_tube_video_upload avec GAQL :

Java

This example is not yet available in Java; you can take a look at the other languages.

C#

This example is not yet available in C#; you can take a look at the other languages.

PHP

This example is not yet available in PHP; you can take a look at the other languages.

Python

# Retrieve the metadata of the newly uploaded video.
query: str = f"""
    SELECT
      you_tube_video_upload.resource_name,
      you_tube_video_upload.video_id,
      you_tube_video_upload.state
    FROM you_tube_video_upload
    WHERE you_tube_video_upload.resource_name = '{video_upload_resource_name}'"""

ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")
stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
    customer_id=customer_id, query=query
)

for row in itertools.chain.from_iterable(batch.results for batch in stream):
    video = row.you_tube_video_upload
    print(
        f"Video with ID {row.you_tube_video_upload.video_id} was found in state {row.you_tube_video_upload.state}."
    )upload_video.py

Ruby

This example is not yet available in Ruby; you can take a look at the other languages.

Perl

This example is not yet available in Perl; you can take a look at the other languages.

curl

curl -i -v -X POST \
"https://qa-prod-googleads.sandbox.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \
--header "Content-Type: application/json" \
  --header "Developer-Token: ${DEVELOPER_TOKEN}" \
  --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
  --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
  --data @- <<EOF
{
  "query": "SELECT you_tube_video_upload.resource_name, you_tube_video_upload.video_id, you_tube_video_upload.state FROM you_tube_video_upload WHERE you_tube_video_upload.resource_name = '$UPLOADED_VIDEO_RESOURCE_NAME'"
}
EOFupload_video.sh

Gérer les importations

Une fois une vidéo importée, vous pouvez l'utiliser comme composant vidéo.

Utiliser la vidéo importée

Une fois qu'une vidéo a atteint l'état PROCESSED, vous pouvez trouver son ID vidéo YouTube dans le champ video_id de la ressource YouTubeVideoUpload.

Utilisez video_id pour créer un VideoAsset ou l'associer directement aux types d'annonces compatibles avec les vidéos YouTube en faisant référence à l'ID de la vidéo.

Mettre à jour les métadonnées

Vous pouvez mettre à jour les métadonnées d'une vidéo importée via cette API à l'aide de la méthode UpdateYouTubeVideoUpload. Seuls les champs video_title, video_description et video_privacy peuvent être mis à jour.

Supprimer des importations

Si vous devez supprimer des vidéos importées avec l'API Google Ads, utilisez la méthode RemoveYouTubeVideoUpload. La vidéo sera alors supprimée de la bibliothèque de composants Google Ads et de YouTube.

Composants Message pour les établissements

Rapports

Mettre des vidéos en ligne Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Concepts clés

Propriété de la chaîne

États d'importation

Paramètres de confidentialité

Mettre en ligne une vidéo

1. Lancer l'importation

Java

C#

PHP

Python

Ruby

Perl

curl

2. Mettre en ligne la vidéo

3. Récupérer l'état de la mise en ligne de la vidéo

Java

C#

PHP

Python

Ruby

Perl

curl

Gérer les importations

Utiliser la vidéo importée

Mettre à jour les métadonnées

Supprimer des importations

Mettre des vidéos en ligne