Upload video

YouTubeVideoUploadService memungkinkan Anda mengupload video langsung ke YouTube melalui Google Ads API. Video ini kemudian dapat digunakan sebagai aset dalam berbagai jenis iklan, seperti kampanye Performa Maksimal atau kampanye Peningkat Permintaan.

Layanan ini menyederhanakan alur kerja pembuatan iklan video dengan menangani proses upload YouTube, memastikan bahwa video dikaitkan dengan benar ke akun Anda.

Konsep utama

Sebelum memulai, Anda harus memahami cara pengelolaan upload video dan berbagai status yang dapat dilalui video.

Kepemilikan channel

Saat mengupload video, Anda dapat menentukan channel YouTube tujuan menggunakan kolom channel_id di resource YouTubeVideoUpload:

  • Channel milik pengiklan (brand): Berikan channel_id channel YouTube milik pengiklan. Mengupload ke channel brand memungkinkan kontrol yang lebih besar atas privasi dan visibilitas video.
  • Channel yang dikelola Google: Jika channel_id tidak ada, video akan diupload ke channel YouTube yang dikelola Google dan terkait dengan akun Google Ads.

Status upload

Siklus proses upload video YouTube dilacak oleh kolom state. Enum YouTubeVideoUploadState menentukan status berikut:

Negara Bagian Deskripsi
PENDING Video sedang diupload.
UPLOADED Video telah berhasil diupload dan sedang diproses oleh YouTube.
PROCESSED Video telah berhasil diproses dan siap digunakan.
FAILED Upload atau pemrosesan gagal dan tidak dapat diselesaikan.
REJECTED Video ditolak karena alasan validasi atau kebijakan.
UNAVAILABLE Status video tidak tersedia; video mungkin telah dihapus dari YouTube.

Setelan privasi

Kolom video_privacy mengontrol siapa yang dapat melihat video yang diupload. Enum YouTubeVideoPrivacy mendukung:

  • PUBLIC: Video tersedia untuk siapa saja di YouTube. (Hanya diizinkan untuk channel merek).
  • UNLISTED: Video tidak dapat ditelusuri, tetapi dapat ditonton oleh siapa saja yang memiliki link-nya. Ini adalah opsi default dan satu-satunya untuk channel yang dikelola Google.

Upload video

Untuk mengupload video, Anda harus menggunakan permintaan multi-bagian ke metode CreateYouTubeVideoUpload. Permintaan ini berisi metadata untuk upload dan file video itu sendiri.

1. Mulai upload

Buat CreateYouTubeVideoUploadRequest yang menentukan:

  • customer_id: ID pelanggan Google Ads Anda.
  • you_tube_video_upload: Objek YouTubeVideoUpload dengan video_title, video_description, dan secara opsional channel_id dan video_privacy.

Jika Anda menggunakan library klien, panggil metode CreateYouTubeVideoUpload dengan meneruskan file video Anda, dan upload video akan ditangani secara internal.

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

Jika Anda menggunakan REST, bagian berikut menjelaskan cara mengelola upload video.

2. Upload video

Saat Anda mengirim permintaan REST ke metode CreateYouTubeVideoUpload, respons akan berisi URL yang akan digunakan untuk mengupload byte video di header respons HTTP x-goog-upload-url, beserta metadata lain seperti ukuran setiap chunk yang diharapkan untuk upload ber-chunk.

Anda juga dapat menyatakan ukuran video yang akan diupload pada awalnya, saat memulai proses, dengan header permintaan HTTP x-goog-upload-header-content-length.

Untuk mengetahui deskripsi lengkap header HTTP yang digunakan dalam protokol upload video, lihat contoh kode berikut:

# 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. Mengambil status upload video

Setelah memulai upload video, Anda dapat mengambil statusnya dengan membuat kueri resource you_tube_video_upload dengan 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'"
}
EOF
upload_video.sh

Kelola upload

Setelah upload video selesai, Anda dapat menggunakannya sebagai aset video.

Menggunakan video yang diupload

Setelah video mencapai status PROCESSED, Anda dapat menemukan ID video YouTube-nya di kolom video_id pada resource YouTubeVideoUpload.

Gunakan video_id ini untuk membuat VideoAsset atau menautkannya langsung ke jenis iklan yang mendukung video YouTube dengan mereferensikan ID video.

Update metadata

Anda dapat memperbarui metadata video yang diupload melalui API ini menggunakan metode UpdateYouTubeVideoUpload. Hanya kolom video_title, video_description, dan video_privacy yang dapat diperbarui.

Menghapus hasil upload

Jika Anda perlu menghapus video yang diupload dengan Google Ads API, gunakan metode RemoveYouTubeVideoUpload. Tindakan ini akan menghapus video dari daftar aset Google Ads dan YouTube.

Sebelumnya
Aset pesan bisnis
Berikutnya
Pelaporan