ไฟล์ข้อมูลที่มีโครงสร้าง (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'] );