動画をアップロード

YouTubeVideoUploadService を使用すると、Google Ads API を介して YouTube に直接動画をアップロードできます。これらの動画は、P-MAX キャンペーンやデマンドジェネレーションキャンペーンなど、さまざまな広告タイプで動画アセットを作成するために使用できます。

このサービスは、YouTube へのアップロードプロセスを処理することで動画広告の作成ワークフローを効率化し、動画がアカウントに正しく関連付けられるようにします。

主なコンセプト

始める前に、動画のアップロードがどのように管理されるか、どのような状態になる可能性があるかを理解しておくことが重要です。

チャンネルの所有権

動画をアップロードする際に、宛先の YouTube チャンネルを指定できます。 channel_id フィールドを YouTubeVideoUpload リソースで使用します。

広告主が所有する（ブランド）チャンネル: 広告主が所有する既存の YouTube チャンネルの channel_id を指定します。これはユーザー認証フローでのみサポートされており、サービスアカウントでは使用できません。
Google が管理するチャンネル: channel_id を省略すると、動画は Google 広告アカウントに関連付けられた 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 広告のお客様 ID。
you_tube_video_upload: video_title、video_description、必要に応じて channel_id と video_privacy を含む YouTubeVideoUpload オブジェクト。

クライアントライブラリを使用している場合は、 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,
        )
    )
    video_upload_resource_name = response.resource_name
    print(f"Created YouTube video upload: {video_upload_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 メソッドに送信すると、レスポンスには、動画バイトのアップロードに使用する URL と、 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'"
}
EOFupload_video.sh

アップロードを管理

動画のアップロードが完了したら、動画アセットとして使用できます。

アップロードした動画を使用する

動画が PROCESSED 状態になると、YouTubeVideoUpload リソースの video_id フィールドで YouTube 動画 ID を確認できます。

この video_id を使用して、YoutubeVideoAsset を MutateAssets で作成するか、動画 ID を参照して YouTube 動画をサポートする広告タイプに直接リンクします。

メタデータを更新

この API を介してアップロードされた動画のメタデータは、UpdateYouTubeVideoUpload メソッドを使用して更新できます。更新できるのは、video_title、video_description、video_privacy フィールドのみです。

アップロードを削除

Google Ads API を使用してアップロードした動画を削除する必要がある場合は、RemoveYouTubeVideoUpload メソッドを使用します。これにより、動画は Google 広告のアセットライブラリと YouTube の両方から削除されます。

ビジネスメッセージアセット

レポート

動画をアップロード コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

主なコンセプト

チャンネルの所有権

アップロードの状態

プライバシー設定

動画をアップロード

1. アップロードを開始する

Java

C#

PHP

Python

Ruby

Perl

curl

2. 動画をアップロードする

3. 動画のアップロード状態を取得する

Java

C#

PHP

Python

Ruby

Perl

curl

アップロードを管理

アップロードした動画を使用する

メタデータを更新

アップロードを削除

動画をアップロード