동영상 업로드

참고: Google Ads API를 사용한 동영상 업로드는 Python 클라이언트 라이브러리 및 REST를 사용하는 경우에만 지원됩니다.

YouTubeVideoUploadService 를 사용하면 Google Ads API를 통해 YouTube에 직접 동영상을 업로드할 수 있습니다. 그런 다음 이러한 동영상을 사용하여 실적 최대화 캠페인 또는 디맨드젠 캠페인과 같은 다양한 광고 유형에서 동영상 애셋을 만들 수 있습니다.

이 서비스는 YouTube 업로드 프로세스를 처리하여 동영상이 계정에 올바르게 연결되도록 함으로써 동영상 광고를 만드는 워크플로를 간소화합니다.

주요 개념

시작하기 전에 동영상 업로드가 관리되는 방식과 동영상 업로드가 거칠 수 있는 다양한 상태를 이해하는 것이 중요합니다.

채널 소유권

동영상을 업로드할 때 대상 YouTube 채널을 사용하여 channel_id 필드를 지정할 수 있습니다. YouTubeVideoUpload 리소스:

• 광고주 소유 (브랜드) 채널: 광고주가 소유한 기존 YouTube 채널의 channel_id를 제공합니다. 이는 사용자 인증 흐름에서만 지원되며 서비스 계정에서는 사용할 수 없습니다.
• Google 관리 채널: channel_id가 생략되면 동영상은 Google Ads 계정과 연결된 Google 관리 YouTube 채널에 업로드됩니다.

업로드 상태

YouTube 동영상 업로드의 수명 주기는 state 필드에 의해 추적됩니다. YouTubeVideoUploadState enum은 다음 상태를 정의합니다.

주	설명
PENDING	동영상을 업로드하는 중입니다.
UPLOADED	동영상이 업로드되었으며 YouTube에서 처리 중입니다.
PROCESSED	동영상이 처리되었으며 사용할 준비가 되었습니다.
FAILED	업로드 또는 처리가 실패하여 완료할 수 없습니다.
REJECTED	유효성 검사 또는 정책상의 이유로 동영상이 거부되었습니다.
UNAVAILABLE	동영상 상태를 사용할 수 없습니다. YouTube에서 삭제되었을 수 있습니다.

개인정보 보호 설정

video_privacy 필드는 업로드된 동영상을 볼 수 있는 사용자를 제어합니다. YouTubeVideoPrivacy enum은 다음을 지원합니다.

• PUBLIC: YouTube의 모든 사용자가 동영상을 볼 수 있습니다. (브랜드 채널에서만 허용됩니다).
• UNLISTED: 동영상을 검색할 수는 없지만 링크가 있는 모든 사용자가 볼 수 있습니다. 이는 Google 관리 채널의 기본값이자 유일한 옵션입니다.

동영상 업로드

동영상을 업로드하려면 CreateYouTubeVideoUpload 메서드에 멀티파트 요청을 사용해야 합니다. 요청에는 업로드의 메타데이터와 동영상 파일 자체가 모두 포함됩니다.

1. 업로드 시작

다음을 지정하는 CreateYouTubeVideoUploadRequest 를 구성합니다.

• customer_id: Google Ads 고객 ID입니다.
• you_tube_video_upload: video_title, video_description, 선택적으로 channel_id 및 video_privacy가 포함된 YouTubeVideoUpload 객체입니다.

클라이언트 라이브러리를 사용하는 경우 동영상 파일을 전달하여 CreateYouTubeVideoUpload 메서드를 호출하면 동영상 업로드가 내부적으로 처리됩니다.

자바

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. 동영상 업로드

CreateYouTubeVideoUpload 메서드에 REST 요청을 보내면 응답에는 동영상 바이트를 업로드하는 데 사용할 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 리소스를 쿼리하여 상태를 가져올 수 있습니다.

자바

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를 사용하여 YoutubeVideoAsset를 MutateAssets 만들거나 동영상 ID를 참조하여 YouTube 동영상을 지원하는 광고 유형에 직접 연결합니다.

메타데이터 업데이트

UpdateYouTubeVideoUpload 메서드를 사용하여 이 API를 통해 업로드된 동영상의 메타데이터를 업데이트할 수 있습니다. video_title, video_description, video_privacy 필드만 업데이트할 수 있습니다.

업로드 삭제

Google Ads API로 업로드된 동영상을 삭제해야 하는 경우 RemoveYouTubeVideoUpload 메서드를 사용합니다. 이렇게 하면 Google Ads 애셋 라이브러리와 YouTube에서 동영상이 삭제됩니다.