תצוגה ו אנחנו מוציאים משימוש את Video 360 API v2. שימוש בתצוגה במקום זאת, Video 360 API v3 לקבלת הוראות למעבר מגרסה 2 לגרסה 3, אפשר לעיין במדריך להעברת נתונים (מיגרציה).

דף זה תורגם על ידי Cloud Translation API.

סקירה כללית

קובצי נתונים מובְנים (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, לא כולל 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 של הפעולה שהוחזרה תהיה ערך שונה מאפס. הפעולה הסופית תכלול את השדה response או את השדה error. אם השדה error קיים, הוא יכיל אובייקט Status שמכיל קוד שגיאה והודעה עם פרטי השגיאה שהתרחשה. אם השדה response קיים, הוא יכלול אובייקט עם ערך resourceName שמזהה את הקובץ שנוצר להורדה.

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

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']
);

הורדת קבצים

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

צור משימה

ציון גרסה

הגדרת ההקשר

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

ParentEntityFilter

IdFilter

InventorySourceFilter

שליחת בקשה

Java

Python

PHP

בדיקת הבקשה וקבלת נתיב ההורדה

Java

Python

PHP

סקירה כללית