فایلهای دادههای ساختاریافته (SDF) فایلهایی با فرمت خاص با مقدار جدا شده با کاما (CSV) هستند که برای بازیابی و بهروزرسانی دادههای مربوط به منابع Display & Video 360 به صورت انبوه استفاده میشوند. از طریق Display & Video 360 API، میتوانید SDFهای سفارشیسازیشده را تولید و دانلود کنید، که به شما امکان میدهد دادههای سازمانیافته و فیلتر شده را در منابع Display & Video 360 خود بازیابی کنید.
این راهنما نحوه ایجاد عملیات دانلود SDF، ردیابی آن عملیات و دانلود SDF های حاصل را شرح می دهد.
اطلاعات مربوط به قالب و نسخه SDF را می توان در اسناد مرجع SDF یافت.
یک کار ایجاد کنید
SDF ها توسط یک عملیات ناهمزمان به نام sdfdownloadtask
تولید می شوند. هنگام ایجاد این وظیفه، پارامترهای مربوط به SDF های مورد نظر خود را تعریف می کنید. این کار از طریق متد sdfdownloadtasks.create
انجام می شود. در زیر بخش های زیر پارامترهایی را که می توانید تنظیم کنید توضیح می دهد.
یک نسخه را مشخص کنید
قالب فایل داده ساختاریافته به طور منظم مستقل از Display & Video 360 API بهروزرسانی میشود، با نسخههای جدید منتشر شده و نسخههای قدیمی به طور منظم منسوخ میشوند . به همین دلیل، همیشه توصیه می شود که کاربران از جدیدترین نسخه SDF استفاده کنند .
شما نسخه SDF SDF مورد نظر خود را با استفاده از قسمت version
در بدنه درخواست تنظیم می کنید. اگر روی SDF_VERSION_UNSPECIFIED
تنظیم یا تنظیم نشود، این کار از نسخه پیشفرض SDF تبلیغکننده یا منبع شریک استفاده میکند که به عنوان زمینه محتوای SDF استفاده میشود.
زمینه را تنظیم کنید
شما میتوانید یک SDF حاوی دادههای مربوط به هر منبعی که در دسترس شماست تولید کنید، اما هر SDF فردی فقط میتواند محتوا را در چارچوب یک شریک یا تبلیغکننده بازگرداند. این زمینه در بدنه درخواست توسط قسمت partnerId
یا advertiserId
تعریف شده است. دقیقا یکی از این دو فیلد باید تنظیم شود.
فقط منابع در چارچوب داده شده در SDF حاصل گنجانده خواهد شد. اگر سعی کنید منبعی را فیلتر کنید که متعلق به شریک یا تبلیغکننده مشخصشده نیست، نه آن و نه محتوای زیر آن در نتایج گنجانده نمیشود. اگر فقط توسط این منابع نامشخص فیلتر شود، فایل های حاصل خالی خواهند بود. تلاش برای فیلتر کردن بر اساس منابع خارج از زمینه داده شده ، خطایی را بر نمی گرداند ، بنابراین مطمئن شوید که زمینه شما درست است.
فیلتر مناسب را انتخاب کنید
علاوه بر مجموعه زمینه بالا، میتوانید با تعیین انواع فایلهایی که میخواهید تولید کنید و منابع خاص یا خانوادهای از منابعی که میخواهید شامل شود، دامنه فایلهای داده ساختاریافته خود را فیلتر کنید.
سه فیلتر در دسترس برای یک sdfdownloadtask
وجود دارد که هر کدام به نوع خاصی از مشخصات مربوط می شود. شما فقط می توانید برای یک sdfdownloadtask
تخصیص دهید.
ParentEntityFilter
ParentEntityFilter
گسترده ترین فیلتر موجود است.
با استفاده از فیلد fileType
، میتوانید تمام انواع فایلهای دلخواه را که میخواهید با کار خود ایجاد کنید، فهرست کنید. این مورد ضروری است، و اگر خالی بماند یا روی FILE_TYPE_UNSPECIFIED
تنظیم شود، sdfdownloadtask
شما به اشتباه تکمیل خواهد شد.
با استفاده از فیلدهای filterType
و filterIds
، می توانید نتایج خود را بیشتر اصلاح کنید. filterType
نوع منابعی را برای فیلتر کردن مشخص می کند و filterIds
آن منابع را با شناسه منحصر به فردشان شناسایی می کند. SDFهای به دست آمده شامل منابع شناسایی شده توسط fileType
هستند که یا منابع یا فرزندان منابع شناسایی شده توسط filterType
و filterIds
هستند.
IDFilter
IdFilter
درخواست شما را فیلتر می کند تا فقط شامل منابع شناسایی شده باشد.
IdFilter
برای هر نوع SDF، به استثنای منبع موجودی، یک فیلد دارد. هر یک از این فیلدها فهرستی از شناسههای منحصربهفرد است که منابع خاصی را که میخواهید در SDF ایجاد شده خود بگنجانید، شناسایی میکند. شناسه های ارائه شده باید در مجموعه زمینه باشند، اما نیازی به ارتباط مستقیم ندارند. برای درخواست یک کمپین خاص، نیازی به درخواست یک کمپین خاص ندارید و بالعکس. تنها انواع فایل های تولید شده مربوط به منابع شناسایی شده در IdFilter
خواهد بود.
InventorySourceFilter
InventorySourceFilter
فقط اجازه فیلتر کردن و دانلود SDF های حاوی منابع Inventory Source را می دهد. این تنها فیلتری است که می توانید برای دریافت اطلاعات در مورد منابع منبع موجودی خود از آن استفاده کنید.
InventorySourceFilter
دارای یک فیلد inventorySourceIds
منحصر به فرد است که در آن شناسه های منحصر به فرد منابع منبع موجودی را که می خواهید در SDF خود قرار دهید شناسایی می کنید. اگر لیست ارائه شده به inventorySourceIds
خالی باشد، تمام منابع موجودی تحت شرایط تنظیم شده در SDF ایجاد شده گنجانده می شود.
درخواست بدهید
هنگامی که پارامترهای SDF مورد نظر خود را دانستید، می توانید درخواست را بسازید و sdfdownloadtask
را ایجاد کنید.
در اینجا مثالی از نحوه ایجاد یک sdfdownloadtask
با استفاده از ParentEntityFilter
آورده شده است:
جاوا
// Create the filter structure ParentEntityFilter parentEntityFilter = new ParentEntityFilter(); parentEntityFilter.setFileType(sdf-file-type-list); parentEntityFilter.setFilterType(sdfFilterType); parentEntityFilter.setFilterIds(filter-id-list); // Configure the sdfdownloadtasks.create request Sdfdownloadtasks.Create request = service .sdfdownloadtasks() .create( new CreateSdfDownloadTaskRequest() .setVersion(sdfVersion) .setAdvertiserId(advertiserId) .setParentEntityFilter(parentEntityFilter) ); // Create the sdfdownloadtask Operation operationResponse = request.execute(); System.out.printf("Operation %s was created.\n", operationResponse.getName());
پایتون
# Configure the sdfdownloadtasks.create request createSdfDownloadTaskRequest = { 'version': sdf-version, 'advertiserId': advertiser-id, 'parentEntityFilter': { 'fileType': sdf-file-type-list, 'filterType': sdf-filter-type, 'filterIds': filter-id-list } } # Create the sdfdownloadtask operation = service.sdfdownloadtasks().create( body=createSdfDownloadTaskRequest).execute(); print("Operation %s was created." % operation["name"])
PHP
// Create the sdfdownloadtasks.create request structure $createSdfDownloadTaskRequest = new Google_Service_DisplayVideo_CreateSdfDownloadTaskRequest(); $createSdfDownloadTaskRequest->setAdvertiserId(advertiser-id); $createSdfDownloadTaskRequest->setVersion(sdf-version); // Create and set the parent entity filter $parentEntityFilter = new Google_Service_DisplayVideo_ParentEntityFilter(); $parentEntityFilter->setFileType(sdf-file-type-list); $parentEntityFilter->setFilterType(sdf-filter-type); if (!empty(filter-id-list)) { $parentEntityFilter->setFilterIds(filter-id-list); } $createSdfDownloadTaskRequest->setParentEntityFilter($parentEntityFilter); // Call the API, creating the SDF Download Task. $operation = $this->service->sdfdownloadtasks->create( $createSdfDownloadTaskRequest ); printf('Operation %s was created.\n', $operation->getName());
درخواست خود را بررسی کنید و مسیر دانلود را دریافت کنید
هنگامی که یک sdfdownloadtask
ایجاد می کنید، یک شی عملیات برگردانده می شود. این عملیات نشان دهنده وضعیت عملیات تولید SDF ناهمزمان شما در زمان ایجاد است. با استفاده از روش sdfdownloadtasks.operations.get
میتوانید عملیات خود را بررسی کنید تا ببینید آیا کامل شده و آماده دانلود است یا خطایی ایجاد کرده است.
پس از اتمام، عملیات برگشتی دارای یک فیلد غیر done
خواهد بود. عملیات تمام شده شامل یک قسمت response
یا error
خواهد بود. در صورت وجود، فیلد error
دارای یک شیء Status
است که حاوی یک کد خطا و پیام است که جزئیات خطای رخ داده را ارائه می دهد. اگر فیلد response
موجود باشد، یک شی با مقدار resourceName
خواهد داشت که فایل تولید شده را برای دانلود شناسایی می کند.
در اینجا مثالی از نحوه بررسی درخواست خود با استفاده از عقب نشینی نمایی آورده شده است:
جاوا
String operationName = operationResponse.getName(); // Configure the Operations.get request Sdfdownloadtasks.Operations.Get operationRequest = service .sdfdownloadtasks() .operations() .get(operationName); // Configure exponential backoff for checking the status of our operation ExponentialBackOff backOff = new ExponentialBackOff.Builder() .setInitialIntervalMillis(5000) // setting initial interval to five seconds .setMaxIntervalMillis(300000) // setting max interval to five minutes .setMaxElapsedTimeMillis(18000000) // setting max elapsed time to five hours .build(); while (operationResponse.getDone() == null) { long backoffMillis = backOff.nextBackOffMillis(); if (backoffMillis == ExponentialBackOff.STOP) { System.out.printf("The operation has taken more than five hours to complete.\n"); return; } Thread.sleep(backoffMillis); // Get current status of operation operationResponse = operationRequest.execute(); } // Check if the operation finished with an error and return if (operationResponse.getError() != null) { System.out.printf("The operation finished in error with code %s: %s\n", operationResponse.getError().getCode(), operationResponse.getError() .getMessage()); return; } System.out.printf( "The operation completed successfully. Resource %s was created.\n", operationResponse.getResponse().get("resourceName").toString());
پایتون
# The following values control retry behavior while # the report is processing. # Minimum amount of time between polling requests. Defaults to 5 seconds. min_retry_interval = 5 # Maximum amount of time between polling requests. Defaults to 5 minutes. max_retry_interval = 5 * 60 # Maximum amount of time to spend polling. Defaults to 5 hours. max_retry_elapsed_time = 5 * 60 * 60 # Configure the Operations.get request get_request = service.sdfdownloadtasks().operations().get( name=operation["name"] ) sleep = 0 start_time = time.time() while True: # Get current status of operation operation = get_request.execute() if "done" in operation: if "error" in operation: print("The operation finished in error with code %s: %s" % ( operation["error"]["code"], operation["error"]["message"])) else: print("The operation completed successfully. Resource %s was created." % operation["response"]["resourceName"]) break elif time.time() - start_time > max_retry_elapsed_time: print("Generation deadline exceeded.") sleep = next_sleep_interval(sleep) print("Operation still running, sleeping for %d seconds." % sleep) time.sleep(sleep) def next_sleep_interval(previous_sleep_interval): """Calculates the next sleep interval based on the previous.""" min_interval = previous_sleep_interval or min_retry_interval max_interval = previous_sleep_interval * 3 or min_retry_interval return min(max_retry_interval, random.randint(min_interval, max_interval))
PHP
// The following values control retry behavior // while the task is processing. // Minimum amount of time between polling requests. Defaults to 5 seconds. $minRetryInterval = 5; // Maximum amount of time between polling requests. Defaults to 5 minutes. $maxRetryInterval = 300; // Maximum amount of time to spend polling. Defaults to 5 hours. $maxRetryElapsedTime = 18000; $operationName = $operation->getName(); $sleepInterval = 0; $startTime = time(); while (!$operation->getDone()) { if ($sleepInterval != 0) { printf( 'The operation is still running, sleeping for %d seconds\n', $sleepInterval ); } // Sleep before retrieving the SDF Download Task again. sleep($sleepInterval); // Call the API, retrieving the SDF Download Task. $operation = $this->service->sdfdownloadtasks_operations->get( $operation->getName() ); // If the operation has exceeded the set deadline, throw an exception. if (time() - $startTime > $maxRetryElapsedTime) { printf('SDF download task processing deadline exceeded\n'); throw new Exception( 'Long-running operation processing deadline exceeded' ); } // Generate the next sleep interval using exponential backoff logic. $sleepInterval = min( $maxRetryInterval, rand( max($minRetryInterval, $previousSleepInterval), max($minRetryInterval, $previousSleepInterval * 3) ) ); } // If the operation finished with an error, throw an exception. if($operation->getError() !== null) { $error = $operation->getError(); printf( 'The operation finished in error with code %s: %s\n', $error->getCode(), $error->getMessage() ); throw new Exception($error->getMessage()); } // Print successfully generated resource. $response = $operation->getResponse(); printf( 'The operation completed successfully. Resource %s was ' . 'created. Ready to download.\n', $response['resourceName'] );