Tệp dữ liệu có cấu trúc (SDF) là các tệp giá trị được phân tách bằng dấu phẩy (CSV) có định dạng đặc biệt, được dùng để truy xuất và cập nhật dữ liệu về các tài nguyên trên Display & Video 360 hàng loạt. Thông qua Display & Video 360 API, bạn có thể tạo và tải SDF tuỳ chỉnh xuống, cho phép bạn truy xuất dữ liệu được sắp xếp và lọc trên các tài nguyên Display & Video 360.
Hướng dẫn này mô tả cách tạo một thao tác Tải SDF xuống, theo dõi thao tác đó và tải các SDF kết quả xuống.
Bạn có thể xem thông tin về định dạng và phiên bản SDF trong tài liệu tham khảo về SDF.
Tạo việc cần làm
SDF được tạo bằng một thao tác không đồng bộ, được gọi là sdfdownloadtask
.
Khi tạo tác vụ này, bạn sẽ xác định các tham số liên quan đến SDF mà bạn muốn.
Việc này được thực hiện thông qua phương thức sdfdownloadtasks.create
. Các tiểu mục sau đây mô tả những tham số mà bạn có thể đặt.
Chỉ định một phiên bản
Định dạng Tệp dữ liệu có cấu trúc được cập nhật thường xuyên độc lập với API Display & Video 360, với các phiên bản mới được phát hành và các phiên bản trước đó bị ngừng cung cấp thường xuyên. Vì lý do này, người dùng nên luôn sử dụng phiên bản SDF mới nhất.
Bạn đặt phiên bản SDF của SDF mà bạn muốn bằng cách sử dụng trường version
trong phần nội dung yêu cầu. Nếu bạn không đặt hoặc đặt thành SDF_VERSION_UNSPECIFIED
, thì tác vụ sẽ sử dụng phiên bản SDF mặc định của tài nguyên nhà quảng cáo hoặc đối tác được dùng làm bối cảnh của nội dung SDF.
Thiết lập bối cảnh
Bạn có thể tạo một SDF chứa dữ liệu về mọi tài nguyên mà bạn có, nhưng mỗi SDF riêng lẻ chỉ có thể trả về nội dung trong bối cảnh của một đối tác hoặc nhà quảng cáo duy nhất. Ngữ cảnh này được xác định trong nội dung yêu cầu bằng trường partnerId
hoặc advertiserId
. Bạn phải đặt đúng một trong hai trường này.
Chỉ những tài nguyên trong ngữ cảnh đã cho mới được đưa vào SDF kết quả. Nếu bạn cố gắng lọc theo một tài nguyên không thuộc sở hữu của đối tác hoặc nhà quảng cáo được chỉ định, thì tài nguyên đó và nội dung bên dưới sẽ không được đưa vào kết quả. Nếu chỉ lọc theo những tài nguyên không được đưa vào này, thì các tệp kết quả sẽ trống. Việc cố gắng lọc theo các tài nguyên bên ngoài ngữ cảnh đã cho sẽ không trả về lỗi, vì vậy, hãy nhớ kiểm tra để đảm bảo ngữ cảnh của bạn là chính xác.
Chọn bộ lọc phù hợp
Ngoài bộ bối cảnh ở trên, bạn có thể lọc thêm phạm vi của Tệp dữ liệu có cấu trúc đã tạo bằng cách chỉ định các loại tệp mà bạn muốn tạo và các tài nguyên hoặc nhóm tài nguyên cụ thể mà bạn muốn đưa vào.
Có 3 bộ lọc cho sdfdownloadtask
, mỗi bộ lọc phục vụ cho một loại thông số kỹ thuật cụ thể. Bạn chỉ có thể chỉ định một sdfdownloadtask
.
ParentEntityFilter
ParentEntityFilter
là bộ lọc rộng nhất trong số các bộ lọc hiện có.
Khi sử dụng trường fileType
, bạn có thể liệt kê tất cả các loại tệp mà bạn muốn tạo bằng tác vụ của mình. Đây là thông tin bắt buộc. Nếu bạn để trống hoặc đặt thành FILE_TYPE_UNSPECIFIED
, sdfdownloadtask
của bạn sẽ hoàn tất trong trạng thái lỗi.
Khi sử dụng các trường filterType
và filterIds
, bạn có thể tinh chỉnh thêm kết quả.
filterType
chỉ định loại tài nguyên để lọc theo và filterIds
xác định những tài nguyên đó bằng mã nhận dạng riêng biệt của chúng. Các SDF thu được sẽ bao gồm những tài nguyên do fileType
xác định, là tài nguyên hoặc tài nguyên con của những tài nguyên do filterType
và filterIds
xác định.
IdFilter
IdFilter
sẽ lọc yêu cầu của bạn để chỉ bao gồm những tài nguyên đã xác định.
IdFilter
có một trường cho mọi loại SDF, ngoại trừ Nguồn kho hàng. Mỗi trường trong số này là một danh sách gồm các mã nhận dạng duy nhất xác định những tài nguyên cụ thể mà bạn muốn đưa vào SDF đã tạo. Các mã nhận dạng được cung cấp phải nằm trong tập hợp ngữ cảnh, nhưng không cần phải liên quan trực tiếp. Bạn không cần yêu cầu một chiến dịch cụ thể để yêu cầu một mục hàng mà chiến dịch đó chứa và ngược lại. Loại tệp duy nhất được tạo sẽ là loại tệp tương ứng với các tài nguyên được xác định trong IdFilter
.
InventorySourceFilter
InventorySourceFilter
chỉ cho phép lọc và tải SDF xuống có chứa tài nguyên Nguồn khoảng không quảng cáo. Đây là bộ lọc duy nhất mà bạn có thể sử dụng để lấy thông tin về tài nguyên Nguồn khoảng không quảng cáo.
InventorySourceFilter
có một trường inventorySourceIds
duy nhất, nơi bạn xác định mã nhận dạng duy nhất của các tài nguyên nguồn kho hàng mà bạn muốn đưa vào SDF. Nếu danh sách được cung cấp cho inventorySourceIds
trống, thì tất cả các nguồn khoảng không quảng cáo trong bối cảnh đã đặt sẽ được đưa vào SDF đã tạo.
Tạo yêu cầu
Sau khi biết các tham số của SDF mà bạn muốn, bạn có thể tạo yêu cầu và tạo sdfdownloadtask
.
Sau đây là ví dụ về cách tạo sdfdownloadtask
bằng 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());
Kiểm tra yêu cầu và nhận đường dẫn tải xuống
Khi bạn tạo một sdfdownloadtask
, một đối tượng operation sẽ được trả về. Thao tác này thể hiện trạng thái của thao tác tạo SDF không đồng bộ tại thời điểm tạo. Bạn có thể kiểm tra thao tác của mình để xem thao tác đó đã hoàn tất và sẵn sàng tải xuống hay đã xảy ra lỗi bằng phương thức sdfdownloadtasks.operations.get
.
Sau khi hoàn tất, thao tác được trả về sẽ có trường done
khác rỗng. Thao tác đã hoàn tất sẽ bao gồm trường response
hoặc error
. Nếu có, trường error
sẽ có một đối tượng Status
chứa mã lỗi và thông báo, cung cấp thông tin chi tiết về lỗi đã xảy ra. Nếu có trường response
, thì trường này sẽ có một đối tượng có giá trị resourceName
xác định tệp đã tạo để tải xuống.
Sau đây là ví dụ về cách kiểm tra yêu cầu bằng cách sử dụng cơ chế thời gian đợi luỹ thừa:
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'] );