این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

در مارس 2022، نسخه 2 Bid Manager API را منتشر کردیم. با توجه به انتشار این نسخه جدید، قصد داریم به زودی تاریخ غروب آفتاب را برای نسخه 1.1 اعلام کنیم. توصیه می کنیم در اسرع وقت مهاجرت خود را از نسخه 1.1 به نسخه 2 آغاز کنید.

درخواست خود را مهاجرت کنید

انتقال از نسخه 1.1 به نسخه 2 نیازمند به روز رسانی URL های نقطه پایانی برای فراخوانی نسخه 2 و به روز رسانی برنامه برای حساب کاربری برای تغییرات شکسته است.

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

برای استفاده از v2 به جای v1.1، باید درخواست های خود را برای استفاده از نقاط پایانی جدید v2 به روز کنید.

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

برای به‌روزرسانی تماس‌های API از استفاده از v1.1 به v2، ابتدا باید روش‌های معادل v1.1 را در v2 شناسایی کنید.

نام‌های زیر همه سرویس‌ها و روش‌ها بین نسخه 1.1 و 2 کمی تغییر کرده است:

Queries و Reports Services در v1.1 به عنوان queries و queries.reports در v2 شناخته می‌شوند.

متدها در v2 به صورت زیر تغییر نام داده اند:

نام روش v1.1	روش معادل v2
`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 با v1.1، از URL زیر استفاده کنید:

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

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

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

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

تغییرات لازم را انجام دهید

ما در حال معرفی تعدادی از تغییرات شکسته در نسخه 2 هستیم. دستورالعمل‌های زیر را مرور کنید و تغییرات مورد نیاز مربوط به استفاده فعلی خود از Bid Manager API را اعمال کنید.

به روز رسانی تماس ها به خدمات `queries`

فیلدهای زیر در منبع Query که در اصل با اشیاء تودرتو عمومی نشان داده می‌شوند، برای استفاده از انواع شیء زیر تغییر کرده‌اند:

فیلد v1.1	نوع شی معادل v2
`metadata`	`QueryMetadata`
`params`	`Parameters`
`params.options`	`Options`
`params.options.pathQueryOptions`	`PathQueryOptions`
`params.options.pathQueryOptions.channelGrouping`	`ChannelGrouping`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter`	`PathQueryOptionsFilter`
`params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter`	`PathQueryOptionsFilter`
`schedule`	`QuerySchedule`

فیلدهای زیر در منبع Query که در اصل با اشیاء لیست عمومی نشان داده می‌شوند، به لیست‌هایی از انواع شی جدید زیر تغییر کرده‌اند:

فیلد لیست v1.1	نوع شیء v2
`params.filters[]`	`FilterPair`
`params.options.pathQueryOptions.channelGrouping.rules[]`	`Rule`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]`	`DisjunctiveMatchStatement`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]`	`EventFilter`
`params.options.pathQueryOptions.pathFilters[]`	`PathFilter`
`params.options.pathQueryOptions.pathFilters[].eventFilters[]`	`EventFilter`

فیلدهای زیر در منبع Query که در اصل با رشته ها نمایش داده می شوند، با انواع enum در v2 نشان داده می شوند و شامل تغییرات زیر هستند:

معادل v2 metadata.dataRange اکنون از Range enum استفاده می کند. در تبدیل به این enum، مقدار PREVIOUS_HALF_MONTH حذف شد و مقدار TYPE_NOT_SUPPORTED به RANGE_UNSPECIFIED تغییر یافت.
اکنون metadata.format از Format enum استفاده می کند. در تبدیل به این enum، مقدار 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 استفاده می کند. در تبدیل به این enum، مقدار PATH_MATCH_POSITION_UNSPECIFIED اضافه شده است.
schedule.frequency اکنون از Frequency enum استفاده می کند. در تبدیل به این enum، مقدار FREQUENCY_UNSPECIFIED اضافه شده است.
params.type اکنون از فهرست ReportType استفاده می کند. در تبدیل به این enum تغییرات زیر اعمال شده است:
مقادیر زیر منسوخ شده اند:
- 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

مقادیر باقی‌مانده همگی به‌روزرسانی شده‌اند تا مقادیر معادل خود را در UI بهتر منعکس کنند:

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

به روز رسانی تماس ها به خدمات `reports`

فیلدهای زیر در منبع Report که در اصل با اشیاء تودرتو عمومی نشان داده می‌شوند، برای استفاده از انواع شیء زیر تغییر کرده‌اند:

فیلد v1.1	نوع شی معادل v2
`key`	`ReportKey`
`metadata`	`ReportMetadata`
`metadata.status`	`ReportStatus`
`params`	`Parameters`
`params.options`	`Options`
`params.options.pathQueryOptions`	`PathQueryOptions`
`params.options.pathQueryOptions.channelGrouping`	`ChannelGrouping`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter`	`PathQueryOptionsFilter`
`params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter`	`PathQueryOptionsFilter`

فیلدهای زیر در منبع Report که در اصل با اشیاء فهرست کلی نشان داده می‌شوند، به فهرست‌هایی از انواع شی جدید زیر تغییر کرده‌اند:

فیلد لیست v1.1	نوع شیء v2
`params.filters[]`	`FilterPair`
`params.options.pathQueryOptions.channelGrouping.rules[]`	`Rule`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]`	`DisjunctiveMatchStatement`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]`	`EventFilter`
`params.options.pathQueryOptions.pathFilters[]`	`PathFilter`
`params.options.pathQueryOptions.pathFilters[].eventFilters[]`	`EventFilter`

فیلدهای زیر در منبع Report که در اصل با رشته‌ها نمایش داده می‌شوند، تغییر کرده‌اند، بنابراین فیلدهای معادل آن‌ها در v2 با انواع enum جدید نشان داده می‌شوند و شامل تغییراتی در مقادیر قابل قبول می‌شوند:
- metadata.status.format اکنون از Format enum استفاده می کند. در تبدیل به این enum، مقدار EXCEL_CSV حذف شده و FORMAT_UNSPECIFIED اضافه شده است.
- metadata.status.state اکنون از State enum استفاده می کند. در تبدیل به این enum، مقادیر 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 استفاده می کند. در تبدیل به این enum، مقدار PATH_MATCH_POSITION_UNSPECIFIED اضافه شده است.
- params.type اکنون از فهرست ReportType استفاده می کند. در تبدیل به این شماره، تغییرات متعددی ایجاد شده است و در قسمت قبل در مورد به روز رسانی تماس های سرویس پرس و جو به تفصیل ذکر شده است.
فیلدهای metadata.reportDataStartTimeMs و metadata.reportDataEndTimeMs با فیلدهای reportDataStartDate و reportDataEndDate در شی ReportMetadata جایگزین شده اند. فیلدهای جدید از زمان Unix Epoch به جای میلی ثانیه از اشیاء Date استفاده می کنند.
metadata.status.finishTimeMs با فیلد finishTime در شی ReportStatus جایگزین شده است. این فیلد زمان جدید تاریخ زمان را به‌عنوان مهر زمانی در قالب RFC3339 UTC "Zulu" به جای میلی‌ثانیه از زمان Unix Epoch نشان می‌دهد.
فیلدهای metadata.status.failure و params.includeInviteData حذف شده اند.
فیلد kind در بدنه پاسخ reports.list حذف شده است.

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

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