Importer des vidéos

Le YouTubeVideoUploadService vous permet de mettre en ligne des vidéos directement sur YouTube via l'API Google Ads. Ces vidéos peuvent ensuite être utilisées pour créer des composants vidéo dans différents types d'annonces, tels que les campagnes Performance Max ou Demand Gen.

Ce service simplifie le processus de création d'annonces vidéo en gérant la mise en ligne 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 traverser.

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 de le champ channel_id dans la ressource YouTubeVideoUpload :

  • Chaîne appartenant à l'annonceur (marque) : fournissez le channel_id d'une chaîne YouTube existante appartenant à l'annonceur. Cette option n'est compatible qu'avec le flux d'authentification des utilisateurs . Elle ne peut pas être utilisée avec des comptes de service.
  • 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 de la mise en ligne

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

État Description
PENDING La vidéo est en cours de mise en ligne.
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 La mise en ligne ou le traitement a échoué et ne peut pas être effectué.
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. Elle a peut-être été supprimée de YouTube.

Paramètres de confidentialité

Le champ video_privacy contrôle qui peut voir la vidéo mise en ligne. L' YouTubeVideoPrivacy enum est compatible avec les options suivantes :

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

Divulgation de contenu génératif

À partir de la version 26, en vertu de réglementations telles que le règlement européen sur l'IA, les annonceurs peuvent indiquer si le contenu vidéo mis en ligne contient des médias générés par l'IA ou synthétiques.

Le champ video_content_metadata dans YouTubeVideoUpload contient VideoContentMetadata. Définissez son champ imbriqué generative_content_disclosure à l'aide de l' YouTubeVideoUploadGenerativeContentDisclosure enum :

Valeur Description
NON_GENERATIVE_CONTENT L'annonceur a indiqué que la vidéo n'était pas générée par l'IA.
GENERATIVE_CONTENT L'annonceur a indiqué que la vidéo était générée par l'IA.

Mettre en ligne une vidéo

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

1. Lancer la mise en ligne

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

  • customer_id : votre numéro client Google Ads.
  • you_tube_video_upload: un objet YouTubeVideoUpload avec video_title, video_description et, éventuellement, channel_id, video_privacy et, à partir de la version 26, video_content_metadata.

Si vous utilisez une bibliothèque cliente, appelez la CreateYouTubeVideoUpload méthode, en transmettant votre fichier vidéo. La mise en ligne 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#

YouTubeVideoUploadServiceClient ytService = client.GetService(
    Services.V25.YouTubeVideoUploadService);

CreateYouTubeVideoUploadRequest createUploadRequest =
    new CreateYouTubeVideoUploadRequest()
    {
        CustomerId = customerId.ToString(),
        YouTubeVideoUpload = new YouTubeVideoUpload()
        {
            VideoTitle = "Test Video",
            VideoDescription = "Test Video Description",
            VideoPrivacy = YouTubeVideoPrivacy.Unlisted
        }
    };

string videoUploadResourceName;
using (FileStream stream = File.OpenRead(videoFilePath))
{
    ResumableUploadSession<CreateYouTubeVideoUploadRequest, CreateYouTubeVideoUploadResponse> session =
        ytService.CreateYouTubeVideoUpload();
    CreateYouTubeVideoUploadResponse response =
        session.BeginUploadAsync(createUploadRequest, stream).Result;

    videoUploadResourceName = response.ResourceName;
    Console.WriteLine($"Created YouTube video upload: {videoUploadResourceName}");
}

PHP

$youTubeVideoUploadServiceClient = $googleAdsClient->getYouTubeVideoUploadServiceClient();

$youTubeVideoUpload = new YouTubeVideoUpload([
    'video_title' => 'Test Video',
    'video_description' => 'Test Video Description',
    'video_privacy' => YouTubeVideoPrivacy::UNLISTED
]);

$createYouTubeVideoUploadRequest = CreateYouTubeVideoUploadRequest::build(
    $customerId,
    $youTubeVideoUpload
);

/** @var ResumableUpload $resumableUpload */
$resumableUpload = $youTubeVideoUploadServiceClient->createYouTubeVideoUpload(
    $createYouTubeVideoUploadRequest
);

$stream = Utils::streamFor(fopen($videoFilePath, 'rb'));
/** @var CreateYouTubeVideoUploadResponse $response */
$response = $resumableUpload->startUpload($stream);

$videoUploadResourceName = $response->getResourceName();
printf("Created YouTube video upload: '%s'%s", $videoUploadResourceName, PHP_EOL);

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,
        )
    )
    video_upload_resource_name = response.resource_name
    print(f"Created YouTube video upload: {video_upload_resource_name}")

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 "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')

Si vous utilisez REST, la section suivante explique comment gérer la mise en ligne de la vidéo.

2. Mettre en ligne la vidéo

Lorsque vous envoyez une requête REST à la CreateYouTubeVideoUpload méthode, 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 segmentées, conformément au protocole standard d'importation avec reprise de Google.

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 de mise en ligne 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')

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

Une fois la mise en ligne d'une vidéo lancée, vous pouvez récupérer son état en interrogeant la you_tube_video_upload ressource avec GAQL :

Java

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

C#

// Retrieve the metadata of the newly uploaded video.
string 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 = '{videoUploadResourceName}'";

GoogleAdsServiceClient gaService = client.GetService(
    Services.V25.GoogleAdsService);

gaService.SearchStream(customerId.ToString(), query,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow row in resp.Results)
        {
            Console.WriteLine(
                $"Video with ID {row.YouTubeVideoUpload.VideoId} was found in " +
                $"state {row.YouTubeVideoUpload.State}.");
        }
    }
);

PHP

// Retrieve the metadata of the newly uploaded video.
$query = sprintf(
    "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 = '%s'",
    $videoUploadResourceName
);

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$stream = $googleAdsServiceClient->searchStream(
    SearchGoogleAdsStreamRequest::build($customerId, $query)
);

foreach ($stream->iterateAllElements() as $googleAdsRow) {
    /** @var GoogleAdsRow $googleAdsRow */
    printf(
        "Video with ID '%s' was found in state '%s'.%s",
        $googleAdsRow->getYouTubeVideoUpload()->getVideoId(),
        YouTubeVideoUploadState::name($googleAdsRow->getYouTubeVideoUpload()->getState()),
        PHP_EOL
    );
}

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}."
    )

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'"
}
EOF

Gérer les mises en ligne

Une fois la mise en ligne d'une vidéo terminée, vous pouvez l'utiliser comme composant vidéo.

Utiliser la vidéo mise en ligne

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

Utilisez ce video_id pour créer un YoutubeVideoAsset avec MutateAssets ou associez-le directement aux types d'annonces compatibles avec les vidéos YouTube en référençant l'ID vidéo.

Mettre à jour les métadonnées

Vous pouvez mettre à jour les métadonnées d'une vidéo mise en ligne 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 les mises en ligne

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

Précédent
Composants Message à un établissement
Suivant
Rapports