YouTubeVideoUploadService
به شما امکان میدهد ویدیوها را مستقیماً ازطریق Google Ads API در YouTube بارگذاری کنید. سپس میتوان از این ویدیوها برای ایجاد داراییهای ویدیویی در انواع مختلف آگهی، مانند پویشهای «عملکرد بیشینه» یا پویشهای «تولید تقاضا» استفاده کرد.
این سرویس با مدیریت فرایند بارگذاری YouTube، گردش کار ایجاد آگهیهای ویدیویی را ساده میکند و اطمینان میدهد که ویدیوها بهدرستی با حساب شما مرتبط شدهاند.
مفاهیم کلیدی
قبلاز شروع، مهم است که بدانید بارگذاریهای ویدیو چگونه مدیریت میشوند و چه حالتهای مختلفی را میتوانند طی کنند.
گردش کار سرتاسر
بارگذاری فایل ویدیویی و ارائه آن در آگهی نیازمند چهار مرحله متوالی است:
| مرحله | سرویس و روش | خلاصه |
|---|---|---|
| ۱. آغاز و بارگذاری بایتهای ویدیو | CreateYouTubeVideoUpload در YouTubeVideoUploadService |
فراداده ویدیو و فایل دودویی را برای ایجاد منبع YouTubeVideoUpload (customers/{customer_id}/youTubeVideoUploads/{video_upload_id}) بارگذاری کنید. |
| ۲. وضعیت پردازش نظرسنجی | SearchStream در GoogleAdsService |
پرسوجو you_tube_video_upload تا state = 'PROCESSED' و video_id ۱۱ نویسهای YouTube پر شده است. |
| ۳. ایجاد یک دارایی ویدیویی قابل استفاده مجدد | MutateAssets در AssetService |
YoutubeVideoAsset (youtube_video_id = video_id) ایجاد کنید تا نام منبع دارایی (customers/{customer_id}/assets/{asset_id}) دریافت کنید. |
| ۴. پیوند دادن دارایی به پویشها یا آگهیها | MutateAssetGroupAssets در AssetGroupAssetService، یا MutateAdGroupAds در AdGroupAdService |
دارایی را به «عملکرد بیشینه» AssetGroupAsset (field_type = YOUTUBE_VIDEO) یا «تولید تقاضا» DemandGenVideoResponsiveAdInfo (videos[].asset) پیوند دهید. |
مالکیت کانال
وقتی ویدیویی را بارگذاری میکنید، میتوانید کانال YouTube مقصد را بااستفاده از
فیلد channel_id در منبع YouTubeVideoUpload
مشخص کنید:
- کانال تحت مالکیت تبلیغکننده (نمانام):
channel_idکانال YouTube موجود تحت مالکیت تبلیغکننده را ارائه دهید. این فقط با جریان اصالتسنجی کاربر پشتیبانی میشود؛ نمیتوان از آن با حسابهای سرویس استفاده کرد. - کانال مدیریتشده توسط Google: اگر
channel_idحذف شود، ویدیو در کانال YouTube مدیریتشده توسط Google منسوب به حساب Google Ads بارگذاری میشود.
وضعیتهای بارگذاری
چرخه حیات بارگذاری ویدیو YouTube توسط فیلد state ردیابی میشود.
YouTubeVideoUploadState
enum حالتهای زیر را تعریف میکند:
| ایالت | شرح |
|---|---|
PENDING |
ویدیو درحال بارگذاری است. |
UPLOADED |
ویدیو با موفقیت بارگذاری شده است و YouTube درحال پردازش آن است. |
PROCESSED |
ویدیو با موفقیت پردازش شده و آماده استفاده است. |
FAILED |
بارگذاری یا پردازش ناموفق بود و تکمیل نمیشود. |
REJECTED |
ویدیو بهدلیل دلایل اعتبارسنجی یا خطمشی رد شد. |
UNAVAILABLE |
وضعیت ویدیو دردسترس نیست؛ ممکن است از YouTube برداشته شده باشد. |
تنظیمات حریم خصوصی
فیلد video_privacy کنترل میکند که چه کسی میتواند ویدیو بارگذاریشده را ببیند. این
YouTubeVideoPrivacy
enum از موارد زیر پشتیبانی میکند:
PUBLIC: ویدیو برای همه در YouTube دردسترس است. (فقط برای کانالهای نمانام مجاز است).UNLISTED: ویدیو قابل جستجو نیست اما هرکسی که پیوند را داشته باشد میتواند آن را ببیند. این گزینه پیشفرض و تنها گزینه برای کانالهای تحت مدیریت Google است.
شفافسازی محتوای زایا
از نسخه ۲۶، طبق مقرراتی مانند «قانون هوش مصنوعی اتحادیه اروپا»، تبلیغکنندگان میتوانند شفافسازی کنند که آیا محتوای ویدیویی بارگذاریشده حاوی رسانه مصنوعی یا تولیدشده با هوش مصنوعی است یا نه.
فیلد video_content_metadata در YouTubeVideoUpload حاوی
VideoContentMetadata است. فیلد تودرتوی
generative_content_disclosure آن را بااستفاده از
YouTubeVideoUploadGenerativeContentDisclosure
enum تنظیم کنید:
| مقدار | شرح |
|---|---|
NON_GENERATIVE_CONTENT |
آگهیدهنده اعلام کرده است که ویدیو با هوش مصنوعی تولید نشده است. |
GENERATIVE_CONTENT |
تبلیغکننده ویدیو را بهعنوان تولیدشده با هوش مصنوعی اعلام کرده است. |
بارگذاری ویدیو
برای بارگذاری ویدیو، باید از درخواست چندبخشی برای روش
CreateYouTubeVideoUpload استفاده کنید. درخواست شامل هر دو فراداده برای
بارگذاری و فایل ویدیو است.
۱. شروع بارگذاری
CreateYouTubeVideoUploadRequest را با فیلدهای زیر بسازید:
| فیلد | الزام | شرح و محدودیتها |
|---|---|---|
customer_id |
الزامی | شناسه مشتری Google Ads دهرقمی (بدون خط تیره). |
you_tube_video_upload.video_title |
الزامی (INPUT_ONLY، IMMUTABLE) |
عنوان ویدیو بارگذاریشده در YouTube (حداکثر ۱۰۰ نویسه؛ نمیتواند حاوی < یا > باشد). |
you_tube_video_upload.video_description |
اختیاری (INPUT_ONLY، IMMUTABLE) |
شرح ویدیو در YouTube (حداکثر ۵٬۰۰۰ نویسه؛ نمیتواند حاوی < یا > باشد). |
you_tube_video_upload.channel_id |
اختیاری (IMMUTABLE) |
شناسه ۲۴ نویسهای کانال YouTube مقصد (که با UC شروع میشود) برای کانال نمانام تحت مالکیت آگهیدهنده. اگر حذف شود، در کانال تحت مدیریت Google بارگذاری میشود. |
you_tube_video_upload.video_privacy |
اختیاری (در کانالهای نمانام قابل تغییر است) | تنظیم YouTubeVideoPrivacy (UNLISTED پیشفرض، یا PUBLIC برای کانالهای نمانام متعلق به تبلیغکننده). |
you_tube_video_upload.video_content_metadata |
اختیاری (INPUT_ONLY، IMMUTABLE) |
از نسخه ۲۶ دردسترس است: VideoContentMetadata با generative_content_disclosure تنظیمشده روی مقدار YouTubeVideoUploadGenerativeContentDisclosure (NON_GENERATIVE_CONTENT یا GENERATIVE_CONTENT). |
اگر از کتابخانه مشتری استفاده میکنید، روش
CreateYouTubeVideoUpload
را فراخوانی کنید، فایل ویدیویی خود را ارسال کنید، و بارگذاری ویدیو بهصورت داخلی انجام خواهد شد.
جاوا
This example is not yet available in Java; you can take a look at the other languages.
C#
YouTubeVideoUploadServiceClient ytService = client.GetService( Services.V26.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.
پرل
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 "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 استفاده میکنید، بخش زیر نحوه مدیریت بارگذاری ویدیو را توضیح میدهد.
۲. بارگذاری ویدیو
هنگام بارگذاری با REST، CreateYouTubeVideoUpload از یک
پروتکل بارگذاری ازسرگیریپذیر دو مرحلهای استفاده میکند:
- شروع جلسه بارگذاری: یک درخواست اولیه
POSTبه نقطه پایانی بارگذاریCreateYouTubeVideoUpload(/upload/v26/customers/{customer_id}/youTubeVideoUploads:create) باx-goog-upload-command: start(و به صورت اختیاریx-goog-upload-header-content-lengthبرای اعلام اندازه فایل) ارسال کنید. پاسخ نشانی وب جلسه بارگذاری را در سرایند پاسخ HTTPx-goog-upload-url، همراه با فرادادههایی مانند اندازه تکه موردانتظار برمیگرداند. - جاریسازی و نهاییسازی بایتهای ویدیو: بار داده ویدیو دودویی را به
نقطه پایانی
x-goog-upload-urlباx-goog-upload-command: upload, finalizeارسال کنید. وقتی بارگذاری تمام شد، پاسخresource_nameایجادشده (customers/{customer_id}/youTubeVideoUploads/{video_upload_id}) را برمیگرداند.
برای شرح کامل سرصفحههای 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')
۳. بازیابی وضعیت بارگذاری ویدیو
پساز شروع بارگذاری ویدیو، وضعیت پردازش آن را با پُرسمان کردن فیلدهای قابلانتخاب منبع you_tube_video_upload (resource_name، video_upload_id، channel_id، video_id، state، و video_privacy) با GAQL تا زمان state = 'PROCESSED' (INPUT_ONLY فیلد در 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.V26.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.
پرل
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 استفاده کنید و نام منبع دارایی حاصل (customers/{customer_id}/assets/{asset_id}) را به پویشها یا آگهیهایتان پیوند دهید:
با انتقال
youtube_video_idبهAssetService.MutateAssets،YoutubeVideoAssetرا ایجاد کنید:POST https://googleads.googleapis.com/v26/customers/{customer_id}/assets:mutate { "operations": [ { "create": { "name": "Product Launch Video", "youtubeVideoAsset": { "youtubeVideoId": "dQw4w9WgXcQ" } } } ] }پیوند دادن
AssetبهAssetGroupیاAdGroupAd:عملکرد بیشینه: ایجاد
AssetGroupAssetبااستفاده ازAssetGroupAssetService.MutateAssetGroupAssetsباfield_typeتنظیمشده رویYOUTUBE_VIDEO:POST https://googleads.googleapis.com/v26/customers/{customer_id}/assetGroupAssets:mutate { "operations": [ { "create": { "assetGroup": "customers/{customer_id}/assetGroups/{asset_group_id}", "asset": "customers/{customer_id}/assets/{asset_id}", "fieldType": "YOUTUBE_VIDEO" } } ] }تولید تقاضا: به
customers/{customer_id}/assets/{asset_id}در فهرستvideosشیءDemandGenVideoResponsiveAdInfoهنگام فراخوانیAdGroupAdService.MutateAdGroupAdsارجاع دهید:POST https://googleads.googleapis.com/v26/customers/{customer_id}/adGroupAds:mutate { "operations": [ { "create": { "adGroup": "customers/{customer_id}/adGroups/{ad_group_id}", "status": "PAUSED", "ad": { "name": "Demand Gen Video Ad", "finalUrls": ["https://www.example.com"], "demandGenVideoResponsiveAd": { "videos": [ { "asset": "customers/{customer_id}/assets/{asset_id}" } ], "logoImages": [ { "asset": "customers/{customer_id}/assets/{logo_asset_id}" } ], "headlines": [ { "text": "Example Headline" } ], "longHeadlines": [ { "text": "Example Long Headline" } ], "descriptions": [ { "text": "Example Description" } ], "businessName": { "text": "Example Business" } } } } } ] }
پُرسمان داراییهای
YOUTUBE_VIDEOموجود بااستفاده ازGoogleAdsService.SearchStream:SELECT asset.id, asset.resource_name, asset.name, asset.type, asset.youtube_video_asset.youtube_video_id, asset.youtube_video_asset.youtube_video_title FROM asset WHERE asset.type = 'YOUTUBE_VIDEO' AND asset.youtube_video_asset.youtube_video_id = '{video_id}'
بهروزرسانی فرادادهها
میتوانید تنظیمات حریم خصوصی ویدیویی را که ازطریق این API بارگذاری شده است بااستفاده از روش UpdateYouTubeVideoUpload با update_mask
تنظیمشده روی "video_privacy" بهروز کنید. فقط فیلد video_privacy (PUBLIC یا
UNLISTED، برای ویدیوهای بارگذاریشده در کانال نمانام متعلق به تبلیغکننده) میتواند پساز ایجاد بهروز شود؛ video_title، video_description، channel_id، و
video_content_metadata تغییرناپذیر هستند.
برداشتن بارگذاریها
اگر نیاز دارید ویدیوهای بارگذاریشده با Google Ads API را حذف کنید،
customers/{customer_id}/youTubeVideoUploads/{video_upload_id} نامهای منبع
آنها را در فیلد resource_names
متد RemoveYouTubeVideoUpload بگذرانید. این کار ویدیو را هم از کتابخانه دارایی Google Ads و هم از YouTube برمیدارد.