تحميل مقاطع فيديو

تتيح لك YouTubeVideoUploadService تحميل الفيديوهات مباشرةً إلى YouTube من خلال Google Ads API. ويمكن بعد ذلك استخدام هذه الفيديوهات كمواد عرض في أنواع مختلفة من الإعلانات، مثل حملات الأداء الأفضل أو حملات زيادة الطلب.

تسهّل هذه الخدمة سير عمل إنشاء إعلانات الفيديو من خلال معالجة عملية التحميل على YouTube، ما يضمن ربط الفيديوهات بشكل صحيح بحسابك.

المفاهيم الرئيسية

قبل البدء، من المهم معرفة كيفية إدارة عمليات تحميل الفيديوهات والحالات المختلفة التي يمكن أن تمر بها.

ملكية القناة

عند تحميل فيديو، يمكنك تحديد قناة YouTube المقصودة باستخدام الحقل channel_id في مصدر YouTubeVideoUpload:

  • قناة يملكها المعلِن (العلامة التجارية): أدخِل channel_id لقناة على YouTube يملكها المعلِن. يتيح التحميل إلى قناة خاصة بعلامة تجارية المزيد من التحكّم في خصوصية الفيديو ومستوى ظهوره.
  • قناة تديرها Google: في حال حذف channel_id، يتم تحميل الفيديو إلى قناة على YouTube تديرها Google ومرتبطة بحساب "إعلانات Google".

حالات التحميل

يتم تتبُّع مراحل تحميل فيديو على YouTube من خلال الحقل state. يحدّد التعداد YouTubeVideoUploadState الحالات التالية:

ولاية الوصف
PENDING جارٍ تحميل الفيديو.
UPLOADED تم تحميل الفيديو بنجاح ويجري YouTube معالجته.
PROCESSED تمت معالجة الفيديو بنجاح وهو جاهز للاستخدام.
FAILED تعذّر إكمال عملية التحميل أو المعالجة.
REJECTED تم رفض الفيديو لأسباب تتعلق بالتحقّق من الصحة أو السياسة.
UNAVAILABLE حالة الفيديو غير متاحة، وقد يكون تمّت إزالته من YouTube.

إعدادات الخصوصية

يتحكّم الحقل video_privacy في تحديد المستخدمين الذين يمكنهم مشاهدة الفيديو الذي تم تحميله. يتيح التعداد YouTubeVideoPrivacy ما يلي:

  • ‫PUBLIC: الفيديو متاح لأي مستخدم على YouTube. (يُسمح بذلك فقط لقنوات العلامات التجارية).
  • ‫UNLISTED: لا يمكن البحث عن الفيديو، ولكن يمكن لأي شخص لديه الرابط مشاهدته. هذا هو الخيار التلقائي والوحيد للقنوات التي تديرها Google.

تحميل فيديو

لتحميل فيديو، يجب استخدام طلب متعدد الأجزاء إلى الطريقة CreateYouTubeVideoUpload. يحتوي الطلب على البيانات الوصفية لعملية التحميل وملف الفيديو نفسه.

1. بدء عملية التحميل

أنشئ CreateYouTubeVideoUploadRequest مع تحديد ما يلي:

  • استبدِل customer_id برقم تعريف عميلك على "إعلانات Google".
  • 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.

#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. تحميل الفيديو

عند إرسال طلب 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

3- استرداد حالة تحميل الفيديو

بعد بدء عملية تحميل فيديو، يمكنك استرداد حالته من خلال طلب البحث عن مورد you_tube_video_upload باستخدام GAQL:

جافا

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، يمكنك العثور على معرّف الفيديو على YouTube في الحقل video_id ضمن المرجع YouTubeVideoUpload.

استخدِم هذا video_id لإنشاء VideoAsset أو ربطه مباشرةً بأنواع الإعلانات التي تتوافق مع فيديوهات YouTube من خلال الإشارة إلى معرّف الفيديو.

تعديل البيانات الوصفية

يمكنك تعديل البيانات الوصفية لفيديو تم تحميله من خلال واجهة برمجة التطبيقات هذه باستخدام الطريقة UpdateYouTubeVideoUpload. يمكن تعديل الحقول video_title وvideo_description وvideo_privacy فقط.

إزالة عمليات التحميل

إذا كنت بحاجة إلى حذف فيديوهات تم تحميلها باستخدام Google Ads API، استخدِم طريقة RemoveYouTubeVideoUpload. سيؤدي ذلك إلى إزالة الفيديو من مكتبة مواد العرض في "إعلانات Google" ومن YouTube.

السابق
مواد عرض الرسائل التجارية
التالي
إعداد التقارير