از Bid Manager API نسخه 1.1 به نسخه 2 مهاجرت کنید

در مارس ۲۰۲۲، نسخه ۲ رابط برنامه‌نویسی کاربردی Bid Manager را منتشر کردیم. با توجه به انتشار این نسخه جدید، قصد داریم به زودی تاریخ پایان پشتیبانی از نسخه ۱.۱ را اعلام کنیم. توصیه می‌کنیم در اسرع وقت مهاجرت خود را از نسخه ۱.۱ به نسخه ۲ آغاز کنید.

برنامه خود را مهاجرت دهید

مهاجرت از نسخه ۱.۱ به نسخه ۲ نیازمند به‌روزرسانی URLهای نقاط پایانی برای فراخوانی نسخه ۲ و به‌روزرسانی برنامه برای در نظر گرفتن تغییرات ناگهانی است.

فراخوانی‌های API خود را از نسخه ۱.۱ به نسخه ۲ به‌روزرسانی کنید

برای استفاده از نسخه ۲ به جای نسخه ۱.۱، باید درخواست‌های خود را برای استفاده از نقاط پایانی جدید نسخه ۲ به‌روزرسانی کنید.

شناسایی روش‌های معادل

برای به‌روزرسانی فراخوانی‌های API خود از نسخه ۱.۱ به نسخه ۲، ابتدا باید متدهای معادل نسخه ۱.۱ را در نسخه ۲ شناسایی کنید.

نام‌های زیر برای تمام سرویس‌ها و متدها بین نسخه ۱.۱ و نسخه ۲ کمی تغییر کرده‌اند:

به‌روزرسانی به نقاط پایانی جدید

پس از شناسایی متدهای معادل، باید درخواست‌های خود را به‌روزرسانی کنید. برای مثال، برای فراخوانی متد queries.getquery با نسخه ۱.۱، از URL زیر استفاده خواهید کرد:

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

برای فراخوانی متد معادل در نسخه ۲، که با نام queries.get شناخته می‌شود، URL را به صورت زیر به‌روزرسانی کنید:

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

اگر از یک کتابخانه کلاینت برای ارسال درخواست به API استفاده می‌کنید، از جدیدترین نسخه کتابخانه کلاینت استفاده کنید و پیکربندی خود را برای استفاده از نسخه ۲ به‌روزرسانی کنید.

اعمال تغییرات مورد نیاز

ما تعدادی تغییر اساسی را در نسخه ۲ معرفی می‌کنیم. دستورالعمل‌های زیر را مرور کنید و تغییرات لازم را که مربوط به استفاده فعلی شما از API مدیریت پیشنهادات است، اعمال کنید.

به‌روزرسانی تماس‌ها به سرویس queries

  • فیلدهای زیر در منبع Query که در ابتدا توسط اشیاء تو در تو نمایش داده می‌شدند، برای استفاده از انواع اشیاء زیر تغییر یافته‌اند:
    فیلد نسخه ۱.۱ نوع شیء معادل v2
    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 که در ابتدا توسط اشیاء لیست عمومی نمایش داده می‌شدند، به لیست‌هایی از انواع اشیاء جدید زیر تغییر یافته‌اند:
    فیلد لیست نسخه ۱.۱ نوع شیء v2
    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 ، که در ابتدا توسط رشته‌ها نمایش داده می‌شدند، در نسخه ۲ توسط انواع enum نمایش داده می‌شوند و شامل تغییرات زیر می‌شوند:
    • معادل نسخه ۲ تابع 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 اکنون از enum PathMatchPosition استفاده می‌کند. در تبدیل به این enum، مقدار 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
    • مقادیر باقیمانده همگی به‌روزرسانی شده‌اند تا مقادیر معادل خود را در رابط کاربری بهتر نشان دهند:
      مقادیر نسخه ۱.۱ مقدار معادل 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 جایگزین شده‌اند. فیلدهای تاریخ جدید از زمان Unix Epoch به جای میلی‌ثانیه از اشیاء Date استفاده می‌کنند. این فیلدهای جایگزین به شیء DataRange اختصاص داده شده به فیلد dataRange در شیء QueryMetadata منتقل شده‌اند.
  • فیلدهای schedule.startTimeMs و schedule.endTimeMs با فیلدهای startDate و endDate در شیء QuerySchedule جایگزین شده‌اند. فیلدهای تاریخ جدید از اشیاء Date به جای میلی‌ثانیه از زمان Unix Epoch استفاده می‌کنند.
  • فیلدهای 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 حذف شده است. برای تولید گزارش برای پرس‌وجوهای جدید، queries.run را پس از queries.create فراخوانی کنید.
  • متد queries.run به روش‌های زیر به‌روزرسانی شده است:
    • پارامتر پرس‌وجوی asynchronous با پارامتر پرس‌وجوی synchronous جایگزین شده است. پارامتر پرس‌وجوی جدید با منطق معکوس عمل می‌کند و در صورت عدم تعیین مقدار، نادرست در نظر گرفته می‌شود. با توجه به این موضوع، queries.run به طور پیش‌فرض در نسخه ۲ گزارش‌ها را به صورت ناهمگام تولید می‌کند، برخلاف همزمانی که در نسخه ۱.۱ پیش‌فرض است.
    • بدنه درخواست به‌روزرسانی شده است تا فیلد timezoneCode حذف شده و فیلدهای dataRange ، reportDataStartTimeMs و reportDataEndTimeMs با یک شیء DataRange اختصاص داده شده به فیلد dataRange جایگزین شوند.
    • این متد به جای یک بدنه پاسخ خالی، شیء Report حاصل را برمی‌گرداند.
  • فیلد kind در بدنه پاسخ queries.list حذف شده است.

به‌روزرسانی تماس‌ها به سرویس reports

منطق مدیریت خطا را به‌روزرسانی کنید

پیام‌های خطا در سراسر API در نسخه ۲ به‌روزرسانی شده‌اند. این پیام‌های خطای جدید خاص‌تر هستند و در برخی موارد، اطلاعاتی در مورد مقادیر موجود در درخواست API که باعث بازگشت خطا می‌شوند، ارائه می‌دهند. اگر منطق مدیریت خطای فعلی شما به متن پیام خطای خاصی متکی است، قبل از مهاجرت به نسخه ۲، مدیریت خطای خود را تعمیم دهید.