نقل البيانات من الإصدار 1 إلى الإصدار 2

تاريخ آخر تعديل: 06‏-12‏-2022

نقل بيانات تطبيقك

تتطلّب عملية نقل البيانات من الإصدار 1 إلى الإصدار 2 تعديل عناوين URL لنقاط النهاية من أجل طلب الإصدار 2 و تعديل تطبيقك لمراعاة التغييرات الأساسية.

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

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

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

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

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

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

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

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

نحن بصدد طرح عدد من التغييرات الأساسية في الإصدار 2. راجِع الخطوات التالية وأجرِ التغييرات المطلوبة ذات الصلة باستخدامك الحالي لواجهة برمجة التطبيقات Display & Video 360 API.

تعديل طلبات الاستهداف

• يتم الآن تحديد بعض أنواع الاستهداف باستخدام قيم التعداد بدلاً من أرقام تعريف خيارات الاستهداف. على سبيل المثال، يتم الآن استهداف الأجهزة اللوحية مباشرةً باستخدام التعداد DEVICE_TYPE_TABLET DeviceType، بدلاً من معرّف خيار الاستهداف من الخدمة targetingTypes.targetingOptions. يتم تمثيل النُسخ من سلاسل ملفّات التعريف هذه في الحقل الجديد assignedTargetingOptionIdAlias في موارد AssignedTargetingOption هذه، ويمكن استخدامها عند استرداد الاستهداف الحالي أو حذفه. لم تتغيّر قيمة assignedTargetingOptionId لهذه الموارد AssignedTargetingOption.

  عدِّل المكالمات التي تدير أنواع الاستهداف التالية لاستخدام قيم التعداد:

  • TARGETING_TYPE_AGE_RANGE
  • TARGETING_TYPE_CONTENT_INSTREAM_POSITION
  • TARGETING_TYPE_CONTENT_OUTSTREAM_POSITION
  • TARGETING_TYPE_DEVICE_TYPE
  • TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION
  • TARGETING_TYPE_ENVIRONMENT
  • TARGETING_TYPE_EXCHANGE
  • TARGETING_TYPE_GENDER
  • TARGETING_TYPE_HOUSEHOLD_INCOME
  • TARGETING_TYPE_NATIVE_CONTENT_POSITION
  • TARGETING_TYPE_OMID
  • TARGETING_TYPE_PARENTAL_STATUS
  • TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION
  • TARGETING_TYPE_VIDEO_PLAYER_SIZE
  • TARGETING_TYPE_VIEWABILITY

• تم استبدال الطريقة advertisers.lineItems.bulkEditLineItemAssignedTargetingOptions بالطريقة advertisers.lineItems.bulkEditAssignedTargetingOptions.

• تم استبدال الطريقة advertisers.lineItems.bulkListLineItemAssignedTargetingOptions بالطريقة advertisers.lineItems.bulkListAssignedTargetingOptions.

• عدِّل طلبات إدارة TARGETING_TYPE_PROXIMITY_LOCATION_LIST لاستخدام حجم دائرة نصف قطرها و وحدة المسافة محدّدة بدلاً من قيمة ProximityRadiusRange في التعداد.

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

  عدِّل المكالمات إلى الطرق التالية لاستخدام أسمائها الجديدة:

  • advertisers.bulkEditAdvertiserAssignedTargetingOptions إلى advertisers.editAssignedTargetingOptions
  • advertisers.bulkListAdvertiserAssignedTargetingOptions إلى advertisers.listAssignedTargetingOptions
  • advertisers.campaigns.bulkListCampaignAssignedTargetingOptions إلى advertisers.campaigns.listAssignedTargetingOptions
  • advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions إلى advertisers.insertionOrders.listAssignedTargetingOptions
  • من partners.bulkEditPartnerAssignedTargetingOptions إلى partners.editAssignedTargetingOptions

تعديل المكالمات إلى خدمة advertisers.lineItems

• تمت إزالة الحقل inventorySourceIds. يمكنك إدارة تعيين مصدر المستودع باستخدام موارد AssignedTargetingOption في TARGETING_TYPE_INVENTORY_SOURCE.

• تم إيقاف قيم LineItemWarningMessage التالية نهائيًا في الإصدار 2 ولن تظهر بعد الآن في LineItem.warningMessages:

  • NO_POSITIVE_AUDIENCE_LIST_TARGETED
  • APP_INSTALL_NO_CONVERSION_PIXEL
  • TARGETING_REVOKED_OR_CLOSED_USER_LIST
  • APP_INSTALL_NO_OPTIMAL_BIDDING_STRATEGY
  • CREATIVE_SIZE_NOT_IN_USE_FOR_TARGETED_DEALS
  • NO_CREATIVE_FOR_TARGETED_DEALS
  • TARGETING_DEPRECATED_GEO_TARGET

• تمّت إزالة الحقل triggerId من كائن LineItemFlight، وتمّت إزالة القيمة LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER من نوع التعداد LineItemFlightDateType. لا تتيح الإصدار 2 ضبط بنود الإعلانات على الإنفاق استنادًا إلى تفعيل عوامل التشغيل اليدوية.

تعديل المكالمات إلى خدمة customBiddingAlgorithms

تم استبدال الحقلين customBiddingAlgorithmState وmodelReadiness بحقل modelDetails الذي يقدّم حالتَي الاستعداد والتعليق لنموذج algorithmic الحالي لكلّ معلِن يمكنه الوصول إليه من خلال قائمة بعناصر CustomBiddingModelDetails.

تغييرات إضافية

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

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

إذن بالقراءة فقط إلى عناصر YouTube

في الإصدار 2، يمكن استرداد عناصر YouTube وإعدادات استهدافها باستخدام خدمات advertisers.lineItems و advertisers.lineItems.targetingTypes.assignedTargetingOptions ، على التوالي. توفّر واجهة برمجة التطبيقات إذن الوصول للقراءة فقط، ما يعني أنّ أي محاولة لطلبات الكتابة التي يتم إجراؤها على هذه العناصر ستؤدي إلى ظهور خطأ. ستكون بنود LineItemType في YouTube من إحدى القيم التالية:

• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_ACTION
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_AUDIO
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_NON_SKIPPABLE
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_NON_SKIPPABLE_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_REACH
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_REACH_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_SIMPLE
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_SIMPLE_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_VIDEO_SEQUENCE

طُرق جديدة تحقّق أداءً أفضل

في الإصدار 2، توفّر خدمة advertisers.lineItems methods جديدة لاستخدامها بدلاً من الطلبات المجمّعة لتحسين الأداء وخفض استهلاك الحصة:

• يمكنك استخدام advertisers.lineItems.bulkUpdate لضبط قيم الحقول نفسها لعدّة عناصر سلع. لا تتوفّر حاليًا سوى تعديلات على الحقل entityStatus.
• يمكنك استخدام advertisers.lineItems.bulkEditAssignedTargetingOptions لإضافة خيارات الاستهداف المحدّدة نفسها أو إزالتها في عناصر سطر متعددة.
• يمكنك استخدام advertisers.lineItems.bulkListAssignedTargetingOptions لعرض خيارات الاستهداف المحدّدة على مستوى عناصر متعددة.
• يمكنك استخدام advertisers.lineItems.duplicate لإنشاء نسخة مماثلة لعنصر حالي ضمن طلب الإدراج نفسه، مع نسخ كل الإعدادات وإعدادات الاستهداف.

إذن الوصول الجزئي للكتابة لاستهداف طلبات الإدراج

في الإصدار 2، يمكنك تعديل إعدادات استهداف مجموعة فرعية لموارد InsertionOrder باستخدام الطريقتَين الجديدتَين create و delete في خدمة advertisers.insertionOrders.targetingTypes.assignedTargetingOptions. يمكن إدارة أنواع الاستهداف التالية بالكامل على مستوى طلب الإدراج:

• TARGETING_TYPE_AGE_RANGE
• TARGETING_TYPE_BROWSER
• TARGETING_TYPE_CATEGORY
• TARGETING_TYPE_CHANNEL
• TARGETING_TYPE_DEVICE_MAKE_MODEL
• TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION
• TARGETING_TYPE_ENVIRONMENT
• TARGETING_TYPE_GENDER
• TARGETING_TYPE_KEYWORD
• TARGETING_TYPE_LANGUAGE
• TARGETING_TYPE_NEGATIVE_KEYWORD_LIST
• TARGETING_TYPE_OPERATING_SYSTEM
• TARGETING_TYPE_PARENTAL_STATUS
• TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION
• TARGETING_TYPE_VIEWABILITY