Upload video

YouTubeVideoUploadService memungkinkan Anda mengupload video langsung ke YouTube melalui Google Ads API. Video ini kemudian dapat digunakan untuk membuat aset video 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, sehingga memastikan video dikaitkan dengan benar ke akun Anda.

Konsep utama

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

Kepemilikan channel

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

  • Channel milik pengiklan (merek): Berikan channel_id channel YouTube yang ada dan dimiliki oleh pengiklan. Hal ini hanya didukung dengan alur autentikasi pengguna; tidak dapat digunakan dengan akun layanan.
  • Channel yang dikelola Google: Jika channel_id dihilangkan, 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:

Status Deskripsi
PENDING Video sedang diupload.
UPLOADED Video berhasil diupload dan sedang diproses oleh YouTube.
PROCESSED Video 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 dilihat oleh siapa saja yang memiliki link. Ini adalah opsi default dan satu-satunya opsi untuk channel yang dikelola Google.

Upload video

Untuk mengupload video, Anda harus menggunakan permintaan multi-bagian ke metode CreateYouTubeVideoUpload. Permintaan 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,
        )
    )
    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 "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')

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 lainnya seperti ukuran yang diharapkan dari setiap bagian untuk upload yang dibagi menjadi beberapa bagian.

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

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

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

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

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 resource YouTubeVideoUpload.

Gunakan video_id ini untuk membuat YoutubeVideoAsset dengan MutateAssets 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.

Hapus upload

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

Sebelumnya
Aset pesan bisnis
Berikutnya
Pelaporan