סקירה כללית

קובצי נתונים מובנים (SDF) הם ערכים מופרדים בפסיקים (CSV) בפורמט מיוחד קבצים שמשמשים לאחזור ולעדכון של נתונים לגבי רשת המדיה ו- משאבי Video 360 ב: בכמות גדולה. דרך התצוגה Video 360 API, אפשר ליצור ולהוריד קובצי SDF מותאמים אישית, שמאפשר לך לאחזר נתונים מסודרים ומסוננים מקמפיינים לרשת המדיה וידאו 360 במשאבי אנוש.

במדריך זה מתואר כיצד ליצור פעולה של הורדת SDF, למעקב אחר ונוריד את קובצי ה-SDF שמתקבלים.

מידע בנוגע לפורמט ולניהול גרסאות של SDF זמין בקטע מסמכי עזר של SDF.

צור משימה

מזהי SDF נוצרים על ידי פעולה אסינכרונית, שנקראת sdfdownloadtask. כשיוצרים את המשימה, מגדירים את הפרמטרים שקשורים ל-SDF הרצויים. עושים זאת באמצעות השיטה sdfdownloadtasks.create. בקטעי המשנה הבאים מתוארים הפרמטרים שאפשר להגדיר.

ציון גרסה

הפורמט של קובץ הנתונים המובְנים מתעדכן באופן קבוע בנפרד תצוגה ו Video 360 API, עם גרסאות חדשות וגרסאות ישנות הוצאה משימוש באופן קבוע. לכן מומלץ מומלץ תמיד למשתמשים להשתמש בגרסה העדכנית ביותר של SDF.

מגדירים את גרסת ה-SDF של ה-SDF הרצוי באמצעות השדה version בגוף הבקשה. אם המאפיין לא מוגדר או מוגדר עד SDF_VERSION_UNSPECIFIED, המשימה תשתמש בגרסת ברירת המחדל של SDF משאב של שותף או מפרסם שמשמשים כהקשר של תוכן ה-SDF.

הערה: לכל משאב של שותף יש גרסת SDF שמוגדרת כברירת מחדל ומוגדרת "פרטים בסיסיים" הגדרות ב-API. אלא אם הוגדר אחרת, מפרסמים יורשים את ברירת המחדל הזו מהשותף ההורה שלהם.

הגדרת ההקשר

אפשר ליצור SDF שמכיל נתונים בכל המשאבים שזמינים לכם, אבל כל SDF יכול להחזיר תוכן רק בהקשר של שותף או מפרסם. הקשר זה מוגדר בגוף הבקשה על ידי partnerId או שדה advertiserId. בדיוק אחד מהשניים האלה צריך להגדיר שדות.

רק משאבים בהקשר הנתון ייכללו ב-SDF שיתקבל. אם אתם מנסים לסנן לפי משאב שאינו בבעלות השותף שצוין או של המפרסם, הוא או התוכן שמתחתיו לא ייכללו תוצאות. אם מסננים רק לפי המשאבים שלא כלולים, הקבצים שיתקבלו תהיה ריקה. ניסיון לסנן לפי משאבים שלא בהקשר הנתון לא יחזיר הודעת שגיאה, לכן חשוב לבדוק שההקשר נכון.

בוחרים את המסנן הנכון

בנוסף להקשר שהוגדר למעלה, אפשר לסנן עוד יותר את ההיקף של שנוצרו קובצי נתונים מובנים על ידי ציון סוגי הקבצים יוצרים את המשאבים או את משפחת המשאבים הספציפיים שרוצים לכלול.

הערה: הסוג של קובץ נתונים מובְנים קובע את סוג המשאב שאפשר לאכלס . לכל סוג קובץ יש מבנה עמודות שונה שמשקף את המידע שזמין לאותו משאב.

יש שלושה מסננים זמינים ל-sdfdownloadtask, כל אחד מהם מיועד סוג מפרט מסוים. אפשר להקצות רק אירוע אחד sdfdownloadtask

ParentEntityFilter

הערך ParentEntityFilter הוא הרחב ביותר מבין מסננים.

בשדה fileType אפשר להציג את כל סוגי הקבצים שרוצים ליצור במשימה. הדבר חובה. אם השדה יישאר ריק או מוגדר לערך FILE_TYPE_UNSPECIFIED, הערך הפעולה sdfdownloadtask תושלם בטעות.

באמצעות filterType filterIds שדות. אפשר לצמצם את התוצאות עוד יותר. filterType מציין את הסוג של משאבים לסינון לפי וגם filterIds מזהה את המשאבים באמצעות המזהה הייחודי שלהם. ממשקי ה-SDF שיתקבלו יכללו המשאבים שמזוהים על ידי fileType שהם את המשאבים או הצאצאים של המשאבים שמזוהים filterType וfilterIds.

הערה: FILTER_TYPE_NONE לא יחיל מסנן על המשימה, אבל הוא רק רלוונטי כאשר צוין advertiserId. אחרת, תוחזר שגיאה במהלך היצירה של sdfdownloadtask.

IdFilter

IdFilter מסננת את הבקשה כדי לכלול רק את המשאבים זוהה.

IdFilter כולל שדה לכל סוג SDF, לא כולל מלאי שטחי פרסום מקור. כל אחד מהשדות האלו הוא רשימה של מזהים ייחודיים שמזהים את למשאבים ספציפיים שהיית רוצה לכלול ב-SDF שנוצר. המזהים שסופקו חייבות להיות במסגרת ההקשר, אבל לא חייב להיות קשר ישיר. שלך אין צורך לבקש קמפיין מסוים כדי לבקש פריט מכיל/ה ולהיפך. סוגי הקבצים היחידים שייווצרו יהיו מהם שתואמים למשאבים המזוהים בIdFilter.

InventorySourceFilter

ב-InventorySourceFilter אפשר רק לסנן והורדה של קובצי SDF שמכילים משאבים של מקור המלאי. הוא היחיד מסנן שבו אפשר להשתמש כדי לקבל מידע על המשאבים של מקור המלאי.

ל-InventorySourceFilter יש יחיד שדה inventorySourceIds שבו מזהים את המזהים של משאבי המקור של המלאי שאתם רוצים לכלול ב-SDF. אם הרשימה שסופקה ל-inventorySourceIds ריקה, כל מקורות של מלאי שטחי פרסום במסגרת ההקשר שהוגדר ייכללו ב-SDF שייווצר.

שליחת בקשה

אחרי שתכירו את הפרמטרים של ה-SDF הרצוי, תוכלו ליצור את הבקשה ויוצרים את sdfdownloadtask.

אזהרה: למשתמש אחד מוגבל ל-20 sdfdownloadtasks שפועלים בכל זמן נתון. פעם אחת. ניסיונות ליצור כותרות נוספות יחזירו שגיאה.

הנה דוגמה לאופן שבו יוצרים 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.

הערה: בהתאם לגודל של קובצי ה-SDF שנוצרים, הפעולה יכולה להימשך ממספר שניות ואפילו שעות. כדי לשמר את המכסה, יוצרת השהיה מעריכית לפני ניסיון חוזר (exponential backoff), כמו זו שמופיעה בדוגמת הקוד שבהמשך.

בסיום, הערך של הפעולה שהוחזרה יהיה done. הפעולה הסופית תכלול 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']
);