این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

Video Creative Ingest API

Video Creative Ingest API به سیستم های تبلیغاتی شخص ثالث اجازه می دهد تا به طور فعال خلاقیت ها را در محصولات YouTube و DAI وارد کنند. این فرآیند تضمین می‌کند که وقتی یک تبلیغ از یک سرور تبلیغات غیر Google تصمیم گرفته می‌شود، خلاقیت‌هایی که برگردانده می‌شوند آماده و در دسترس هستند تا در یک جریان ویدیویی YouTube یا DAI ارائه شوند.

فرآیند جذب فعالانه خلاقیت ها از سیستم های تبلیغاتی شخص ثالث شامل دو بخش اصلی است. بخش اول به سیستم تبلیغات شخص ثالث اجازه می‌دهد تا خلاقیت‌ها را در اختیار Google قرار دهد و پیشرفت خلاقیت‌ها را هنگام ورود به زیرساخت ویدیوی Google نظارت کند. هنگامی که خلاقیت ها با موفقیت جذب شدند، شناسه ها به سیستم تبلیغات ارسال می شوند.

مرحله دوم شامل سیستم تبلیغاتی است که آن شناسه‌ها را می‌گیرد و آنها را در اسناد VAST که به خلاقیت ارسال شده ارجاع می‌دهند، با استفاده از شناسه آگهی جهانی (VAST 4.0+) یا یک برنامه افزودنی خلاقانه از نوع "UniversalAdId" اضافه می‌کند. هنگامی که یک سند VAST از سیستم تبلیغاتی در زمان تصمیم گیری در DAI یا YouTube مواجه می شود، سیستم خلاق آن شناسه ها را از VAST استخراج می کند و خلاقیت مناسب را از زیرساخت ویدیوی Google واکشی می کند تا برای پخش درج شود.

الزامات رسانه ای

رسانه خلاق ارسال شده به API باید معیارهای زیر را داشته باشد تا اطمینان حاصل شود که می‌تواند توسط سیستم با موفقیت پردازش شود.

انواع رسانه ها

انواع رسانه زیر توسط Google پذیرفته شده است. هر نوع رسانه دیگری می تواند پس از ارسال رد شود.

video/mp4
video/webm
video/quicktime
video/avi
video/mpeg
video/x-flv
flv-application/octet-stream
application/octet-stream
video/3gpp
video/ogg
audio/mp4
audio/mpeg

ویژگی های رسانه

معیارهای زیر باید توسط رسانه ارسال شده رعایت شود:

رسانه باید حداقل یک تراک صوتی یا تصویری داشته باشد.
رسانه ها باید مدت زمان معقولی داشته باشند. چیزی بیش از چند دقیقه نیست.
رسانه باید صدا یا تصویری داشته باشد که مدت زمان آن بیش از 1 ثانیه باشد.
اگر رسانه دارای صدا باشد، باید یک پیکربندی استاندارد کانال صوتی مانند صدای مونو، استریو یا صدای فراگیر داشته باشد.

خلاقیت ها را برای جذب ارسال کنید

نمودار جریان فرآیند بلع

یک سیستم تبلیغاتی شخص ثالث یک درخواست HTTP را به API ویدیوی Creative Ingest همراه با فهرستی از فایل‌های رسانه‌ای مرتبط با محتوا ارسال می‌کند.
Video Creative Ingest API خلاقیت با بالاترین کیفیت را از لیست ارائه شده انتخاب می کند و آن را از CDN دانلود می کند.
Video Creative Ingest API خلاقیت دانلود شده را در زیرساخت ویدیوی Google جذب می کند و آن را برای محصولات YouTube و DAI در دسترس قرار می دهد.
یک اعلان Pub/Sub با وضعیت خلاق به سیستم تبلیغات شخص ثالث بازگردانده می شود. این اعلان نشان می دهد که آیا برای YouTube و DAI با موفقیت بارگیری شده است یا خیر. اگر بارگیری خلاقیت منجر به شکست شود، اعلان علت خرابی را نشان می دهد.

هنگام ارسال خلاقیت، این دستورالعمل ها را دنبال کنید.

احراز هویت

باید با استفاده از حساب سرویس Google Cloud به API دسترسی داشته باشید. در زمان ادغام، اطلاعات حساب باید به Google ارائه شود تا مجوز مناسب را دریافت کند.

هنگامی که اطلاعات حساب از طریق creativeingestion@google.com به Google ارائه شد، به نقاط پایانی API و موضوعات Cloud PubSub که برای انتشار اعلان‌ها استفاده می‌شوند، دسترسی داده می‌شود.

برای شروع فرآیند احراز هویت، مراحل زیر را دنبال کنید:

یک حساب Google Cloud ایجاد کنید.
یک پروژه با حساب برای ارسال درخواست به DAI API راه اندازی کنید.
در داخل پروژه، به تب IAM & Admin در سمت چپ بروید و یک حساب سرویس جدید ایجاد کنید. درخواست ها با استفاده از حساب سرویس ارسال می شوند.
PubSub API را فعال کنید و یک موضوع منحصر به فرد اعلان شریک ایجاد کنید که API همه اعلان‌های موفقیت و عدم موفقیت دریافت را برای آن منتشر می‌کند.
اگر خط‌مشی سازمان محدودیت دامنه دارید، باید شناسه مشتری Google را به فهرست مشتریان مجاز اضافه کنید. برای دریافت شناسه با creativeingestion@google.com تماس بگیرید. پس از انجام این کار، می‌توانید اصول (حساب ربات ما) را از فهرست‌های مشتریان مجاز (شناسه مشتری API) به خط‌مشی‌های IAM (PubSub Publisher) اضافه کنید.
video-creative-library-discovery@system.gserviceaccount.com به عنوان PubSub Publisher به موضوع اضافه کنید.
برای ثبت این اطلاعات در API، آدرس ایمیل حساب سرویس و موضوع PubSub creativeingestion@google.com ارائه دهید.
پس از افزودن حساب به عنوان مصرف کننده سرویس ، API DAI را فعال کنید.
برای تنظیم اعتبار خود برای دسترسی به API:
- بارگیری اطلاعات کاربری از حساب سرویس: روی حساب سرویس در بخش حساب‌های سرویس در برگه IAM & Admin کلیک کنید، روی ایجاد کلید کلیک کنید و اعتبارنامه‌ها را ذخیره کنید.
- تماس گیرنده API خود را احراز هویت کنید . GOOGLE_APPLICATION_CREDENTIALS روی مسیر فایل JSON تنظیم کنید. نمونه‌های کد برای احراز هویت کلاینت‌های gRPC در زبان‌های رایج را ببینید.

بلع خلاقانه

هر بار که یک خلاقیت جدید در سیستم تبلیغات شریک موجود است، خلاقیت باید توسط سیستم شریک به Creative Ingest API ارسال شود.

وقتی خلاقیت‌های جدید برای بارگیری در زیرساخت ویدیو به Google ارسال می‌شوند، همان داده‌های خلاقانه‌ای که در سند VAST ایجاد شده توسط سیستم تبلیغاتی گنجانده شده است، باید ارائه شوند. این تضمین می‌کند که رفتار ورود فعالانه خلاقیت‌ها به Google همان رفتار بارگیری خلاقیت‌ها را در زمانی که برای اولین بار در پاسخ آگهی کشف می‌شوند، دارد.

هر خلاقیت ارسالی یک عملیات جذب طولانی مدت در سرور ایجاد می کند که وضعیت آن قابل پرس و جو است. هنگامی که عملیات با موفقیت کامل شد، منجر به یک منبع خلاق در سیستم می شود. پاسخ به ارسال یک خلاقیت حاوی شناسه عملیاتی است که از درخواست حاصل شده است. شناسه عملیات به‌دست‌آمده در اعلان‌های Cloud PubSub گنجانده می‌شود که پس از تکمیل عملیات ارسال می‌شوند تا به خلاقیت اصلی ارسال شده نگاشت شوند. شناسه عملیات همچنین می تواند برای بررسی پیشرفت عملیات در هر زمان مورد استفاده قرار گیرد.

درخواست های خلاقانه

داده ها به عنوان بافرهای پروتکل یا به عنوان اشیاء JSON به API ارسال می شوند. بافرهای پروتکل که با استفاده از gRPC ارسال می‌شوند، توصیه می‌شوند، زیرا برای مصرف اعلان‌های PubSub ضروری هستند، و حذف JSON عوارضی را به دلیل فیلدهای google.protobuf.Any در پاسخ اضافه کرده است.

پاسخ های خلاقانه

در صورت موفقیت، سرور بسته به نوع درخواست، پاسخ بافر پروتکل یا پاسخ JSON را برمی‌گرداند. پاسخ شامل نام عملیات ورودی تازه ایجاد شده و جزئیات عملیات است.

پس از ارسال اولیه، ممکن است برخی از ابرداده های مرتبط با عملیات خالی باشد و نتیجه ممکن است وجود نداشته باشد. پس از تکمیل عملیات، نتیجه با منبع Creative (یا یک خطا) پر می شود و ابرداده حاوی اطلاعاتی در مورد وضعیت دریافت است.

توجه داشته باشید که ابرداده باید از یک پروتو Any به پروتو CreateCreativeOperationMetadata جدا شود و پاسخ (در صورت وجود) باید به پروتو Creative باز شود.

کتابخانه مشتری برای دسترسی به API

برای ادغام با API مراحل زیر را دنبال کنید:

وابستگی های بافر پروتکل را دانلود کنید و کل پوشه google را به دایرکتوری src خود منتقل کنید. در صورت استفاده از Google Cloud App Engine، می توان از این کار صرفنظر کرد.
با استفاده از افزونه protoc کد gRPC را از فایل proto تولید کنید و کد تولید شده را در دایرکتوری مربوطه قرار دهید.
یک فایل پروتوی جدید برای پروتوی بازگردانده شده در اعلان PubSub ایجاد کنید. مرحله قبل را برای تولید کد از پروتو تکرار کنید.
از gRPC برای درخواست به API استفاده کنید:
1. اعتبار پیش فرض را با دامنه های زیر دریافت کنید:
https://www.googleapis.com/auth/video-ads ،
https://www.googleapis.com/auth/pubsub
1. درخواست را به Creative Ingest ارسال کنید.
- با استفاده از اطلاعات کاربری پیش فرض به dai.googleapis.com:443 متصل شوید.
- با استفاده از کد تولید شده توسط gRPC، یک خرد مشتری برای سرویس Creative Ingest ایجاد کنید.
- با استفاده از خرد مشتری، CreateCreative فراخوانی کنید.
در صورت تمایل، با استفاده از کد gRPC عملیات طولانی مدت - که در فهرست راهنمای googleapis دانلود شده در مرحله 2 وجود دارد - یک خرد برای سرویس عملیات ایجاد کنید که می تواند برای دریافت وضعیت یک عملیات معین ( GetOperation ) استفاده شود.
PubSub را برای اطلاعیه ها بررسی کنید:
1. از کتابخانه سرویس گیرنده PubSub یا gRPC برای اتصال به سرویس PubSub و نظرسنجی برای اطلاعیه های PubSub منتشر شده در موضوع ارائه شده استفاده کنید.
2. پیام PubSub را از مرحله 4 در پروتو حذف کنید.
3. هر زمان که عملیات طولانی‌مدت از تماس‌های CreateCreative ، GetOperation ، یا در اعلان PubSub برگردانده می‌شود، فراداده را از google.protobuf.Any پروتو و هر پاسخی را به Creative در discovery.proto به CreateCreativeOperationMetadata در discovery.proto بازگردانید.

به عنوان مثال کد سرویس گیرنده Go

// Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package main

import (
  dai "google.golang.org/genproto/googleapis/ads/dai/v1"
  psnotif "protos/dai"
  "google.golang.org/genproto/googleapis/longrunning"
  "cloud.google.com/go/pubsub"
  "golang.org/x/net/context"
  "google.golang.org/grpc"
  "google.golang.org/grpc/credentials"
  "google.golang.org/grpc/credentials/oauth"
  "github.com/golang/protobuf/proto"
  anypb "github.com/golang/protobuf/ptypes/any"
)

var scopes = []string{"https://www.googleapis.com/auth/video-ads", "https://www.googleapis.com/auth/pubsub"}

const (
  subID = "sub-id" // The ID for the subscription to the topic you provided us (projects/<project ID>/subscriptions/<subscription ID>)
  project = "your-project-id" // Your Google Cloud Project ID
)

func main() {
  ctx := context.Background()
  crpc, err := oauth.NewApplicationDefault(ctx, scopes...)
  if err != nil {
    // TODO: Handle error
  }

  conn, err := grpc.Dial("dai.googleapis.com:443",
    grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")),
    grpc.WithPerRPCCredentials(crpc))
  if err != nil {
    // TODO: Handle error 
  }

  apiclient := dai.NewPartnerDiscoveryServiceClient(conn)
  opclient := longrunning.NewOperationsClient(conn)

  op, err := apiclient.CreateCreative(ctx, &dai.CreateCreativeRequest{
    // TODO: Add Creative with metadata and media files.
  })
  if err != nil {
    // TODO: Handle error
  }

  pubsubClient, err := pubsub.NewClient(ctx, project)
  if err != nil {
    // TODO: Handle error
  }
  sub := pubsubClient.Subscription(subID)

  // TODO: Pull from Pub/Sub subscription to receive messages, and acknowledge them
  var msg *pubsub.Message // Assume msg = a received Pub/Sub message

  // Unmarshal the Pub/Sub message into the proto created in step 9a of guide
  var n psnotif.CreateCreativeStatus
  if err := proto.Unmarshal(msg.Data, &n); err != nil {
    // TODO: Handle error
  }
  op = n.GetDetails()
  md, err = anyToMetadata(op.GetMetadata())
  if err != nil {
    // TODO: Handle error
  }
  // TODO: Check if ingest was successful and get Google Video ID from md.GetGvRegistryId()
  // TODO: Enable serving of creative using Google Video ID in VAST document

  // Optionally check the status of an ingest request using the status endpoint
  op, err = opclient.GetOperation(ctx, &longrunning.GetOperationRequest{Name:   op.Name})
  if err != nil {
    // TODO: Handle error
  }
}

// anyToMetadata converts the metadata Any field in an Operation message to
// CreateCreativeOperationMetadata.
func anyToMetadata(msg *anypb.Any) (*dai.CreateCreativeOperationMetadata, error) {
  var md dai.CreateCreativeOperationMetadata
  return &md, proto.Unmarshal(msg.Value, &md)
}

// anyToCreative converts the response Any field in an Operation message to
// Creative.
func anyToCreative(msg *anypb.Any) (*dai.Creative, error) {
  var cr dai.Creative
  return &cr, proto.Unmarshal(msg.Value, &cr)
}

جستجوی خلاقانه در حین پخش

نمودار جریان فرآیند جستجوی خلاق

درخواست کاربر برای مشاهده محتوا در YouTube یا DAI.
YouTube / DAI یک پاسخ VAST را از یک سیستم تبلیغاتی شخص ثالث برای درج تبلیغات در محتوا دریافت می کند.
تبلیغات بازگردانده شده به خلاقیت‌هایی که قبلا جذب شده‌اند نگاشت می‌شوند. این خلاقیت‌ها برای پخش آماده هستند - از زیرساخت ویدیوی Google واکشی شده و برای کاربر پخش می‌شوند.

اسناد VAST اصلاح شده توسط شریک

هنگامی که پس از بارگیری موفقیت آمیز خلاقیت در زیرساخت ویدیوی Google، یک پاسخ VAST از سیستم تبلیغات بازگردانده می شود، سند باید حاوی ارجاعی به خلاقیت پردازش شده باشد. سند VAST باید همچنان شامل فایل های رسانه ای برای یک خلاقیت خاص باشد، اما هیچ تضمینی وجود ندارد که این فایل های رسانه ای توسط سیستم استفاده شوند.

دو راه برای ارجاع به یک خلاقیت پردازش شده در یک سند VAST وجود دارد: افزودن یک عنصر UniversalAdId جدید به سند VAST 4+ یا افزودن یک برنامه افزودنی سفارشی.

شناسه آگهی جهانی

gvRegistryID بازگردانده شده توسط Video Creative Ingest API یک شناسه عمومی جهانی است که برای شناسایی منحصربه‌فرد یک ویدیوی خلاق در چندین سیستم تبلیغاتی استفاده می‌شود. این شناسه باید به اسناد VAST 4+ سیستم تبلیغاتی اضافه شود تا زمانی که سند VAST توسط YouTube یا DAI دریافت می‌شود، شناسه می‌تواند برای نگاشت به خلاقیت ارسال شده اولیه استفاده شود.

سیستم های تبلیغاتی باید یک عنصر UniversalAdId جدید به اسناد VAST 4+ خود در زیر گره Creative اضافه کنند. ویژگی idRegistry باید روی "googlevideo" تنظیم شود و مقدار باید مقدار ارائه شده در وضعیت اعلان خلاقیت پردازش شده با موفقیت باشد.

نمونه زیر یک سند VAST 4 با شناسه آگهی جهانی جدید اضافه شده است:

<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="4.0">
  <Ad id="318230556">
    <InLine>
      <AdSystem>DCM</AdSystem>
      <AdTitle>In-Stream Video</AdTitle>
      <Creatives>
        <Creative id="79534759" AdID="" sequence="1">
          <UniversalAdId idRegistry="googlevideo">dQw4w9WgXcQ</UniversalAdId>
          <Linear>
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <Mezzanine>
                <![CDATA[https://cdn.com/media.mp4]]>
              </Mezzanine>
              <MediaFile delivery="progressive" width="640" height="360" type="video/mp4" bitrate="313">
                <![CDATA[https://cdn.com/low-res-media.mp4]]>
              </MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

Creative Extension

از آنجایی که عنصر شناسه آگهی جهانی فقط در VAST 4.0 معرفی شده است، همان داده ها به یک پسوند سفارشی نیاز دارند تا در اسناد VAST با نسخه کمتر از 4.0 نمایش داده شوند. این کار با استفاده از یک عنصر CreativeExtension در زیر عنصر Creative از مشخصات VAST انجام می شود.

برنامه افزودنی جدید معرفی شده یک برنامه افزودنی عمومی است که امکان پر کردن هر مقدار شناسه AD جهانی را می دهد. در این مورد خاص، شناسه آگهی جهانی متعلق به رجیستری googlevideo است و شناسه، شناسه ویدیوی گوگل خواهد بود.

<VAST version="3.0">
  <Ad id="318230556">
    <InLine>
      <AdSystem>My Ad Server</AdSystem>
      <AdTitle>Car Company</AdTitle>
      <Creatives>
        <Creative id="79534759" AdID="" sequence="1">
          <Linear>...</Linear>
          <CreativeExtensions>
            <CreativeExtension type="UniversalAdId">
              <UniversalAdId idRegistry="googlevideo">dQw4w9WgXcQ</UniversalAdId>
            </CreativeExtension>
          </CreativeExtensions>
        </Creative>
      </Creative>
    </InLine>
  </Ad>
</VAST>

رویکرد CreativeExtension همچنین می‌تواند در VAST 4+ استفاده شود، در صورتی که UniversalAdId قبلاً با یک شناسه برای یک رجیستری UniversalAdId دیگر پر شده باشد:

<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="4.0">
  <Ad id="318230556">
    <InLine>
      <AdSystem>DCM</AdSystem>
      <AdTitle>In-Stream Video</AdTitle>
      <Creatives>
        <Creative id="79534759" AdID="" sequence="1">
          <UniversalAdId idRegistry="other-registry">other-id</UniversalAdId>
          <Linear>
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <Mezzanine>
                <![CDATA[https://cdn.com/media.mp4]]>
              </Mezzanine>
              <MediaFile delivery="progressive" width="640" height="360" type="video/mp4" bitrate="313">
                <![CDATA[https://cdn.com/low-res-media.mp4]]>
              </MediaFile>
            </MediaFiles>
          </Linear>
          <CreativeExtensions>
            <CreativeExtension type="UniversalAdId">
              <UniversalAdId idRegistry="googlevideo">dQw4w9WgXcQ</UniversalAdId>
            </CreativeExtension>
          </CreativeExtensions>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

Video Creative Ingest API با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.