آپلود ویدیوها

YouTubeVideoUploadService به شما امکان می‌دهد ویدیوها را مستقیماً از طریق API تبلیغات گوگل (Google Ads API) در یوتیوب آپلود کنید. سپس این ویدیوها می‌توانند به عنوان دارایی در انواع مختلف تبلیغات، مانند کمپین‌های Performance Max یا Demand Gen ، استفاده شوند.

این سرویس با مدیریت فرآیند آپلود در یوتیوب، گردش کار ایجاد تبلیغات ویدیویی را ساده می‌کند و اطمینان حاصل می‌کند که ویدیوها به درستی با حساب شما مرتبط هستند.

مفاهیم کلیدی

قبل از شروع، مهم است که بدانید آپلود ویدیو چگونه مدیریت می‌شود و چه حالت‌های مختلفی را می‌تواند پشت سر بگذارد.

مالکیت کانال

هنگام آپلود یک ویدیو، می‌توانید کانال یوتیوب مقصد را با استفاده از فیلد channel_id در منبع YouTubeVideoUpload مشخص کنید:

  • کانال متعلق به تبلیغ‌کننده (برند): channel_id کانال یوتیوب متعلق به تبلیغ‌کننده را وارد کنید. آپلود در کانال یک برند، امکان کنترل بیشتر بر حریم خصوصی و میزان دیده شدن ویدیو را فراهم می‌کند.
  • کانال تحت مدیریت گوگل: اگر channel_id حذف شود، ویدیو در یک کانال یوتیوب تحت مدیریت گوگل که با حساب گوگل ادز مرتبط است، آپلود می‌شود.

حالت‌های آپلود

چرخه حیات آپلود یک ویدیوی یوتیوب توسط فیلد state ردیابی می‌شود. enum مربوط به YouTubeVideoUploadState حالت‌های زیر را تعریف می‌کند:

ایالت توضیحات
PENDING ویدیو در حال آپلود شدن است.
UPLOADED این ویدیو با موفقیت آپلود شده و توسط یوتیوب در حال پردازش است.
PROCESSED ویدیو با موفقیت پردازش شده و آماده استفاده است.
FAILED آپلود یا پردازش ناموفق بود و نمی‌تواند تکمیل شود.
REJECTED این ویدیو به دلایل مربوط به اعتبارسنجی یا سیاست‌ها رد شد.
UNAVAILABLE وضعیت ویدیو در دسترس نیست؛ ممکن است از یوتیوب حذف شده باشد.

تنظیمات حریم خصوصی

فیلد video_privacy کنترل می‌کند چه کسی می‌تواند ویدیوی آپلود شده را ببیند. enum مربوط به YouTubeVideoPrivacy از موارد زیر پشتیبانی می‌کند:

  • PUBLIC : این ویدیو برای همه در یوتیوب در دسترس است. (فقط برای کانال‌های برند مجاز است).
  • UNLISTED : ویدیو قابل جستجو نیست اما هر کسی که لینک را داشته باشد می‌تواند آن را مشاهده کند. این گزینه پیش‌فرض و تنها گزینه برای کانال‌های تحت مدیریت گوگل است.

آپلود ویدیو

برای آپلود یک ویدیو، باید از یک درخواست چند قسمتی به متد CreateYouTubeVideoUpload استفاده کنید. این درخواست شامل متادیتای آپلود و خود فایل ویدیو است.

۱. آپلود را آغاز کنید

یک CreateYouTubeVideoUploadRequest با مشخصات زیر بسازید:

  • customer_id : شناسه مشتری تبلیغات گوگل شما.
  • you_tube_video_upload : یک شیء YouTubeVideoUpload با video_title ، video_description و به صورت اختیاری channel_id و video_privacy .

اگر از یک کتابخانه کلاینت استفاده می‌کنید، متد CreateYouTubeVideoUpload را فراخوانی کنید و فایل ویدیویی خود را ارسال کنید تا آپلود ویدیو به صورت داخلی انجام شود.

جاوا 

This example is not yet available in Java; you can take a look at the other languages.

سی شارپ 

This example is not yet available in C#; you can take a look at the other languages.

پی اچ پی 

This example is not yet available in PHP; you can take a look at the other languages.

پایتون 

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

روبی 

This example is not yet available in Ruby; you can take a look at the other languages.

پرل 

This example is not yet available in Perl; you can take a look at the other languages.

حلقه زدن 

# 
# 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 استفاده می‌کنید، بخش زیر نحوه مدیریت آپلود ویدیو را شرح می‌دهد.

۲. ویدیو را آپلود کنید

وقتی یک درخواست REST به متد CreateYouTubeVideoUpload ارسال می‌کنید، پاسخ شامل URL مورد استفاده برای آپلود بایت‌های ویدیو در هدر پاسخ HTTP با کد x-goog-upload-url به همراه سایر متادیتاها مانند اندازه مورد انتظار هر قطعه برای آپلودهای قطعه قطعه شده است.

همچنین می‌توانید اندازه ویدیویی را که می‌خواهید در ابتدا آپلود کنید، هنگام شروع فرآیند، با هدر درخواست HTTP x-goog-upload-header-content-length اعلام کنید.

برای شرح کامل هدرهای 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

۳. وضعیت آپلود ویدیو را بازیابی کنید

پس از شروع آپلود ویدیو، می‌توانید وضعیت آن را با پرس‌وجو از منبع you_tube_video_upload با GAQL بازیابی کنید:

جاوا 

This example is not yet available in Java; you can take a look at the other languages.

سی شارپ 

This example is not yet available in C#; you can take a look at the other languages.

پی اچ پی 

This example is not yet available in PHP; you can take a look at the other languages.

پایتون 

# 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

روبی 

This example is not yet available in Ruby; you can take a look at the other languages.

پرل 

This example is not yet available in Perl; you can take a look at the other languages.

حلقه زدن 

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 رسید، می‌توانید شناسه ویدیوی یوتیوب آن را در فیلد video_id از منبع YouTubeVideoUpload پیدا کنید.

از این video_id برای ایجاد یک VideoAsset یا پیوند مستقیم آن به انواع تبلیغاتی که از ویدیوهای YouTube پشتیبانی می‌کنند با ارجاع به شناسه ویدیو استفاده کنید.

به‌روزرسانی فراداده

شما می‌توانید متادیتای یک ویدیوی آپلود شده از طریق این API را با استفاده از متد UpdateYouTubeVideoUpload به‌روزرسانی کنید. فقط فیلدهای video_title ، video_description و video_privacy می‌توانند به‌روزرسانی شوند.

حذف آپلودها

اگر نیاز دارید ویدیوهای آپلود شده با API گوگل ادز را حذف کنید، از متد RemoveYouTubeVideoUpload استفاده کنید. این کار ویدیو را هم از کتابخانه دارایی‌های گوگل ادز و هم از یوتیوب حذف می‌کند.

قبلی
دارایی های پیام تجاری
بعدی
گزارش نویسی