ภาพรวม

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

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

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

สร้างงาน

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

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

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

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

เว้นแต่จะกำหนดค่าเป็นอย่างอื่น

ให้บริบท

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

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

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

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

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

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

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