ไฟล์ 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'] );