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

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 از یک پروتکل بارگذاری ازسرگیری‌پذیر دو مرحله‌ای استفاده می‌کند:

  1. شروع جلسه بارگذاری: یک درخواست اولیه POST به نقطه پایانی بارگذاری CreateYouTubeVideoUpload (/upload/v26/customers/{customer_id}/youTubeVideoUploads:create) با x-goog-upload-command: start (و به صورت اختیاری x-goog-upload-header-content-length برای اعلام اندازه فایل) ارسال کنید. پاسخ نشانی وب جلسه بارگذاری را در سرایند پاسخ HTTP x-goog-upload-url، همراه با فراداده‌هایی مانند اندازه تکه موردانتظار برمی‌گرداند.
  2. جاری‌سازی و نهایی‌سازی بایت‌های ویدیو: بار داده ویدیو دودویی را به نقطه پایانی 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}) را به پویش‌ها یا آگهی‌هایتان پیوند دهید:

  1. با انتقال 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"
            }
          }
        }
      ]
    }
    
  2. پیوند دادن 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"
                  }
                }
              }
            }
          }
        ]
      }
      
  3. پُرسمان دارایی‌های 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 برمی‌دارد.