تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

واجهة برمجة تطبيقات أداة نقل تصاميم إعلانات الفيديو

تتيح واجهة برمجة التطبيقات Video Creative Ingest API لأنظمة الإعلانات التابعة لجهات خارجية نقل تصميمات الإعلانات إلى YouTube ومنتجات عرض الإعلانات الديناميكي (DAI) بشكل استباقي. تضمن هذه العملية أنّه عند اتخاذ قرار بشأن إعلان من خادم إعلانات غير تابع لشركة Google، تكون مواد العرض التي يتم عرضها جاهزة ومتاحة لعرضها في بث فيديو على YouTube أو بث إعلان ديناميكي أثناء عرض الفيديو.

تتضمّن عملية نقل مواد العرض بشكل استباقي من أنظمة الإعلانات التابعة لجهات خارجية جزأَين رئيسيَين. يسمح الجزء الأول لنظام الإعلان التابع لجهة خارجية بتقديم تصميمات الإعلانات إلى Google ومراقبة مستوى تقدّم تصميمات الإعلانات أثناء نقلها إلى البنية الأساسية لفيديوهات Google. بعد نقل مواد العرض بنجاح، يتمّ تمرير المعرّفات إلى نظام الإعلانات.

تتضمّن الخطوة الثانية أن يأخذ نظام الإعلان هذه المعرّفات ويُدرِجها في مستندات VAST التي تشير إلى تصميم الإعلان الذي تم إرساله، وذلك باستخدام معرّف الإعلان العالمي (VAST 4.0 والإصدارات الأحدث) أو إضافة تصميم الإعلان من النوع UniversalAdId. عند العثور على مستند VAST من نظام الإعلان في وقت اتخاذ القرار في DAI أو YouTube، يستخرج نظام المواد الإبداعية هذه المعرّفات من VAST وي retrieving يُسترجع المادة الإبداعية المناسبة من البنية الأساسية لفيديوهات Google لإدراجها لتشغيلها.

متطلبات الوسائط

يجب أن تستوفي مواد العرض الإبداعية التي يتم إرسالها إلى واجهة برمجة التطبيقات المعايير التالية لضمان أنّه يمكن للنظام معالجتها بنجاح.

أنواع الوسائط

تقبل 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

خصائص الوسائط

يجب أن تستوفي الوسائط المرسَلة المعايير التالية:

يجب أن تحتوي الوسائط على مقطع صوتي أو فيديو واحد على الأقل.
يجب أن تكون مدة الوسائط معقولة. لا تستغرق هذه العملية أكثر من بضع دقائق.
يجب أن تتضمّن الوسائط صوتًا أو فيديو تزيد مدته عن ثانية واحدة.
إذا كانت الوسائط تتضمّن صوتًا، يجب أن تتضمّن إعدادات قناة صوتية عادية، مثل الصوت الأحادي أو الاستيريو أو الصوت المحيطي.

إرسال مواد إبداعية لاستيرادها

مخطّط انسيابي لعملية نقل البيانات

يُرسِل نظام إعلان تابع لجهة خارجية طلب HTTP إلى واجهة برمجة التطبيقات Video Creative Ingest API مع قائمة بملفات الوسائط المرتبطة بتصميم الإعلان.
تختار Video Creative Ingest API تصميم الإعلان الأعلى جودة من القائمة المقدَّمة وتنزّله من شبكة توصيل المحتوى (CDN).
تعمل واجهة برمجة التطبيقات Video Creative Ingest API على نقل تصميم الإعلان الذي تم تنزيله إلى "بنية Google للفيديو"، ما يجعله متاحًا لكل من منتجات YouTube وDAI.
يتم إرسال إشعار Pub/Sub (النشر/الاشتراك) مرة أخرى إلى نظام الإعلان التابع لجهة خارجية مع حالة تصميم الإعلان. سيشير الإشعار إلى ما إذا تم تحميله بنجاح لكل من YouTube وDAI. إذا تعذّر تحميل تصميم الإعلان، سيشير الإشعار إلى سبب التعذّر.

اتّبِع هذه الإرشادات عند إرسال تصميمات الإعلانات.

المصادقة

يجب الوصول إلى واجهة برمجة التطبيقات باستخدام حساب لخدمة Google Cloud. في وقت دمج المحتوى، يجب تقديم معلومات الحساب إلى Google للحصول على الإذن المناسب.

بعد تقديم معلومات الحساب إلى Google من خلال creativeingestion@google.com، سيتم منح إذن الوصول إلى نقاط نهاية واجهة برمجة التطبيقات وموضوعات Cloud PubSub المستخدَمة لنشر الإشعارات.

لبدء عملية المصادقة، اتّبِع الخطوات التالية:

أنشئ حسابًا على Google Cloud.
إعداد مشروع باستخدام الحساب لإرسال الطلبات إلى DAI API
ضمن المشروع، انتقِل إلى علامة التبويب إدارة الهوية وإمكانية الوصول والمشرف على يمين الصفحة، وأنشئ حساب خدمة جديدًا، ويتم إرسال الطلبات باستخدام حساب الخدمة.
فعِّل PubSub API و أنشئ موضوعًا فريدًا واحدًا لإشعارات الشركاء تنشر واجهة برمجة التطبيقات عليه جميع إشعارات نجاح نقل البيانات وإخفاقها.

إذا كانت لديك سياسة تنظيم قيود النطاق سارية، عليك إضافة رقم تعريف العميل على Google إلى قائمة العملاء المسموح لهم. يُرجى التواصل مع العميل creativeingestion@google.com للحصول على رقم التعريف. بعد الانتهاء من ذلك، يمكنك إضافة عناصر التحكم (حساب الروبوت) من قوائم العملاء المسموح لهم (رقم تعريف العميل في واجهة برمجة التطبيقات) إلى سياسات إدارة الهوية وإمكانية الوصول (PubSub Publisher).

أضِف video-creative-library-discovery@system.gserviceaccount.com كمنشِر PubSub إلى الموضوع.
قدِّم creativeingestion@google.com عنوان البريد الإلكتروني لحساب الخدمة وموضوع PubSub لتسجيل هذه المعلومات في واجهة برمجة التطبيقات.
فعِّل DAI API بعد إضافة الحساب كمستهلك خدمة.
لضبط بيانات الاعتماد للوصول إلى واجهة برمجة التطبيقات:
- تنزيل بيانات الاعتماد من حساب الخدمة: انقر على حساب الخدمة في قسم حسابات الخدمة ضمن علامة التبويب إدارة الهوية وإمكانية الوصول والمشرف، ثم انقر على إنشاء مفتاح، واحفظ بيانات الاعتماد.
- مصادقة واجهة برمجة التطبيقات المُرسِل اضبط GOOGLE_APPLICATION_CREDENTIALS على مسار ملف JSON. اطّلِع على أمثلة على الرمز المبرمَج لمصادقة عملاء gRPC باللغات الشائعة.

نقل تصميمات الإعلانات

في كل مرة يتوفّر فيها تصميم إعلان جديد في نظام إعلان الشريك، يجب أن يُرسِل نظام الشريك تصميم الإعلان إلى Creative Ingest API.

عند إرسال تصميمات إعلانات جديدة إلى Google لتحميلها في بنية الفيديو، يجب تقديم بيانات تصميم الإعلان نفسها المضمّنة في مستند VAST الذي أنشأه نظام الإعلان. يضمن ذلك أنّ سلوك نقل مواد إبداعية إلى Google بشكل استباقي هو نفسه سلوك تحميل مواد إبداعية عند اكتشافها لأول مرة في ردّ إعلان.

يؤدي كلّ تصميم مُرسَل إلى إنشاء عملية نقل بيانات طويلة الأمد على الخادم يمكن الاستعلام عن حالتها. بعد اكتمال العملية بنجاح، يؤدي ذلك إلى إنشاء مورد تصميم إعلان داخل النظام. يحتوي الردّ على إرسال مادة عرض على رقم تعريف العملية الناتجة عن الطلب. يتم تضمين معرّف العملية الناتج في إشعارات Cloud PubSub التي يتم إرسالها عند اكتمال العملية لإعادة الربط بالتصميم الأصلي الذي تم إرساله. يمكن أيضًا استخدام معرّف العملية للتحقّق من مستوى تقدّم العملية في أي وقت.

طلبات المواد الإبداعية

يتم إرسال البيانات إلى واجهة برمجة التطبيقات بتنسيق Protocol Buffers أو كعناصر JSON. يُنصح باستخدام Buffers البروتوكول التي يتم إرسالها باستخدام gRPC لأنّها ضرورية لاستخدام إشعارات PubSub، ويؤدي تحويل ترميز ملف JSON إلى تنسيق عادي إلى حدوث تعقيدات إضافية بسبب حقول google.protobuf.Any في الاستجابة.

الردود الإبداعية

في حال نجاح الطلب، يعرض الخادم استجابة Protocol Buffer أو استجابة JSON، استنادًا إلى نوع الطلب. يحتوي الردّ على اسم عملية نقل بيانات الإنشاء الجديدة وتفاصيل العملية.

عند الإرسال الأوّلي، قد تكون بعض البيانات الوصفية المرتبطة بالعملية فارغة وقد لا تكون النتيجة متوفّرة. بعد اكتمال العملية، تتم تعبئة النتيجة بمورد تصميم الإعلان (أو خطأ) وتحتوي البيانات الوصفية على معلومات عن حالة نقل البيانات.

يُرجى العلم أنّه يجب تحويل البيانات الوصفية من Any proto إلىCreateCreativeOperationMetadata proto، ويجب تحويل الاستجابة (في حال توفّرها) إلىCreative proto.

مكتبة العميل للوصول إلى واجهة برمجة التطبيقات

اتّبِع الخطوات التالية للدمج مع واجهة برمجة التطبيقات:

نزِّل التبعيات المتعلقة بذاكرة التخزين المؤقت للبروتوكول وانقِل المجلد google بأكمله إلى الدليل src. يمكن تخطّي هذه الخطوة في حال استخدام Google Cloud App Engine.
استخدِم المكوّن الإضافي protoc من أجل إنشاء رمز gRPC من ملف proto ووضع الرمز الذي تم إنشاؤه في الدليل المعنيّ.
أنشئ ملف proto جديدًا لملف proto الذي تم إرجاعه في إشعار PubSub، ثم كرِّر الخطوة السابقة لإنشاء رمز من ملف proto.
استخدِم gRPC لتقديم طلبات إلى واجهة برمجة التطبيقات:
1. الحصول على بيانات الاعتماد التلقائية باستخدام النطاقات التالية:
https://www.googleapis.com/auth/video-ads،

https://www.googleapis.com/auth/pubsub
1. أرسِل الطلب إلى فريق Creative Ingest.
- اتصل بخادم dai.googleapis.com:443 باستخدام بيانات الاعتماد التلقائية.
- أنشئ رمزًا تعريفيًا للعميل لخدمة نقل مواد العرض باستخدام الرمز الذي تم إنشاؤه باستخدام gRPC proto.
- اتصل بـ CreateCreative باستخدام الرمز المرجعي للعميل.
يمكنك اختياريًا إنشاء رمز مثبّت لخدمة العمليات باستخدام رمز gRPC لعمليات المعالجة التي تستغرق وقتًا طويلاً، والذي تم تضمينه في دليل googleapis الذي تم تنزيله في الخطوة 2، والذي يمكن استخدامه للحصول على حالة عملية معيّنة (GetOperation).
التحقّق من PubSub بحثًا عن الإشعارات:
1. استخدِم مكتبة برنامج PubSub أو gRPC للربط بخدمة PubSub و الاستعلام عن إشعارات PubSub المنشورة في الموضوع المقدَّم.
2. فك ترميز رسالة PubSub إلى proto من الخطوة 4.
3. عند عرض عملية تستغرق وقتًا طويلاً من طلبات برمجة التطبيقات إلى CreateCreative أو GetOperation أو في إشعار PubSub، يجب تحويل البيانات الوصفية إلى CreateCreativeOperationMetadata في discovery.proto من google.protobuf.Any proto وأي استجابة إلى Creative في 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 أو ميزة "الإعلانات أثناء عرض الفيديو" على استجابة نموذج عرض إعلانات فيديو (VAST) من نظام إعلان تابع لجهة خارجية لأجل الإعلانات التي سيتم إدراجها في المحتوى.
يتمّ ربط الإعلانات المعروضة بتصميمات الإعلانات التي تمّ نقلها سابقًا. تكون مواد العرض هذه جاهزة للتشغيل، ويتم جلبها من Google Video Infrastructure وتشغيلها للمستخدم.

تعديل الشريك لمستندات VAST

عند عرض استجابة نموذج عرض إعلانات فيديو (VAST) من نظام الإعلانات بعد تحميل تصميم الإعلان بنجاح إلى البنية الأساسية لفيديوهات Google، يجب أن يحتوي المستند على إشارة إلى تصميم الإعلان الذي تمت معالجته. يجب أن يستمر مستند VAST في تضمين ملفات الوسائط لتصميم إعلان معيّن، ولكن لا يمكن ضمان أن يستخدم النظام ملفات الوسائط هذه.

هناك طريقتان للإشارة إلى تصميم إعلان تمت معالجته في مستند VAST: إضافة عنصر UniversalAdId جديد إلى مستند VAST 4 أو الإصدارات الأحدث أو إضافة إضافة مخصّصة.

رقم تعريف الإعلان العام

إنّ gvRegistryID الذي تعرضه Video Creative Ingest API هو معرّف عالمي متاح للجميع ويُستخدَم لتحديد تصميم إعلان فيديو بشكل فريد على مستوى عدة أنظمة إعلانية. يجب إضافة رقم التعريف هذا إلى مستندات VAST 4 أو الإصدارات الأحدث من نظام عرض الإعلانات، وذلك لكي يتمكّن YouTube أو ميزة "إدراج الإعلانات الديناميكية" من استخدام رقم التعريف عند تلقّي مستند VAST، وربطه بالتصميم الأصلي الذي تم إرساله.

على أنظمة الإعلانات إضافة عنصر UniversalAdId جديد إلى مستندات VAST 4 والإصدارات الأحدث ضمن عقدة تصميم الإعلان. يجب ضبط سمة idRegistry على "googlevideo" ، ويجب أن تكون القيمة هي القيمة المقدَّمة في حالة إشعار تصميم الإعلان الذي تمت معالجته بنجاح.

في ما يلي نموذج لمستند VAST 4 تمّت فيه إضافة المعرّف الجديد لإعلان Universal:

<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>

CreativeExtension

بما أنّ عنصر Universal Ad ID لم يتم طرحه إلا في الإصدار 4.0 من نموذج عرض إعلانات الفيديو (VAST)، تحتاج العميد نفسها إلى إضافة مخصّصة لعرضها في مستندات VAST التي تستخدم إصدارًا أقل من 4.0. ويتم ذلك باستخدام عنصر CreativeExtension ضمن عنصر Creative في مواصفات VAST.

الإضافة الجديدة التي تمّ تقديمها هي إضافة عامة تمّ تفعيلها للسماح بملء أي قيمة لمعرّف Universal AD. في هذه الحالة تحديدًا، سيعود معرّف الإعلان العالمي إلى قاعدة بيانات المسجّلين في googlevideo وسيكون المعرّف هو معرّف 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>

واجهة برمجة تطبيقات أداة نقل تصاميم إعلانات الفيديو تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.