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

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

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

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

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

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

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

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

بالنسبة إلى الإصدار 2، عليك تحديث عنوان URL إلى ما يلي:

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

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

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

نحن بصدد طرح عدد من التغييرات التي قد تؤدي إلى أعطال في الإصدار 2. يُرجى مراجعة التعليمات التالية وإجراء التغييرات المطلوبة ذات الصلة باستخدامك الحالي لواجهة برمجة التطبيقات لـ "مساحة العرض والفيديو 360".

تحديث المكالمات إلى طرق الاستهداف

• تم تخصيص بعض أنواع الاستهداف الآن باستخدام قيم التعداد بدلاً من أرقام تعريف خيارات الاستهداف. على سبيل المثال، يتم الآن استهداف الأجهزة اللوحية مباشرةً من خلال تعداد 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 الذي يقدّم حالة الاستعداد والتعليق لنموذج الخوارزمية الحالي لكل معلِن لديه إمكانية الوصول من خلال قائمة من عناصر CustomBiddingModelDetails.

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

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

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

إذن بالاطّلاع على عناصر YouTube

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

• 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 طرقًا جديدة للاستخدام بدلاً من الطلبات المجمّعة لتحسين الأداء والحدّ من استهلاك الحصص:

• يمكنك استخدام 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