หน้านี้ได้รับการแปลโดย Cloud Translation API

ภาพรวม

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

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

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

สร้างงาน

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

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

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

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

กำหนดบริบท

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

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

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

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

sdfdownloadtask มีตัวกรองที่ใช้ได้ 3 รายการ โดยแต่ละรายการมีไว้สำหรับประเภทข้อกำหนดเฉพาะ คุณกำหนดได้เพียงรายการเดียวสำหรับ sdfdownloadtask 1 รายการ

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 ระบบจะแสดงผลออบเจ็กต์ operation การดำเนินการนี้จะแสดงสถานะของการดำเนินการสร้าง 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']
);

ดาวน์โหลดไฟล์