تتيح لك السمة 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.
الإفصاح عن المحتوى المُنشأ بالذكاء الاصطناعي التوليدي
اعتبارًا من الإصدار 26، وبموجب لوائح مثل قانون الذكاء الاصطناعي الأوروبي، يمكن للمعلِنين الإفصاح عمّا إذا كان محتوى الفيديو الذي تم تحميله يتضمّن وسائط من إنشاء الذكاء الاصطناعي أو وسائط اصطناعية.
يحتوي الحقل video_content_metadata في YouTubeVideoUpload على
VideoContentMetadata. يمكنك ضبط الحقل المتداخل
generative_content_disclosure
باستخدام
YouTubeVideoUploadGenerativeContentDisclosure التعداد:
| القيمة | الوصف |
|---|---|
NON_GENERATIVE_CONTENT |
أفصح المعلِن عن أنّ الفيديو ليس من إنشاء الذكاء الاصطناعي. |
GENERATIVE_CONTENT |
أفصح المعلِن عن أنّ الفيديو من إنشاء الذكاء الاصطناعي. |
تحميل فيديو
لتحميل فيديو، يجب استخدام طلب متعدد الأجزاء إلى طريقة CreateYouTubeVideoUpload. يحتوي الطلب على البيانات الوصفية للتحميل وملف الفيديو نفسه.
1. بدء عملية التحميل
يمكنك إنشاء CreateYouTubeVideoUploadRequest
مع تحديد ما يلي:
customer_id: رقم تعريف عميلك على "إعلانات Google"you_tube_video_upload: كائنYouTubeVideoUploadيتضمّنvideo_titleوvideo_description، وchannel_idوvideo_privacyبشكلٍ اختياري، وvideo_content_metadataاعتبارًا من الإصدار 26.
إذا كنت تستخدم مكتبة برامج عميل، يمكنك استدعاء طريقة
CreateYouTubeVideoUpload
مع تمرير ملف الفيديو، وستتم معالجة عملية تحميل الفيديو
داخليًا.
جافا
This example is not yet available in Java; you can take a look at the other languages.
#C
YouTubeVideoUploadServiceClient ytService = client.GetService( Services.V25.YouTubeVideoUploadService); CreateYouTubeVideoUploadRequest createUploadRequest = new CreateYouTubeVideoUploadRequest() { CustomerId = customerId.ToString(), YouTubeVideoUpload = new YouTubeVideoUpload() { VideoTitle = "Test Video", VideoDescription = "Test Video Description", VideoPrivacy = YouTubeVideoPrivacy.Unlisted } }; string videoUploadResourceName; using (FileStream stream = File.OpenRead(videoFilePath)) { ResumableUploadSession<CreateYouTubeVideoUploadRequest, CreateYouTubeVideoUploadResponse> session = ytService.CreateYouTubeVideoUpload(); CreateYouTubeVideoUploadResponse response = session.BeginUploadAsync(createUploadRequest, stream).Result; videoUploadResourceName = response.ResourceName; Console.WriteLine($"Created YouTube video upload: {videoUploadResourceName}"); }
PHP
$youTubeVideoUploadServiceClient = $googleAdsClient->getYouTubeVideoUploadServiceClient(); $youTubeVideoUpload = new YouTubeVideoUpload([ 'video_title' => 'Test Video', 'video_description' => 'Test Video Description', 'video_privacy' => YouTubeVideoPrivacy::UNLISTED ]); $createYouTubeVideoUploadRequest = CreateYouTubeVideoUploadRequest::build( $customerId, $youTubeVideoUpload ); /** @var ResumableUpload $resumableUpload */ $resumableUpload = $youTubeVideoUploadServiceClient->createYouTubeVideoUpload( $createYouTubeVideoUploadRequest ); $stream = Utils::streamFor(fopen($videoFilePath, 'rb')); /** @var CreateYouTubeVideoUploadResponse $response */ $response = $resumableUpload->startUpload($stream); $videoUploadResourceName = $response->getResourceName(); printf("Created YouTube video upload: '%s'%s", $videoUploadResourceName, PHP_EOL);
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}")
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 "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')
إذا كنت تستخدم REST، يوضّح القسم التالي كيفية إدارة عملية تحميل الفيديو.
2. تحميل الفيديو
عند إرسال طلب REST إلى طريقة
CreateYouTubeVideoUpload
، تحتوي الاستجابة على عنوان URL الذي سيتم استخدامه لتحميل وحدات بايت الفيديو
في عنوان استجابة HTTP x-goog-upload-url، بالإضافة إلى بيانات وصفية أخرى مثل
الحجم المتوقّع لكل جزء من عمليات التحميل المقسّمة، وذلك وفقًا لـ Google's
بروتوكول التحميل القابل للاستئناف العادي.
يمكنك أيضًا تحديد حجم الفيديو الذي ستحمّله في البداية، عند بدء العملية، باستخدام عنوان طلب 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')
3. استرداد حالة تحميل الفيديو
بعد بدء عملية تحميل فيديو، يمكنك استرداد حالته من خلال طلب البحث عن المورد
you_tube_video_upload باستخدام GAQL:
جافا
This example is not yet available in Java; you can take a look at the other languages.
#C
// Retrieve the metadata of the newly uploaded video. string 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 = '{videoUploadResourceName}'"; GoogleAdsServiceClient gaService = client.GetService( Services.V25.GoogleAdsService); gaService.SearchStream(customerId.ToString(), query, delegate (SearchGoogleAdsStreamResponse resp) { foreach (GoogleAdsRow row in resp.Results) { Console.WriteLine( $"Video with ID {row.YouTubeVideoUpload.VideoId} was found in " + $"state {row.YouTubeVideoUpload.State}."); } } );
PHP
// Retrieve the metadata of the newly uploaded video. $query = sprintf( "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 = '%s'", $videoUploadResourceName ); $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); $stream = $googleAdsServiceClient->searchStream( SearchGoogleAdsStreamRequest::build($customerId, $query) ); foreach ($stream->iterateAllElements() as $googleAdsRow) { /** @var GoogleAdsRow $googleAdsRow */ printf( "Video with ID '%s' was found in state '%s'.%s", $googleAdsRow->getYouTubeVideoUpload()->getVideoId(), YouTubeVideoUploadState::name($googleAdsRow->getYouTubeVideoUpload()->getState()), PHP_EOL ); }
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}." )
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
إدارة التحميلات
بعد اكتمال عملية تحميل الفيديو، يمكنك استخدامه كمادة عرض فيديو.
استخدام الفيديو الذي تم تحميله
بعد أن يصل الفيديو إلى الحالة PROCESSED، يمكنك العثور على معرّف فيديو YouTube الخاص به في الحقل video_id من المورد YouTubeVideoUpload.
يمكنك استخدام video_id هذا لإنشاء YoutubeVideoAsset باستخدام
MutateAssets أو ربطه مباشرةً بأنواع الإعلانات التي تتيح استخدام فيديوهات على YouTube
من خلال الإشارة إلى معرّف الفيديو.
تعديل البيانات الوصفية
يمكنك تعديل البيانات الوصفية لفيديو تم تحميله من خلال واجهة برمجة التطبيقات هذه باستخدام طريقة UpdateYouTubeVideoUpload. لا يمكن تعديل سوى الحقول video_title وvideo_description وvideo_privacy.
إزالة عمليات التحميل
إذا كنت بحاجة إلى حذف فيديوهات تم تحميلها باستخدام Google Ads API، استخدِم طريقة RemoveYouTubeVideoUpload. سيؤدي ذلك إلى إزالة الفيديو من مكتبة مواد العرض في "إعلانات Google" ومن YouTube.