上传视频

借助 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. 上传视频

当您向 CreateYouTubeVideoUpload 方法发送 REST 请求时，响应会在 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 视频的广告类型。

更新元数据

您可以使用 UpdateYouTubeVideoUpload 方法更新通过此 API 上传的视频的元数据。只能更新 video_title、video_description 和 video_privacy 字段。

移除上传内容

如果您需要删除使用 Google Ads API 上传的视频，请使用 RemoveYouTubeVideoUpload 方法。这会将视频从 Google Ads 素材资源库和 YouTube 中移除。

上一页
商家消息的素材资源
下一页
报告