ภาพรวม

ไฟล์ข้อมูลที่มีโครงสร้าง (SDF) เป็นค่าที่คั่นด้วยคอมมา (CSV) ที่มีรูปแบบพิเศษ ที่ใช้ในการดึงและอัปเดตข้อมูลเกี่ยวกับ Display และ แหล่งข้อมูลของวิดีโอ 360 ใน จำนวนมาก ผ่านดิสเพลย์และ Video 360 API ให้คุณสร้างและดาวน์โหลด SDF ที่กำหนดเอง ช่วยให้คุณเรียกดูข้อมูลที่จัดระเบียบและกรองแล้วบนเครือข่ายดิสเพลย์ วิดีโอ 360 ที่ไม่ซับซ้อน

คู่มือนี้จะอธิบายวิธีสร้างการดำเนินการดาวน์โหลด SDF โปรดติดตามการดำเนินการดังกล่าว และดาวน์โหลด SDF ที่ได้

ดูข้อมูลเกี่ยวกับรูปแบบและการกำหนดเวอร์ชัน SDF ได้ที่ เอกสารอ้างอิง SDF

สร้างงาน

SDF สร้างขึ้นโดยการดำเนินการแบบไม่พร้อมกันที่เรียกว่า sdfdownloadtask เมื่อสร้างงานนี้ คุณจะต้องระบุพารามิเตอร์เกี่ยวกับ SDF ที่ต้องการ ซึ่งทำโดยใช้เมธอด sdfdownloadtasks.create ส่วนย่อยต่อไปนี้จะอธิบายพารามิเตอร์ที่คุณสามารถตั้งค่า

ระบุเวอร์ชัน

รูปแบบไฟล์ข้อมูลที่มีโครงสร้างได้รับการอัปเดตอย่างสม่ำเสมอโดยไม่ขึ้นอยู่กับ ดิสเพลย์และ API ของ Video 360 ที่มีการเผยแพร่เวอร์ชันใหม่และเวอร์ชันเก่า เลิกใช้งานเป็นประจำ ด้วยเหตุนี้จึง แนะนำให้ผู้ใช้ใช้ SDF เวอร์ชันล่าสุดเสมอ

ตั้งค่าเวอร์ชัน SDF ของ SDF ที่ต้องการโดยใช้ version ในส่วนเนื้อหาของคำขอ หากไม่ได้ตั้งค่าหรือตั้งค่า เป็น SDF_VERSION_UNSPECIFIED งานจะใช้เวอร์ชัน SDF เริ่มต้นของ ทรัพยากรของผู้ลงโฆษณาหรือพาร์ทเนอร์ที่ใช้เป็นบริบทของเนื้อหา SDF

หมายเหตุ: ทรัพยากรของพาร์ทเนอร์แต่ละรายการจะมีเวอร์ชัน SDF เริ่มต้นที่กำหนดค่าไว้ใน "รายละเอียดพื้นฐาน" การตั้งค่าใน API เว้นแต่จะกำหนดค่าเป็นอย่างอื่น ผู้ลงโฆษณาจะได้รับค่าเริ่มต้นนี้จากพาร์ทเนอร์หลัก

กำหนดบริบท

คุณสามารถสร้าง SDF ที่มีข้อมูลจากทรัพยากรทั้งหมดที่ใช้ได้ แต่ SDF แต่ละรายการจะแสดงเนื้อหาได้ภายในบริบทของ SDF เท่านั้น พาร์ทเนอร์หรือผู้ลงโฆษณา บริบทนี้ได้รับการกำหนดในเนื้อหาคำขอตาม partnerId หรือ advertiserId 1 ใน 2 อย่างนี้นะ ต้องตั้งค่า

เฉพาะทรัพยากรในบริบทที่กำหนดเท่านั้นที่จะรวมอยู่ใน SDF ที่ได้ หากพยายามกรองตามทรัพยากรที่ไม่ได้เป็นเจ้าของของพาร์ทเนอร์ที่ระบุ หรือผู้ลงโฆษณา ทั้งคู่สัญญาและเนื้อหาภายใต้ข้อมูลนี้จะไม่รวมอยู่ใน ผลลัพธ์ หากกรองโดยใช้ทรัพยากรที่ไม่ได้รวมไว้เหล่านี้เท่านั้น ไฟล์ที่ได้ จะว่างเปล่า กำลังพยายามกรองตามทรัพยากรที่อยู่นอกบริบทที่ระบุ จะไม่แสดงผลข้อผิดพลาด ดังนั้นโปรดตรวจสอบว่าบริบทของคุณ ถูกต้อง

เลือกตัวกรองที่เหมาะสม

นอกจากชุดบริบทข้างต้นแล้ว คุณสามารถกรองขอบเขตของ ไฟล์ข้อมูลที่มีโครงสร้างที่สร้างขึ้นโดยการระบุประเภทไฟล์ที่คุณต้องการ สร้าง และทรัพยากรเฉพาะหรือกลุ่มทรัพยากรที่คุณต้องการรวมไว้

หมายเหตุ: ประเภทไฟล์ข้อมูลที่มีโครงสร้างจะกำหนดประเภททรัพยากรที่แสดง ไฟล์นั้น ไฟล์แต่ละประเภทมีโครงสร้างคอลัมน์ที่แตกต่างกัน เพื่อแสดงข้อมูลที่พร้อมใช้งานสำหรับทรัพยากรนั้นๆ

มีตัวกรองที่พร้อมใช้งาน 3 รายการสำหรับ sdfdownloadtask โดยแต่ละรายการรองรับ ประเภทข้อกำหนดเฉพาะ คุณกำหนดได้เพียง 1 รายการเท่านั้น 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 ออบเจ็กต์การดำเนินการจะ ส่งคืนแล้ว การดำเนินการนี้จะแสดงสถานะของ SDF แบบอะซิงโครนัสของคุณ การสร้างข้อมูลในขณะที่สร้าง คุณสามารถตรวจสอบการดำเนินการเพื่อ ดูว่าเนื้อหาเสร็จสมบูรณ์แล้วและพร้อมให้ดาวน์โหลดไหม หรือมีข้อผิดพลาดโดยใช้ เมธอด sdfdownloadtasks.operations.get

หมายเหตุ: การดำเนินการอาจใช้เวลา ทั้งนี้ขึ้นอยู่กับขนาดของ SDF ที่สร้างขึ้น ตั้งแต่เพียงไม่กี่วินาที ไปจนถึงไม่กี่ชั่วโมง วิธีประหยัดโควต้า เริ่มใช้ Exponential Backoff ดังเช่นที่แสดงในตัวอย่างโค้ดด้านล่าง

เมื่อเสร็จสิ้น การดำเนินการที่แสดงผลจะมีค่าที่ไม่ใช่ Null 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']
);