ممکن است برای آپلود فایل های داده های ساختاریافته نیاز به استفاده از نسخه 9 یا جدیدتر داشته باشید. برای جزئیات بیشتر به صفحه منسوخ شدن ها و راهنمای انتقال نسخه 9 برای دستورالعمل های گام به گام مراجعه کنید.
مهاجرت به فایل های داده ساختاریافته v8، مهاجرت به فایل های داده ساختاریافته v8، مهاجرت به فایل های داده ساخت یافته v8
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
آخرین به روز رسانی: 2024-11-12
این راهنما شما را در فرآیند مهاجرت از استفاده از فایل‌های داده ساختاریافته نسخه ۷.۱ به نسخه ۸ راهنمایی می‌کند و تغییرات بین دو نسخه را که ممکن است بر یکپارچه‌سازی شما تأثیر بگذارد، توضیح می‌دهد.
برای فهرست جامع تفاوت‌های نسخه 7.1 و 8، به یادداشت‌های انتشار مراجعه کنید.
نسخه فایل های داده ساختاریافته خود را مهاجرت کنید
برای انتقال به فایل‌های داده ساختاریافته (SDF) نسخه ۸ از نسخه قبلی:
منابع و اقدامات تولید SDF خود را برای استفاده از v8 به روز کنید.
منطق منبع آگهی را به روز کنید تا پس از ایجاد یک نوع آن را شناسایی کنید.
منطق جدیدی را برای خواندن، ایجاد و به‌روزرسانی منابع تقاضای نسل اضافه کنید.
نسخه فایل های داده ساختاریافته را به روز کنید
برای استفاده از نسخه جدید فایل‌های داده ساختاریافته، نسخه اختصاص داده شده را در منابع شریک و آگهی‌دهنده خود به‌روزرسانی کنید و هنگام ایجاد تکالیف دانلود در Display & Video 360 API از نسخه جدید استفاده کنید.
تنظیمات منبع والد را به روز کنید
نسخه پیش‌فرض Structured Data Files در سطح منبع شریک و تبلیغ‌کننده تنظیم شده است. این نسخه به عنوان پیش‌فرض هنگام دانلود فایل‌های داده ساختاریافته از طریق رابط یا API استفاده می‌شود.
در رابط تنظیم کنید
در سطح شریک
به شریک مورد نظر بروید.
منوی تنظیمات شریک را در ناوبری سمت چپ باز کنید و به صفحه جزئیات اصلی بروید.
پیکربندی نسخه SDF را در بخش فایل های داده ساخت یافته به نسخه 8 به روز کنید.
در سطح تبلیغ کننده
به تبلیغ کننده مورد نظر بروید.
منوی تنظیمات آگهی‌دهنده را در پیمایش سمت چپ باز کنید و به صفحه جزئیات اصلی بروید.
پیکربندی نسخه SDF را در بخش فایل های داده ساخت یافته به نسخه 8 به روز کنید. اگر نسخه پیش‌فرض در سطح شریک تنظیم شده باشد، ممکن است این تنظیم قابل ویرایش نباشد.
در API تنظیم کنید
در سطح شریک
نمی‌توانید نسخه پیش‌فرض SDF را در سطح Partner در API تنظیم کنید.
درخواست‌های sdfdownloadtasks.create را در API به‌روزرسانی کنید
هنگام ایجاد یک درخواست sdfdownloadtasks.create با استفاده از Display & Video 360 API، قسمت version بدنه درخواست را روی SDF_VERSION_8 تنظیم کنید.
نوع را در منابع آگهی مشخص کنید
v8 یک ستون Ad Type به فایل‌های Ad اضافه می‌کند، که نوع آگهی نشان‌داده‌شده توسط هر ردیف را نشان می‌دهد. این ستون جدید مورد نیاز است و برای منابع موجود هنگام دانلود فایل‌های تبلیغ v8 پر می‌شود.
هنگام به روز رسانی تبلیغات موجود، مقدار این ستون نباید تغییر کند.
هنگام ایجاد تبلیغات جدید، باید این ستون را با یکی از مقادیر ذکر شده در توضیحات ستون پر کنید.
منطق منابع تقاضای نسل را به روز کنید
v8 از ایجاد، بازیابی و به‌روزرسانی کمپین‌های تقاضای نسل با استفاده از موارد خط ، گروه آگهی و فایل‌های آگهی پشتیبانی می‌کند. منابع تقاضای Gen از منطق متفاوتی برای تأیید مهر زمانی استفاده می‌کنند، به جمعیت ستون‌های اضافی نیاز دارند و با محدودیت‌های جدید در سه نوع فایل محدود می‌شوند.
تأیید مهر زمانی
برای همه موارد خط غیر تقاضای نسل، ستون Timestamp یک فایل آیتم خط در دانلود با آخرین باری که یک آیتم خط اصلاح شده است پر می شود. این مقدار هنگام به‌روزرسانی یک مورد خط با استفاده از SDF برای تأیید اینکه یک مورد خط از زمان دانلود فایل اصلی به‌روزرسانی نشده است استفاده می‌شود. اگر چنین است، به روز رسانی ناموفق است.
برای موارد خط تقاضای نسل، ستون Timestamp و تأیید همراه آن متفاوت عمل می کند. برای ورودی های مورد خط تقاضای Gen، ستون با زمان فعلی در زمان دانلود پر می شود. هنگام آپلود، Display & Video 360 بررسی می‌کند که آیا بیش از 24 ساعت از مهر زمانی داده شده گذشته است یا خیر. اگر بیش از 24 ساعت گذشته باشد، ورودی فایل اصلی قدیمی در نظر گرفته می شود و به روز رسانی انجام نمی شود. اگر این اتفاق افتاد، فایل را دوباره دانلود کنید و به‌روزرسانی‌های خود را بر اساس نسخه جدیدتر انجام دهید. این روش تأیید جدید مانع از بازنویسی تغییرات ایجاد شده در 24 ساعت گذشته نمی شود. برای جلوگیری از رونویسی تصادفی، فقط موارد خط تقاضای نسل تقاضا را که می‌خواهید به‌روزرسانی کنید در فایل‌هایی که آپلود می‌کنید بگنجانید.
ستون های مورد نیاز
انواع فایل‌های زیر دارای ستون‌هایی هستند که اکنون برای منابع خاص تقاضای Gen، علاوه بر ستون‌هایی که برای همه موجودیت‌های آن نوع فایل مورد نیاز هستند، مورد نیاز هستند.
مورد خط
ستون های مورد نیاز برای مقادیر ستون Typeآیتم خط زیر
تقاضای ژنرال
Pacing Amount
TrueView Bid Strategy Type
TrueView Bid Strategy Value
آگهی
ستون های مورد نیاز برای مقادیر ستون Ad Typeآگهی زیر
تقاضای ژنرال چرخ فلک
Business Name
Call to Action
Demand Gen Cards
Description 1
Headline
In-feed Video Headline
Landing Page URL
Logo Asset IDs
تصویر نسل تقاضا
Business Name
Call to Action
Description 1
Headline
In-feed Video Headline
Landing Page URL
Logo Asset IDs
Marketing Image Asset Id
محصول نسل تقاضا
Business Name
Description 1
Headline
In-feed Video Headline
Landing Page URL
Logo Asset IDs
ویدیوی نسل تقاضا
Business Name
Call to Action
Description 1
Headline
In-feed Video Headline
Landing Page URL
Logo Asset IDs
Video Id
محدودیت های به روز شده
علاوه بر ستون‌های جدید مورد نیاز برای برخی از موارد و آگهی‌های خط تقاضای نسل، چندین ستون در انواع موارد خط ، گروه آگهی و انواع فایل آگهی محدودیت‌های استفاده جدیدی دارند که برای منابع نسل تقاضا اعمال می‌شود.
این محدودیت‌ها متعدد و مختص ستون‌های مورد نظر هستند، بنابراین این راهنما فهرست کاملی از محدودیت‌ها ارائه نمی‌کند. توصیه می‌کنیم قبل از ایجاد یا به‌روزرسانی منابع تقاضای نسل با استفاده از آپلود SDF، مستندات مرجع v8 را برای انواع موارد خط ، گروه آگهی ، و انواع فایل آگهی بخوانید.
تاریخ آخرین به‌روزرسانی 2025-07-24 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین به‌روزرسانی 2025-07-24 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eThis guide explains how to migrate from Structured Data Files v7.1 to v8, outlining key changes and impacts on integration.\u003c/p\u003e\n"],["\u003cp\u003eMigrating involves updating resource and SDF generation actions to v8, adding Ad resource type identification logic, and implementing Demand Gen resource handling.\u003c/p\u003e\n"],["\u003cp\u003eYou can set the default SDF version at the partner and advertiser level through the interface or API, and individual download tasks need version specification in API requests.\u003c/p\u003e\n"],["\u003cp\u003eVersion 8 introduces an \u003ccode\u003eAd Type\u003c/code\u003e column for Ads, requiring it to be populated when creating new ads and preventing changes to existing ads.\u003c/p\u003e\n"],["\u003cp\u003eDemand Gen resources in v8 have specific logic for timestamp verification, require additional columns in Line Item and Ad files, and have new restrictions detailed in the v8 reference documentation.\u003c/p\u003e\n"]]],[],null,["# Migrate to Structured Data Files v8\n\n*Last update: 2024-11-12*\n\nThis guide leads you through the process of migrating from using Structured Data\nFiles v7.1 to v8 and explains the changes between the two versions that may\nimpact your integration.\n\nSee the [release notes](/display-video/api/structured-data-file/rel-notes#version_8_beta) for an exhaustive list of differences\nbetween v7.1 and v8.\n\nMigrate your Structured Data Files version\n------------------------------------------\n\nTo migrate to Structured Data Files (SDFs) v8 from a previous version:\n\n1. Update your resources and SDF generation actions to use v8.\n2. Update Ad resource logic to identify a type upon creation.\n3. Add new logic for reading, creating, and updating Demand Gen resources.\n\n### Update Structured Data Files version\n\nTo use a new Structured Data Files version, update the assigned version in your\nparent Partner and Advertiser resources and use the new version when creating\nindividual download tasks in the [Display \\& Video 360 API](/display-video/api).\n\n#### Update parent resource settings\n\nA default Structured Data Files version is set at the partner and advertiser\nresource level. This version is used as the default when downloading Structured\nData Files through the interface or API.\n\n##### Set in the interface\n\n**At the partner level**\n\n1. Navigate to the intended partner.\n2. Expand the **Partner settings** menu in the left-hand navigation and navigate to the **Basic details** page.\n3. Update the **SDF version** configuration in the **Structured Data Files** section to **v8**.\n\n**At the advertiser level**\n\n1. Navigate to the intended advertiser.\n2. Expand the **Advertiser settings** menu in the left-hand navigation and navigate to the **Basic details** page.\n3. Update the **SDF version** configuration in the **Structured Data Files** section to **v8**. If the default version is set at the Partner level, this setting may not be editable.\n\n##### Set in the API\n\nAt the partner level\n: You cannot set the default SDF version at the Partner level in the API.\n\nAt the advertiser level\n: Make an [`advertisers.patch`](/display-video/api/reference/rest/current/advertisers/patch) request to update the\n [`dataAccessConfig.sdfConfig.sdfConfig.version`](/display-video/api/reference/rest/current/SdfConfig#FIELDS.version) to\n `SDF_VERSION_8` and, if needed,\n [`dataAccessConfig.sdfConfig.overridePartnerSdfConfig`](/display-video/api/reference/rest/current/advertisers#AdvertiserSdfConfig.FIELDS.override_partner_sdf_config)\n to `True`.\n\n#### Update `sdfdownloadtasks.create` requests in the API\n\nWhen making a [`sdfdownloadtasks.create`](/display-video/api/reference/rest/current/sdfdownloadtasks/create) request using the\nDisplay \\& Video 360 API, set the [`version`](/display-video/api/reference/rest/current/sdfdownloadtasks/create#body.request_body.FIELDS.version) field of the\nrequest body to `SDF_VERSION_8`.\n\n### Specify type in Ad resources\n\nv8 adds an `Ad Type` column to [Ad](/display-video/api/structured-data-file/v8/AdGroupAd) files, which surfaces the type of\nAd represented by each row. This new column is required and will be populated\nfor existing resources when downloading v8 Ad files.\n\nWhen updating existing Ads, the value of this column shouldn't be changed.\n\nWhen creating new Ads, you must populate this column with one of the values\nlisted in the column description.\n\n### Update logic for Demand Gen resources\n\nv8 supports the creation, retrieval, and updating of Demand Gen campaigns using\n[Line Item](/display-video/api/structured-data-file/v8/LineItem), [Ad Group](/display-video/api/structured-data-file/v8/AdGroup), and [Ad](/display-video/api/structured-data-file/v8/AdGroupAd) files. Demand\nGen resources use different logic for timestamp verification, require the\npopulation of additional columns, and are limited by new restrictions across the\nthree file types.\n\n#### Timestamp verification\n\nFor all non-Demand-Gen line items, the `Timestamp` column of a [Line\nItem](/display-video/api/structured-data-file/v8/LineItem) file is populated at download with the last time a line item\nwas modified. This value is used when updating a line item using SDF to verify\nthat a line item has not been updated since the original file was downloaded. If\nso, the update fails.\n\nFor Demand Gen line items, the `Timestamp` column and the accompanying\nverification works differently. For Demand Gen line item entries, the column is\npopulated with the current time at download. On upload, Display \\& Video 360\nchecks if it has been more than 24 hours since the given timestamp. If it has\nbeen more than 24 hours, the original file entry is considered stale and the\nupdate fails. If this happens, download the file again and make your updates\nbased on the more recent version. *This new verification method does not prevent\nyou from overwriting changes made in the last 24 hours. To avoid accidental\noverwrites, only include Demand Gen line items that you want to update in files\nthat you upload.*\n\n#### Required columns\n\nThe following file types have columns that are now required for certain Demand\nGen resources, in addition to the columns that are required for all entities of\nthat file type.\n| **Note:** Other columns not listed here may be required when *updating* Demand Gen resources. See the v8 reference documentation for [Line Item](/display-video/api/structured-data-file/v8/LineItem), [Ad\n| Group](/display-video/api/structured-data-file/v8/AdGroup), and [Ad](/display-video/api/structured-data-file/v8/AdGroupAd) file types for an exhaustive list of requirements for each column.\n\n##### Line Item\n\n| Required columns for the following [Line Item](/display-video/api/structured-data-file/v8/LineItem) `Type` column values ||\n|------------|-----------------------------------------------------------------------------------------------------------------------------------------|\n| Demand Gen | |-------------------------------| | `Pacing Amount` | | `TrueView Bid Strategy Type` | | `TrueView Bid Strategy Value` | |\n\n##### Ad\n\n| Required columns for the following [Ad](/display-video/api/structured-data-file/v8/AdGroupAd) `Ad Type` column values ||\n|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Demand Gen Carousel | |--------------------------| | `Business Name` | | `Call to Action` | | `Demand Gen Cards` | | `Description 1` | | `Headline` | | `In-feed Video Headline` | | `Landing Page URL` | | `Logo Asset IDs` | |\n| Demand Gen Image | |----------------------------| | `Business Name` | | `Call to Action` | | `Description 1` | | `Headline` | | `In-feed Video Headline` | | `Landing Page URL` | | `Logo Asset IDs` | | `Marketing Image Asset Id` | |\n| Demand Gen Product | |--------------------------| | `Business Name` | | `Description 1` | | `Headline` | | `In-feed Video Headline` | | `Landing Page URL` | | `Logo Asset IDs` | |\n| Demand Gen Video | |--------------------------| | `Business Name` | | `Call to Action` | | `Description 1` | | `Headline` | | `In-feed Video Headline` | | `Landing Page URL` | | `Logo Asset IDs` | | `Video Id` | |\n\n#### Updated restrictions\n\nIn addition to the new required columns for certain Demand Gen Line Items and\nAds, multiple columns across [Line Item](/display-video/api/structured-data-file/v8/LineItem), [Ad Group](/display-video/api/structured-data-file/v8/AdGroup), and\n[Ad](/display-video/api/structured-data-file/v8/AdGroupAd) file types have new use restrictions that apply to Demand Gen\nresources.\n\nThese restrictions are numerous and specific to the columns in question, so this\nguide doesn't provide an exhaustive list of restrictions. We recommend that you\nclosely read the v8 reference documentation for [Line Item](/display-video/api/structured-data-file/v8/LineItem), [Ad\nGroup](/display-video/api/structured-data-file/v8/AdGroup), and [Ad](/display-video/api/structured-data-file/v8/AdGroupAd) file types before creating or updating\nDemand Gen resources using SDF upload."]]
