上傳影片

YouTubeVideoUploadService 可讓您透過 Google Ads API 直接將影片上傳至 YouTube。這些影片隨後可用於各種廣告類型，例如最高成效廣告活動或需求開發廣告活動。

這項服務會處理 YouTube 上傳程序，確保影片與帳戶正確建立關聯，簡化影片廣告的製作工作流程。

核心概念

開始前，請務必瞭解影片上傳作業的管理方式，以及影片可能經歷的不同狀態。

頻道擁有權

上傳影片時，您可以使用 YouTubeVideoUpload 資源中的 channel_id 欄位，指定目的地 YouTube 頻道：

  • 廣告主擁有的 (品牌) 頻道：提供廣告主擁有的 YouTube 頻道 channel_id。上傳至品牌頻道可讓你進一步控管影片的隱私權和顯示設定。
  • Google 管理的頻道：如果省略 channel_id，影片會上傳至與 Google Ads 帳戶相關聯的 Google 管理 YouTube 頻道。

上傳狀態

YouTube 影片上傳的生命週期會由 state 欄位追蹤。 YouTubeVideoUploadState 列舉會定義下列狀態：

州 說明
PENDING 正在上傳影片。
UPLOADED 影片已成功上傳，YouTube 正在處理中。
PROCESSED 影片已成功處理完畢，可以開始使用。
FAILED 上傳或處理失敗，無法完成。
REJECTED 影片因驗證或政策問題遭到拒絕。
UNAVAILABLE 影片狀態為無法使用，可能已從 YouTube 移除。

隱私權設定

video_privacy 欄位可控管誰能觀看上傳的影片。YouTubeVideoPrivacy 列舉支援：

  • PUBLIC：YouTube 上的任何人都能觀看影片。(僅限品牌頻道)。
  • UNLISTED：影片無法搜尋，但任何擁有連結的人都能觀看。這是 Google 管理的頻道預設且唯一的選項。

上傳影片

如要上傳影片，請使用多部分要求向 CreateYouTubeVideoUpload 方法提出要求。要求包含上傳的中繼資料和影片檔案本身。

1. 啟動上傳作業

建構 CreateYouTubeVideoUploadRequest，並指定：

  • customer_id：您的 Google Ads 客戶 ID。
  • you_tube_video_upload：YouTubeVideoUpload 物件，包含 video_title、video_description，以及選用的 channel_id 和 video_privacy。

如果您使用用戶端程式庫，請呼叫 CreateYouTubeVideoUpload 方法並傳遞影片檔案，系統就會在內部處理影片上傳作業。

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

如果您使用 REST，請參閱下一節，瞭解如何管理影片上傳作業。

2. 上傳影片

當您將 REST 要求傳送至 CreateYouTubeVideoUpload 方法時，回應會包含用於在 x-goog-upload-url HTTP 回應標頭中上傳影片位元組的網址，以及其他中繼資料，例如分塊上傳時每個區塊的預期大小。

您也可以在啟動程序時，使用 x-goog-upload-header-content-length HTTP 要求標頭，預先宣告要上傳的影片大小。

如要完整瞭解影片上傳通訊協定中使用的 HTTP 標頭，請參閱下列程式碼範例：

# 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. 擷取影片上傳狀態

開始上傳影片後，您可以使用 GAQL 查詢 you_tube_video_upload 資源，擷取影片上傳狀態：

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

管理上傳項目

影片上傳完成後，即可做為影片素材資源使用。

使用上傳的影片

影片達到 PROCESSED 狀態後，你可以在 YouTubeVideoUpload 資源的 video_id 欄位中找到 YouTube 影片 ID。

使用這個 video_id 建立 VideoAsset，或參照影片 ID，直接將其連結至支援 YouTube 影片的廣告類型。

更新中繼資料

如要更新透過這個 API 上傳的影片中繼資料，請使用 UpdateYouTubeVideoUpload 方法。只有 video_title、video_description 和 video_privacy 欄位可以更新。

移除上傳內容

如要刪除使用 Google Ads API 上傳的影片，請使用 RemoveYouTubeVideoUpload 方法。這會從 Google Ads 素材資源庫和 YouTube 移除影片。

上一頁
Business Message 素材資源
下一頁
報表