קבצים של נתונים מובְנים (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 הרצויה באמצעות השדה 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, למעט Inventory
Source. כל אחד מהשדות האלה הוא רשימה של מזהים ייחודיים שמציינים את המשאבים הספציפיים שרוצים לכלול בקובץ ה-SDF שנוצר. המזהים שצוינו צריכים להיות בתוך קבוצת ההקשר, אבל לא בהכרח קשורים ישירות. לא צריך לבקש קמפיין מסוים כדי לבקש פריט הזמנה שהוא מכיל, ולהפך. סוגי הקבצים שייווצרו יהיו רק אלה שתואמים למשאבים שזוהו ב-IdFilter
.
InventorySourceFilter
InventorySourceFilter
מאפשר רק סינון והורדה של קובצי SDF שמכילים משאבים של מקורות מלאי שטחי פרסום. זה המסנן היחיד שאפשר להשתמש בו כדי לקבל מידע על משאבי מקור המלאי.
InventorySourceFilter
כולל שדה יחיד inventorySourceIds
שבו מציינים את המזהים הייחודיים של משאבי מקור המלאי שרוצים לכלול ב-SDF. אם הרשימה שסופקה ל-inventorySourceIds
ריקה, כל מקורות מלאי שטחי הפרסום בהקשר שמוגדר ייכללו בקובץ ה-SDF שנוצר.
שליחת בקשה
אחרי שמגדירים את הפרמטרים של קובץ ה-SDF הרצוי, אפשר ליצור את הבקשה וליצור את sdfdownloadtask
.
דוגמה ליצירת sdfdownloadtask
באמצעות ParentEntityFilter
:
Java
// 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());
Python
# 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
, מוחזר אובייקט operation. הפעולה הזו מייצגת את הסטטוס של פעולת יצירת ה-SDF האסינכרונית בזמן היצירה. אפשר לבדוק אם הפעולה הושלמה ומוכנה להורדה, או אם היא החזירה שגיאה, באמצעות השיטה sdfdownloadtasks.operations.get
.
בסיום, הפעולה שמוחזרת תכלול שדה done
שאינו null. הפעולה שהסתיימה תכלול את השדה response
או error
. אם השדה error
קיים, הוא יכיל אובייקט Status
עם קוד שגיאה והודעה, שבהם מפורטים פרטי השגיאה שהתרחשה. אם השדה response
קיים, הוא יכיל אובייקט עם ערך resourceName
שמזהה את הקובץ שנוצר להורדה.
הנה דוגמה לאופן שבו אפשר לבדוק את הבקשה באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff):
Java
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());
Python
# 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'] );