نقل البيانات من Bid Manager API v1.1 إلى v2

في آذار (مارس) 2022، أطلقنا الإصدار 2 من Bid Manager API. وبعد طرح هذا الإصدار الجديد، نخطّط للإعلان قريبًا عن تاريخ إيقاف الإصدار 1.1. ننصحك ببدء عملية نقل البيانات من الإصدار 1.1 إلى الإصدار 2 في أقرب وقت ممكن.

نقل تطبيقك

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

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

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

تحديد الطرق المكافئة

لتعديل طلبات البيانات من واجهة برمجة التطبيقات من الإصدار 1.1 إلى الإصدار 2، عليك أولاً تحديد طرق الإصدار 1.1 المكافئة في الإصدار 2.

تغيّرت أسماء جميع الخدمات والطرق التالية بشكل طفيف بين الإصدارين 1.1 و2:

• يُعرف كل من الخدمتين Queries وReports في الإصدار 1.1 باسم queries وqueries.reports في الإصدار 2.
• تمت إعادة تسمية الطرق على النحو التالي في الإصدار 2:

  اسم الطريقة في الإصدار 1.1	طريقة الإصدار 2 من "المكافئ"
  Queries.createquery	queries.create
  Queries.deletequery	queries.delete
  Queries.getquery	queries.get
  Queries.listqueries	queries.list
  Queries.runquery	queries.run
  Reports.listreports	queries.reports.list

تعديل نقاط النهاية الجديدة

بعد تحديد الطرق المكافئة، عليك تعديل طلباتك. على سبيل المثال، لاستدعاء الطريقة queries.getquery باستخدام الإصدار 1.1، عليك استخدام عنوان URL التالي:

https://www.googleapis.com/doubleclickbidmanager/v1.1/query/queryId

لاستدعاء الطريقة المكافئة في الإصدار 2، والمعروفة باسم queries.get، عدِّل عنوان URL إلى ما يلي:

GET https://doubleclickbidmanager.googleapis.com/v2/queries/queryId

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

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

نحن بصدد طرح عدد من التغييرات التي قد تؤدي إلى أعطال في الإصدار 2. راجِع التعليمات التالية وأجرِ التغييرات المطلوبة ذات الصلة بطريقة استخدامك الحالية لواجهة برمجة التطبيقات Bid Manager API.

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

• تم تغيير الحقول التالية في المورد Query الذي تم تمثيله في الأصل بواسطة كائنات عامة متداخلة لاستخدام أنواع الكائنات التالية:

  الحقل v1.1	نوع العنصر المكافئ في الإصدار 2
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	تمّت إزالته
  params.options.pathQueryOptions.channelGrouping	تمّت إزالته
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	تمّت إزالته
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	تمّت إزالته
  schedule	QuerySchedule

• تم تغيير الحقول التالية في مرجع Query الذي تمثله في الأصل عناصر القائمة العامة، لتصبح قوائم بأنواع العناصر الجديدة التالية:

  حقل القائمة الإصدار 1.1	نوع العنصر في الإصدار 2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	تمّت إزالته
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	تمّت إزالته
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	تمّت إزالته
  params.options.pathQueryOptions.pathFilters[]	تمّت إزالته
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	تمّت إزالته

• يتم تمثيل الحقول التالية في مرجع Query، والتي كانت ممثلة في الأصل بسلاسل، بأنواع تعداد في الإصدار 2، وتشمل التغييرات التالية:
  • يستخدم الإصدار 2 من metadata.dataRange الآن التعداد Range. عند التحويل إلى هذا النوع من التعداد، تمت إزالة القيمة PREVIOUS_HALF_MONTH وتغيير القيمة TYPE_NOT_SUPPORTED إلى RANGE_UNSPECIFIED.
  • يستخدم metadata.format الآن تعداد Format. عند التحويل إلى هذا النوع من التعداد، تمت إزالة القيمة EXCEL_CSV وإضافة القيمة FORMAT_UNSPECIFIED.
  • يستخدم التطبيقان params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match وparams.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match الآن تعداد Match.
  • يستخدم params.options.pathQueryOptions.pathFilters[].pathMatchPosition الآن التعداد PathMatchPosition. تمت إضافة القيمة PATH_MATCH_POSITION_UNSPECIFIED عند التحويل إلى هذا النوع من التعداد.
  • يستخدم schedule.frequency الآن تعداد Frequency. عند التحويل إلى هذا النوع من التعداد، تمت إضافة القيمة FREQUENCY_UNSPECIFIED.
  • يستخدم params.type الآن تعداد ReportType. عند التحويل إلى هذا النوع من التعداد، تم إجراء التغييرات التالية:
  • تم إيقاف القيم التالية نهائيًا:
    • TYPE_ACTIVE_GRP
    • TYPE_AUDIENCE_PERFORMANCE
    • TYPE_CLIENT_SAFE
    • TYPE_COMSCORE_VCE
    • TYPE_CROSS_FEE
    • TYPE_CROSS_PARTNER
    • TYPE_CROSS_PARTNER_THIRD_PARTY_DATA_PROVIDER
    • TYPE_ESTIMATED_CONVERSION
    • TYPE_FEE
    • TYPE_KEYWORD
    • TYPE_LINEAR_TV_SEARCH_LIFT
    • TYPE_NIELSEN_AUDIENCE_PROFILE
    • TYPE_NIELSEN_DAILY_REACH_BUILD
    • TYPE_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PAGE_CATEGORY
    • TYPE_PETRA_NIELSEN_DAILY_REACH_BUILD
    • TYPE_PETRA_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PIXEL_LOAD
    • TYPE_THIRD_PARTY_DATA_PROVIDER
    • TYPE_TRUEVIEW_IAR
    • TYPE_VERIFICATION
    • TYPE_YOUTUBE_VERTICAL
  • تم تعديل القيم المتبقية لتعكس بشكل أفضل القيم المكافئة لها في واجهة المستخدم:

    قيم الإصدار 1.1	قيمة ReportType المكافئة
    TYPE_NOT_SUPPORTED	REPORT_TYPE_UNSPECIFIED
    TYPE_GENERAL	STANDARD
    TYPE_INVENTORY_AVAILABILITY	INVENTORY_AVAILABILITY
    TYPE_AUDIENCE_COMPOSITION	AUDIENCE_COMPOSITION
    TYPE_ORDER_ID	FLOODLIGHT
    TYPE_TRUEVIEW	YOUTUBE
    TYPE_NIELSEN_SITE	GRP
    TYPE_PETRA_NIELSEN_AUDIENCE_PROFILE	YOUTUBE_PROGRAMMATIC_GUARANTEED
    TYPE_REACH_AND_FREQUENCY	REACH
    TYPE_REACH_AUDIENCE	UNIQUE_REACH_AUDIENCE
    TYPE_PATH	FULL_PATH
    TYPE_PATH_ATTRIBUTION	PATH_ATTRIBUTION

• تم استبدال الحقول metadata.dataRange وreportDataStartTimeMs وreportDataEndTimeMs بالحقول range وcustomStartDate وcustomEndDate. تستخدم حقول التاريخ الجديدة عناصر Date بدلاً من الملّي ثانية منذ بدء حقبة يونكس. تم نقل حقول الاستبدال هذه إلى عنصر DataRange الذي تم تعيينه إلى الحقل dataRange في العنصر QueryMetadata.
• تم استبدال الحقلَين schedule.startTimeMs وschedule.endTimeMs بالحقلَين startDate وendDate في العنصر QuerySchedule. تستخدم حقول التاريخ الجديدة عناصر Date بدلاً من الملّي ثانية منذ بدء حقبة يونكس.
• تمت إزالة الحقول metadata.running وmetadata.reportCount وmetadata.googleCloudStoragePathForLatestReport وmetadata.googleDrivePathForLatestReport وmetadata.latestReportRunTimeMs. يجب بدلاً من ذلك استرداد المعلومات المتعلقة بأحدث التقارير التي تم إنشاؤها لطلب بحث باستخدام طريقة queries.reports.list مع مَعلمة طلب البحث orderBy التي تتضمّن "key.reportId desc" لضمان أن يعرض الطلب أحدث التقارير أولاً.
• تمت إزالة الحقول kind وtimezoneCode وmetadata.locale وparams.includeInviteData وschedule.nextRunMinuteOfDay.
• لم يعُد queries.create ينفّذ طلبات البحث تلقائيًا بعد إنشائها، وتمت إزالة مَعلمة طلب البحث asynchronous. استخدِم الأمر Call queries.run بعد queries.create لإنشاء تقارير لطلبات البحث الجديدة.
• تم تعديل طريقة queries.run بالطرق التالية:
  • تم استبدال مَعلمة طلب البحث asynchronous بمَعلمة طلب البحث synchronous. تعمل مَعلمة طلب البحث الجديدة بمنطق معكوس، ويتم اعتبارها غير صحيحة إذا لم يتم تحديدها. بناءً على ذلك، تنشئ queries.run التقارير بشكل غير متزامن تلقائيًا في الإصدار 2، على عكس الإصدار 1.1 الذي ينشئ التقارير بشكل متزامن تلقائيًا.
  • تم تعديل نص الطلب لإزالة الحقل timezoneCode واستبدال الحقول dataRange وreportDataStartTimeMs وreportDataEndTimeMs بكائن DataRange تم تعيينه للحقل dataRange.
  • يعرض الإجراء عنصر Report الناتج بدلاً من نص استجابة فارغ.
• تمت إزالة الحقل kind في نص استجابة queries.list.

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

• تم تغيير الحقول التالية في مورد Report الذي كان يتم تمثيله في الأصل بواسطة كائنات عامة مدمجة لاستخدام أنواع الكائنات التالية:

  حقل الإصدار 1.1	نوع العنصر المكافئ في الإصدار 2
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	تمّت إزالته
  params.options.pathQueryOptions.channelGrouping	تمّت إزالته
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	تمّت إزالته
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	تمّت إزالته

• تم تغيير الحقول التالية في مرجع Report الذي كان يتم تمثيله في الأصل بواسطة عناصر القائمة العامة، لتصبح قوائم من أنواع العناصر الجديدة التالية:

  حقل القائمة الإصدار 1.1	نوع العنصر في الإصدار 2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	تمّت إزالته
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	تمّت إزالته
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	تمّت إزالته
  params.options.pathQueryOptions.pathFilters[]	تمّت إزالته
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	تمّت إزالته

• تم تغيير الحقول التالية في المرجع Report الذي كان ممثلاً في الأصل بسلاسل، وذلك لتصبح الحقول المكافئة لها في الإصدار 2 ممثلة بأنواع تعداد جديدة، كما تم إجراء تغييرات على القيم المقبولة:
  • يستخدم metadata.status.format الآن تعداد Format. عند التحويل إلى هذا النوع من التعداد، تمت إزالة القيمة EXCEL_CSV وإضافة FORMAT_UNSPECIFIED.
  • يستخدم metadata.status.state الآن تعداد State. عند التحويل إلى هذا النوع من التعداد، تمت إضافة القيمتين QUEUED وSTATE_UNSPECIFIED.
  • يستخدم التطبيقان params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match وparams.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match الآن تعداد Match.
  • يستخدم params.options.pathQueryOptions.pathFilters[].pathMatchPosition الآن التعداد PathMatchPosition. تمت إضافة القيمة PATH_MATCH_POSITION_UNSPECIFIED عند التحويل إلى هذا النوع من التعداد.
  • يستخدم params.type الآن تعداد ReportType. عند التحويل إلى هذا النوع من التعداد، تم إجراء العديد من التغييرات التي تم إدراجها بالتفصيل في القسم السابق بشأن تعديل طلبات الخدمة الخاصة بالاستعلامات.
• تم استبدال الحقلين metadata.reportDataStartTimeMs وmetadata.reportDataEndTimeMs بالحقلين reportDataStartDate وreportDataEndDate في العنصر ReportMetadata. تستخدم الحقول الجديدة عناصر Date بدلاً من الملّي ثانية منذ بدء حقبة يونكس.
• تم استبدال metadata.status.finishTimeMs بالحقل finishTime في العنصر ReportStatus. يمثّل حقل الوقت الجديد التاريخ والوقت كطابع زمني بتنسيق RFC3339 UTC "Zulu"‎ بدلاً من تمثيلهما بالملي ثانية منذ بدء حقبة يونكس.
• تمت إزالة الحقلَين metadata.status.failure وparams.includeInviteData.
• تمت إزالة الحقل kind من نص الاستجابة reports.list.

تعديل منطق معالجة الأخطاء

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