نقل البيانات من الإصدار 4 إلى الإصدار 5 من Display & Video 360 API

تاريخ آخر تعديل: 22-10-2026

تحذير: يتوفّر الإصدار 5 كإصدار تجريبي مفتوح. قد يتم إجراء تغييرات قد تؤدي إلى عطل في الإصدار 5 أثناء مرحلة الإصدار التجريبي، وسيتم إدراجها في ملاحظات إصدار Display & Video 360 API. سيتم تعديل هذا المستند حسب الحاجة ليعكس الإصدار التجريبي المباشر.

نقل تطبيقك

تتطلّب عملية نقل البيانات من الإصدار 4 إلى الإصدار 5 تعديل عناوين URL لنقاط النهاية من أجل طلب الإصدار 5، وتعديل تطبيقك لمراعاة التغييرات التي قد تؤدي إلى عطل، ومراجعة أي ميزات جديدة قد تفيد عملية الدمج.

تعديل طلبات البيانات من واجهة برمجة التطبيقات من الإصدار 4 إلى الإصدار 5

لاستخدام الإصدار 5 بدلاً من الإصدار 4، عليك تعديل طلباتك لاستخدام نقاط النهاية الجديدة في الإصدار 5.

على سبيل المثال، لطلب طريقة advertisers.get باستخدام الإصدار 4، استخدِم عنوان URL التالي:

GET https://displayvideo.googleapis.com/v4/advertisers/advertiserId

بالنسبة إلى الإصدار 5، عدِّل عنوان URL إلى ما يلي:

GET https://displayvideo.googleapis.com/v5/advertisers/advertiserId

إذا كنت تستخدم مكتبة عميل لإرسال الطلبات إلى واجهة برمجة التطبيقات، استخدِم أحدث إصدار من مكتبة العميل وعدِّل الإعدادات لاستخدام الإصدار 5.

إجراء التغييرات المطلوبة

يقدّم الإصدار 5 من Display & Video 360 API عددًا من التغييرات التي قد تؤدي إلى عطل. يُرجى مراجعة التعليمات التالية وإجراء التغييرات المطلوبة ذات الصلة باستخدامك الحالي لواجهة Display & Video 360 API.

للاطّلاع على قائمة شاملة بالاختلافات بين الإصدارَين 4 و5 من Display & Video 360 API، يُرجى مراجعة ملاحظات الإصدار.

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

يغيّر الإصدار 5 من Display & Video 360 API طريقة استرداد واستهداف صفقات مصادر المساحات الإعلانية المتاحة وحزم المزادات.

في الإصدار 4، تمثّل موارد InventorySource التي يتم استردادها باستخدام خدمة inventorySources كلاً من صفقات مصادر المستودع الإعلاني وحزم المزادات. يتم استهداف كل من الصفقات وحِزم المزادات باستخدام TARGETING_TYPE_INVENTORY_SOURCE.

في الإصدار الخامس، يتم التعامل مع صفقات مصادر المستودع الإعلاني وحزم المزادات بشكل منفصل:

• يتم استهداف صفقات مصادر المستودع الإعلاني باستخدام TARGETING_TYPE_INVENTORY_SOURCE_DEAL، ويتم استردادها باستخدام الخدمتَين advertisers.inventorySources وpartners.inventorySources، ويتم استهدافها باستخدام الحقل AssignedTargetingOption inventorySourceDetails.
• يتم استهداف حزم المزاد باستخدام TARGETING_TYPE_AUCTION_PACKAGE، ويتم استردادها باستخدام خدمة targetingTypes.targetingOptions، ويتم استهدافها باستخدام الحقل AssignedTargetingOption auctionPackageDetails.

يؤدي هذا التعديل إلى تغيير المعرّفات المستخدَمة للصفقات وحزم المزادات الحالية، لذا لا يمكنك استخدام أي معرّفات موارد InventorySource مخزّنة مؤقتًا سابقًا بعد نقل البيانات.

بالإضافة إلى هذه التغييرات، يزيل الإصدار الخامس أيضًا إمكانية إنشاء دوال استرداد القيمة لمصادر المستودع الإعلاني وتعديلها.

تعديل منطق استهداف الجمهور لموارد "حملات زيادة الطلب" وYouTube

يعدّل الإصدار 5 من Display & Video 360 API منطق استهداف الجمهور لموارد "حملات زيادة الطلب" وYouTube لاستخدام الخيارات الفردية المحدّدة لكل قائمة مستخدمين مستهدَفة.

في الإصدار 4، تتم إدارة جميع عمليات استهداف الجمهور باستخدام TARGETING_TYPE_AUDIENCE_GROUP.

في الإصدار 5، تتم إدارة استهداف الجمهور المخصّص للمجموعات الإعلانية في حملات زيادة الطلب والمجموعات الإعلانية على YouTube باستخدام أحد أنواع الاستهداف التالية وحقول موارد AssignedTargetingOption، وذلك حسب نوع الجمهور:

• ‫TARGETING_TYPE_COMBINED_AUDIENCE باستخدام combinedAudienceDetails
• ‫TARGETING_TYPE_CUSTOM_LIST باستخدام customListDetails
• ‫TARGETING_TYPE_FIRST_PARTY_AND_PARTNER_AUDIENCE باستخدام firstPartyAndPartnerAudienceDetails
• ‫TARGETING_TYPE_GOOGLE_AUDIENCE باستخدام googleAudienceDetails
• ‫TARGETING_TYPE_LOOKALIKE_AUDIENCE باستخدام lookalikeAudienceDetails

ستواصل البنود الإعلانية استخدام TARGETING_TYPE_AUDIENCE_GROUP AssignedTargetingOption واحد لإدارة استهداف الجمهور لجميع الأنواع.

الترقية إلى Data Manager API لإدارة شرائح جمهور "مطابقة العملاء"

تزيل واجهة برمجة التطبيقات Display & Video 360 API v5 إمكانية إنشاء وإدارة عضوية شرائح جمهور "مطابقة العملاء" من خلال إزالة الطرق التالية:

• firstPartyAndPartnerAudiences.create
• firstPartyAndPartnerAudiences.editCustomerMatchMembers
• firstPartyAndPartnerAudiences.patch

لمواصلة إدارة شرائح جمهور "مطابقة العملاء"، عليك ترقية سير العمل لاستخدام Data Manager API.

إضافة إمكانية استرداد طلبات الإدراج في "الإعلانات الرقمية في الأماكن العامة"

يضيف الإصدار 5 من Display & Video 360 API إمكانية استرداد طلبات الإدراج في "الإعلانات الرقمية في الأماكن العامة".

إذا كان المعلِنون يستخدمون الإعلانات الرقمية في الأماكن العامة، عليك ترقية أي عملية دمج تستدعي advertisers.insertionOrders.list تحسّبًا لتضمين موارد InsertionOrder مع قيمة حقل insertionOrderType تساوي OUT_OF_HOME.

في الإصدار الخامس، سيظل من الممكن استرداد العناصر الإعلانية ضمن طلبات الإدراج في "الإعلانات الرقمية في الأماكن العامة" كما كانت في الإصدار الرابع.

تعديل الإشارات إلى Adloox لتصبح Peer39

في الإصدار 5، تم تعديل الحقول وقيم التعداد التي تشير إلى دمج "مساحة العرض والفيديو 360" مع Adloox (المعروفة أيضًا باسم Scope3) لتقييم مدى الملاءمة للعلامة التجارية من جهة خارجية، لتصبح Peer39:

• تم استبدال الحقل ThirdPartyVerifierAssignedTargetingOptionDetails adloox بـ peer39.
• PartnerCostType تم استبدال قيم التعداد PARTNER_COST_TYPE_ADLOOX وPARTNER_COST_TYPE_ADLOOX_PREBID بـ PARTNER_COST_TYPE_PEER39 وPARTNER_COST_TYPE_PEER39_PREBID.

تعديل الحقول الخاصة بالبنود الإعلانية والمجموعات الإعلانية والإعلانات على YouTube

في الإصدار 5، تمت إزالة أو تعديل حقول مختلفة في الموارد LineItem وAdGroup وAdGroupAd. يُرجى تعديل منطق استرداد الموارد لمراعاة هذه التغييرات.

في المرجع LineItem:

• تم استبدال حقل YoutubeAndPartnersSettings relatedVideoIds بـ relatedVideos.

في الموردَين LineItem وAdGroup:

• تمت إزالة الحقلَين audienceExpansionSeedListExcluded وaudienceExpansionLevel من TargetingExpansionConfig.

في المرجع AdGroupAd:

• تمت إضافة حقل containsSyntheticMedia.
• تم تقسيم حقل trackingUrl في عناصر AudioAd وCommonInStreamAttribute وVideoPerformanceAd إلى حقلَين، هما trackingUrl وuserSpecifiedTrackingUrl، للتمييز بين عنوان URL المستخدَم للتتبُّع وعنوان URL للتتبُّع الذي يحدّده المستخدِم.

إزالة الإشارات إلى قيم التعداد التي تم إيقافها نهائيًا

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

تشمل أنواع التعداد التي تتضمّن قيمًا متأثرة ما يلي: ContentRatingTier وGoogleAudienceType وSdfVersion وSensitiveCategory. يمكنك الاطّلاع على ملاحظات الإصدار للحصول على قائمة شاملة بجميع قيم التعداد التي تمت إزالتها.

مراجعة الميزات الجديدة

بالإضافة إلى التغييرات التي قد تؤدي إلى عطل، يقدّم الإصدار الخامس أيضًا الميزات الجديدة التالية:

• إدارة كاملة لاستهداف استبعاد قنوات وفيديوهات YouTube على مستوى المعلِن ضمن نوعَي الاستهداف TARGETING_TYPE_YOUTUBE_VIDEO وTARGETING_TYPE_YOUTUBE_CHANNEL في الإصدار 4، كان هذا الاستهداف متاحًا للقراءة فقط.
• إمكانية إنشاء موارد InsertionOrder للإعلانات الرقمية في الأماكن العامة
• إتاحة المجموعات الإعلانية التي تستخدم تصاميم إعلانات مخصّصة لإنشاء الإعلانات من خلال إضافة الحقلَين AdGroup adSource وcreativeAssignments والحقل AdGroupAd parentCreativeId
• إمكانية إنشاء موارد LookalikeAudience واستردادها
• حقل containsSyntheticMedia جديد في المورد AdGroupAd.