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

توجه: بارگذاری ویدیو با Google Ads API فقط با کتابخانه‌های کارخواه .NET،‏ PHP، و Python و بااستفاده از REST پشتیبانی می‌شود. برای کتابخانه‌های مشتری دیگر، می‌توانید ویدیوها را مستقیماً بااستفاده از YouTube Data API v3 بارگذاری کنید و با شناسه ویدیو YouTube حاصل، YoutubeVideoAsset ایجاد کنید.

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_title و video_description در منبع YouTubeVideoUpload مشخص کنید:

• ‫video_title: الزامی. عنوان نباید بیشتر از ۱۰۰ نویسه باشد و نباید حاوی نویسه‌های نامعتبر (پرانتزهای زاویه‌دار < یا >) باشد. این عنوان فقط هنگام ایجاد بارگذاری ویدیو قابل تنظیم است و پس‌از ایجاد قابل تغییر نیست.
• video_description: اختیاری. شرح نباید بیشتر از ۵٬۰۰۰ نویسه باشد و نباید نویسه نامعتبر داشته باشد (پرانتز زاویه‌دار < یا >). فقط هنگام ایجاد بارگذاری ویدیو می‌توان آن را تنظیم کرد و پس‌از ایجاد تغییرناپذیر است.

هر دو فیلد پس‌از ایجاد تغییرناپذیر هستند. گنجاندن video_title یا video_description در ماسک به‌روزرسانی درخواست UpdateYouTubeVideoUpload با خطای FieldError.IMMUTABLE_FIELD ناموفق می‌شود.

برای اطلاعات بیشتر درباره قالب‌بندی عنوان و شرح YouTube و نویسه‌های نامعتبر، به مرکز راهنمایی YouTube مراجعه کنید.

شفاف‌سازی محتوای زایا

از نسخه ۲۶، طبق مقرراتی مانند «قانون هوش مصنوعی اتحادیه اروپا»، تبلیغ‌کنندگان می‌توانند شفاف‌سازی کنند که آیا محتوای ویدیویی بارگذاری‌شده حاوی رسانه مصنوعی یا تولیدشده با هوش مصنوعی است یا نه.

فیلد video_content_metadata در YouTubeVideoUpload حاوی VideoContentMetadata است. فیلد تودرتوی generative_content_disclosure آن را بااستفاده از YouTubeVideoUploadGenerativeContentDisclosure enum تنظیم کنید:

مقدار	شرح
NON_GENERATIVE_CONTENT	آگهی‌دهنده اعلام کرده است که ویدیو با هوش مصنوعی تولید نشده است.
GENERATIVE_CONTENT	تبلیغ‌کننده ویدیو را به‌عنوان تولیدشده با هوش مصنوعی اعلام کرده است.

توجه: video_content_metadata فقط ورودی است و فقط هنگام ایجاد بارگذاری ویدیو YouTube قابل تنظیم است. پس‌از ایجاد، تغییرناپذیر است.

بارگذاری ویدیو

برای بارگذاری ویدیو، باید از درخواست چندبخشی برای روش 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 را فراخوانی کنید، فایل ویدیویی خود را ارسال کنید، و بارگذاری ویدیو به‌صورت داخلی انجام خواهد شد.

جاوا

String videoUploadResourceName;
try (YouTubeVideoUploadServiceClient youTubeVideoUploadServiceClient =
    googleAdsClient.getLatestVersion().createYouTubeVideoUploadServiceClient()) {
  YouTubeVideoUpload youTubeVideoUpload =
      YouTubeVideoUpload.newBuilder()
          .setVideoTitle("Test Video")
          .setVideoDescription("Test Video Description")
          .setVideoPrivacy(YouTubeVideoPrivacy.UNLISTED)
          .build();

  CreateYouTubeVideoUploadRequest createUploadRequest =
      CreateYouTubeVideoUploadRequest.newBuilder()
          .setCustomerId(Long.toString(customerId))
          .setYouTubeVideoUpload(youTubeVideoUpload)
          .build();

  CreateYouTubeVideoUploadResponse response =
      youTubeVideoUploadServiceClient.createYouTubeVideoUpload(
          createUploadRequest, () -> new FileInputStream(videoFile), null);

  videoUploadResourceName = response.getResourceName();
  System.out.printf("Created YouTube video upload: %s%n", videoUploadResourceName);
}
UploadVideo.java
      

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}");
}
UploadVideo.cs
      

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);
UploadVideo.php
      

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}")
upload_video.py
      

Ruby

video_upload = client.resource.you_tube_video_upload do |v|
  v.video_title = "Test Video"
  v.video_description = "Test Video Description"
  v.video_privacy = :UNLISTED
end

upload = client.service.you_tube_video_upload.create_you_tube_video_upload(
  customer_id: customer_id,
  you_tube_video_upload: video_upload,
)

video_upload_resource_name = nil
File.open(video_file_path, "rb") do |stream|
  response = upload.start(
    stream: stream,
    content_type: "application/octet-stream",
  )
  video_upload_resource_name = response.resource_name
  puts "Created YouTube video upload: #{video_upload_resource_name}"
end
upload_video.rb
      

پرل

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')
upload_video.sh
      

اگر از 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')
upload_video.sh
      

۳. بازیابی وضعیت بارگذاری ویدیو

پس‌از شروع بارگذاری ویدیو، وضعیت پردازش آن را با پُرسمان فیلدهای قابل‌انتخاب منبع you_tube_video_upload (resource_name،‏ video_upload_id،‏ channel_id،‏ video_id،‏ state، و video_privacy) با GAQL تا state = 'PROCESSED' نظرسنجی کنید (فیلدهای INPUT_ONLY را نمی‌توان در GAQL انتخاب کرد):

جاوا

// Retrieve the metadata of the newly uploaded video.
String query =
    String.format(
        "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);

try (GoogleAdsServiceClient googleAdsServiceClient =
    googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
  SearchGoogleAdsStreamRequest request =
      SearchGoogleAdsStreamRequest.newBuilder()
          .setCustomerId(Long.toString(customerId))
          .setQuery(query)
          .build();

  ServerStream<SearchGoogleAdsStreamResponse> stream =
      googleAdsServiceClient.searchStreamCallable().call(request);

  for (SearchGoogleAdsStreamResponse response : stream) {
    for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
      YouTubeVideoUpload video = googleAdsRow.getYouTubeVideoUpload();
      System.out.printf(
          "Video with ID %s was found in state %s.%n",
          video.getVideoId(), video.getState());
    }
  }
}
UploadVideo.java
      

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}.");
        }
    }
);
UploadVideo.cs
      

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
    );
}
UploadVideo.php
      

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

# Retrieve the metadata of the newly uploaded video.
query = <<~EOQ
  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}'
EOQ

responses = client.service.google_ads.search_stream(
  customer_id: customer_id,
  query: query,
)

responses.each do |batch|
  batch.results.each do |row|
    puts "Video with ID #{row.you_tube_video_upload.video_id} was found in " \
      "state #{row.you_tube_video_upload.state}."
  end
end
upload_video.rb
      

پرل

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 برای ایجاد YoutubeVideoAsset با MutateAssets استفاده کنید و نام منبع دارایی حاصل (customers/{customer_id}/assets/{asset_id}) را به پویش‌ها یا آگهی‌هایتان پیوند دهید:

1. YoutubeVideoAsset را با ارسال youtube_video_id به AssetService.MutateAssets ایجاد کنید:

   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 تغییرناپذیر هستند. گنجاندن video_title یا video_description در ماسک به‌روزرسانی با خطای FieldError.IMMUTABLE_FIELD ناموفق می‌شود.

برداشتن بارگذاری‌ها

اگر لازم است ویدیوهای بارگذاری‌شده با Google Ads API را حذف کنید، customers/{customer_id}/youTubeVideoUploads/{video_upload_id}نام منابع آن‌ها را در فیلد resource_names روش RemoveYouTubeVideoUpload وارد کنید. با این کار، ویدیو هم از کتابخانه دارایی Google Ads و هم از YouTube برداشته می‌شود.