2월 26일 오전 10시(EST)에 Google 광고 및 측정 커뮤니티 서버의 Discord와 YouTube에서 라이브로 참여하세요. Google Ads API v23.1에 추가된 새로운 기능을 살펴봅니다.

동영상 업로드

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

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

주요 개념

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

채널 소유권

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

광고주 소유 (브랜드) 채널: 광고주가 소유한 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 열거형은 다음을 지원합니다.

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,
        )
    )
    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 응답 헤더에 동영상 바이트를 업로드하는 데 사용되는 URL과 청크 업로드의 각 청크 예상 크기와 같은 기타 메타데이터가 포함됩니다.

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'"
}
EOFupload_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에서 동영상이 삭제됩니다.

비즈니스 메시지 확장 소재

보고

동영상 업로드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

주요 개념

채널 소유권

업로드 상태

개인정보 보호 설정

동영상 업로드

1. 업로드 시작

자바

C#

PHP

Python

Ruby

Perl

curl

2. 동영상 업로드

3. 동영상 업로드 상태 가져오기

자바

C#

PHP

Python

Ruby

Perl

curl

업로드 관리

업로드된 동영상 사용

메타데이터 업데이트

업로드 삭제

동영상 업로드