Video yükleme

YouTubeVideoUploadService Google Ads API aracılığıyla videoları doğrudan YouTube'a yüklemenize olanak tanır. Bu videolar daha sonra Maksimum Performans kampanyaları veya Talep Yaratma kampanyaları gibi çeşitli reklam türlerinde video öğeleri oluşturmak için kullanılabilir.

Bu hizmet, YouTube yükleme sürecini yöneterek video reklam oluşturma iş akışını kolaylaştırır ve videoların hesabınızla doğru şekilde ilişkilendirilmesini sağlar.

Temel kavramlar

Başlamadan önce, video yüklemelerinin nasıl yönetildiğini ve geçebilecekleri farklı durumları anlamanız önemlidir.

Kanal sahipliği

Video yüklerken YouTubeVideoUpload kaynağındaki channel_id alanını kullanarak hedef YouTube kanalını belirtebilirsiniz:

  • Reklamverene ait (marka) kanal: Reklamverene ait mevcut bir YouTube kanalının channel_id değerini girin. Bu özellik yalnızca kullanıcı kimlik doğrulama akışında desteklenir ve hizmet hesaplarıyla kullanılamaz.
  • Google tarafından yönetilen kanal: channel_id atlanırsa video, Google Ads hesabıyla ilişkili, Google tarafından yönetilen bir YouTube kanalına yüklenir.

Yükleme durumları

YouTube video yükleme işleminin yaşam döngüsü state alanı tarafından izlenir. YouTubeVideoUploadState enum'u aşağıdaki durumları tanımlar:

Eyalet Açıklama
PENDING Video yükleniyor.
UPLOADED Video başarıyla yüklendi ve YouTube tarafından işleniyor.
PROCESSED Video başarıyla işlendi ve kullanıma hazır.
FAILED Yükleme veya işleme başarısız oldu ve tamamlanamıyor.
REJECTED Video, doğrulama veya politika nedenleriyle reddedildi.
UNAVAILABLE Video durumu kullanılamıyor. Video, YouTube'dan kaldırılmış olabilir.

Gizlilik ayarları

video_privacy alanı, yüklenen videoyu kimlerin görebileceğini kontrol eder. YouTubeVideoPrivacy enum'u şunları destekler:

  • PUBLIC: Video, YouTube'daki herkes tarafından izlenebilir. (Yalnızca marka kanalları için izin verilir).
  • UNLISTED: Video aranamaz ancak bağlantıya sahip olan herkes tarafından görüntülenebilir. Bu, Google tarafından yönetilen kanallar için varsayılan ve tek seçenektir.

Yapay zekayla üretilmiş içerik açıklaması

26. sürümden itibaren, AB Yapay Zeka Yasası gibi düzenlemeler uyarınca reklamverenler, yüklenen video içeriğinin yapay zekayla üretilmiş veya sentetik medya içerip içermediğini açıklayabilir.

YouTubeVideoUpload içindeki video_content_metadata alanı VideoContentMetadata içeriyor. YouTubeVideoUploadGenerativeContentDisclosure enum'unu kullanarak iç içe yerleştirilmiş generative_content_disclosure alanını ayarlayın:

Değer Açıklama
NON_GENERATIVE_CONTENT Reklamveren, videonun yapay zeka tarafından üretilmediğini belirtti.
GENERATIVE_CONTENT Reklamveren, videonun yapay zekayla üretildiğini belirtti.

Video yükleme

Video yüklemek için CreateYouTubeVideoUpload yöntemine çok parçalı bir istek göndermeniz gerekir. İstek, hem yüklemenin meta verilerini hem de video dosyasını içerir.

1. Yükleme işlemini başlatma

Aşağıdakileri belirterek bir CreateYouTubeVideoUploadRequest oluşturun:

  • customer_id: Google Ads müşteri kimliğiniz.
  • you_tube_video_upload: video_title, video_description ve isteğe bağlı olarak channel_id, video_privacy ve 26. sürümden itibaren video_content_metadata içeren bir YouTubeVideoUpload nesnesi.

İstemci kitaplığı kullanıyorsanız video dosyanızı ileterek CreateYouTubeVideoUpload yöntemini çağırın. Video yükleme işlemi dahili olarak gerçekleştirilir.

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

REST kullanıyorsanız video yükleme işlemini nasıl yöneteceğiniz aşağıdaki bölümde açıklanmıştır.

2. Videoyu yükleyin.

CreateYouTubeVideoUpload yöntemine bir REST isteği gönderdiğinizde, yanıtta x-goog-upload-url HTTP yanıt başlığında video baytlarını yüklemek için kullanılacak URL'nin yanı sıra Google'ın standart devam ettirilebilir yükleme protokolüne uygun olarak parçalı yüklemeler için her parçanın beklenen boyutu gibi diğer meta veriler de yer alır.

Ayrıca, işlemi başlatırken x-goog-upload-header-content-length HTTP istek üstbilgisiyle yükleyeceğiniz videonun boyutunu da başlangıçta belirtebilirsiniz.

Video yükleme protokolünde kullanılan HTTP üstbilgilerinin tam açıklaması için aşağıdaki kod örneğine bakın:

# 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. Video yükleme durumunu alma

Video yükleme işlemini başlattıktan sonra GAQL ile you_tube_video_upload kaynağını sorgulayarak videonun durumunu alabilirsiniz:

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
      

Yüklemeleri yönet

Yükleme işlemi tamamlandıktan sonra videoyu video öğesi olarak kullanabilirsiniz.

Yüklenen videoyu kullanma

Bir video PROCESSED durumuna ulaştıktan sonra YouTube video kimliğini YouTubeVideoUpload kaynağının video_id alanında bulabilirsiniz.

Video kimliğine referans vererek MutateAssets ile YoutubeVideoAsset oluşturmak veya YouTube videolarını destekleyen reklam türlerine doğrudan bağlamak için bu video_id kullanın.

Meta veriyi güncelle

Bu API aracılığıyla yüklenen bir videonun meta verilerini UpdateYouTubeVideoUpload yöntemini kullanarak güncelleyebilirsiniz. Yalnızca video_title, video_description ve video_privacy alanları güncellenebilir.

Yüklemeleri kaldırma

Google Ads API ile yüklenen videoları silmeniz gerekiyorsa RemoveYouTubeVideoUpload yöntemini kullanın. Bu işlem, videoyu hem Google Ads öğe kitaplığından hem de YouTube'dan kaldırır.