Tải video lên

YouTubeVideoUploadService cho phép bạn tải video trực tiếp lên YouTube thông qua Google Ads API. Sau đó, bạn có thể sử dụng những video này làm thành phần trong nhiều loại quảng cáo, chẳng hạn như chiến dịch Tối đa hoá hiệu suất hoặc chiến dịch Tạo nhu cầu.

Dịch vụ này giúp đơn giản hoá quy trình tạo quảng cáo dạng video bằng cách xử lý quy trình tải lên YouTube, đảm bảo rằng video được liên kết chính xác với tài khoản của bạn.

Khái niệm chính

Trước khi bắt đầu, bạn cần hiểu rõ cách quản lý video tải lên và các trạng thái mà video có thể trải qua.

Quyền sở hữu kênh

Khi tải video lên, bạn có thể chỉ định kênh YouTube đích bằng cách sử dụng trường channel_id trong tài nguyên YouTubeVideoUpload:

  • Kênh thuộc quyền sở hữu của nhà quảng cáo (thương hiệu): Cung cấp channel_id của một kênh YouTube thuộc quyền sở hữu của nhà quảng cáo. Khi tải lên một kênh thương hiệu, bạn sẽ có nhiều quyền kiểm soát hơn đối với quyền riêng tư và chế độ hiển thị của video.
  • Kênh do Google quản lý: Nếu bạn bỏ qua channel_id, video sẽ được tải lên một kênh YouTube do Google quản lý và được liên kết với tài khoản Google Ads.

Trạng thái tải lên

Vòng đời của một video tải lên YouTube được theo dõi bằng trường state. Liệt kê YouTubeVideoUploadState xác định các trạng thái sau:

Tiểu bang Mô tả
PENDING Video đang được tải lên.
UPLOADED Video đã được tải lên thành công và đang được YouTube xử lý.
PROCESSED Video đã được xử lý thành công và sẵn sàng để sử dụng.
FAILED Quá trình tải lên hoặc xử lý không thành công và không thể hoàn tất.
REJECTED Video bị từ chối vì lý do xác thực hoặc lý do chính sách.
UNAVAILABLE Video không có trạng thái; video đó có thể đã bị gỡ bỏ khỏi YouTube.

Chế độ cài đặt quyền riêng tư

Trường video_privacy kiểm soát những người có thể xem video đã tải lên. Enum YouTubeVideoPrivacy hỗ trợ:

  • PUBLIC: Bất kỳ ai trên YouTube cũng có thể xem video này. (Chỉ được phép đối với kênh thương hiệu).
  • UNLISTED: Video không tìm kiếm được nhưng bất kỳ ai có đường liên kết đều có thể xem. Đây là lựa chọn mặc định và duy nhất cho các kênh do Google quản lý.

Tải video lên

Để tải video lên, bạn phải sử dụng yêu cầu nhiều phần cho phương thức CreateYouTubeVideoUpload. Yêu cầu này chứa cả siêu dữ liệu cho tệp tải lên và chính tệp video.

1. Bắt đầu tải lên

Tạo một CreateYouTubeVideoUploadRequest nêu rõ:

  • customer_id: Mã khách hàng Google Ads của bạn.
  • you_tube_video_upload: Một đối tượng YouTubeVideoUpload có video_title, video_description và không bắt buộc là channel_id và video_privacy.

Nếu đang sử dụng một thư viện ứng dụng, hãy gọi phương thức CreateYouTubeVideoUpload, truyền tệp video của bạn và quá trình tải video lên sẽ được xử lý nội bộ.

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

Nếu bạn đang sử dụng REST, phần sau đây mô tả cách quản lý quá trình tải video lên.

2. Tải video lên

Khi bạn gửi yêu cầu REST đến phương thức CreateYouTubeVideoUpload, phản hồi sẽ chứa URL dùng để tải các byte video lên trong tiêu đề phản hồi HTTP x-goog-upload-url, cùng với các siêu dữ liệu khác, chẳng hạn như kích thước dự kiến của từng khối để tải lên theo khối.

Bạn cũng có thể khai báo kích thước của video mà bạn sẽ tải lên ban đầu khi bắt đầu quy trình bằng tiêu đề yêu cầu HTTP x-goog-upload-header-content-length.

Để xem nội dung mô tả đầy đủ về các tiêu đề HTTP được dùng trong giao thức tải video lên, hãy tham khảo ví dụ về mã sau:

# 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. Truy xuất trạng thái tải video lên

Sau khi bắt đầu tải video lên, bạn có thể truy xuất trạng thái của video đó bằng cách truy vấn tài nguyên you_tube_video_upload bằng 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

Quản lý mục tải lên

Sau khi tải video lên, bạn có thể sử dụng video đó làm thành phần video.

Sử dụng video đã tải lên

Sau khi video đạt đến trạng thái PROCESSED, bạn có thể tìm thấy mã video trên YouTube của video đó trong trường video_id của tài nguyên YouTubeVideoUpload.

Sử dụng video_id này để tạo VideoAsset hoặc liên kết trực tiếp với các loại quảng cáo hỗ trợ video trên YouTube bằng cách tham chiếu mã video.

Cập nhật siêu dữ liệu

Bạn có thể cập nhật siêu dữ liệu của video được tải lên thông qua API này bằng phương thức UpdateYouTubeVideoUpload. Bạn chỉ có thể cập nhật các trường video_title, video_description và video_privacy.

Xoá tệp tải lên

Nếu cần xoá video đã tải lên bằng Google Ads API, hãy sử dụng phương thức RemoveYouTubeVideoUpload. Thao tác này sẽ xoá video khỏi cả thư viện thành phần của Google Ads và YouTube.