Tổng quan

Tệp dữ liệu có cấu trúc (SDF) là giá trị được phân tách bằng dấu phẩy (CSV) có định dạng đặc biệt các tệp dùng để truy xuất và cập nhật dữ liệu về chiến dịch Hiển thị & Tài nguyên video 360 trong hàng loạt. Thông qua Mạng Hiển thị và Video 360 API, bạn có thể tạo và tải các tệp SDF tuỳ chỉnh xuống, cho phép bạn truy xuất dữ liệu có tổ chức và đã lọc trên Mạng hiển thị và Video 360 của chúng tôi.

Hướng dẫn này mô tả cách tạo thao tác Tải xuống SDF, hãy theo dõi và tải các tệp SDF thu được xuống.

Bạn có thể tìm thông tin về định dạng và phiên bản của SDF trong Tài liệu tham khảo về SDF.

Tạo việc cần làm

SDF được tạo bởi một hoạt động không đồng bộ, được gọi là sdfdownloadtask. Khi tạo nhiệm vụ này, bạn xác định các tham số liên quan đến SDF mong muốn. Việc này được thực hiện thông qua phương thức sdfdownloadtasks.create. Chiến lược phát hành đĩa đơn các tiểu mục sau mô tả các tham số 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 Hiển thị và Video 360 API, với các phiên bản mới phát hành và phiên bản cũ không dùng nữa. Vì lý do này, luôn khuyến nghị người dùng sử dụng phiên bản mới nhất của SDF.

Bạn đặt phiên bản SDF của SDF mà mình muốn bằng cách sử dụng Trường version trong nội dung yêu cầu. Nếu chưa đặt hoặc đặt chưa vào SDF_VERSION_UNSPECIFIED, tác vụ sẽ sử dụng phiên bản SDF mặc định của tài nguyên của nhà quảng cáo hoặc đối tác được dùng làm ngữ cảnh của nội dung SDF.

Thiết lập bối cảnh

Bạn có thể tạo một tệp SDF chứa dữ liệu của bất kỳ tài nguyên nào bạn có thể sử dụng, nhưng bất kỳ tệp SDF nào cũng chỉ có thể trả về nội dung trong ngữ cảnh của một đối tác hoặc nhà quảng cáo. Ngữ cảnh này được xác định trong nội dung yêu cầu bằng partnerId hoặc advertiserId. Chính xác là một trong hai câu trả lời này phải đặt.

Chỉ những tài nguyên trong bối cảnh cụ thể mới được đưa vào tệp SDF thu được. 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 đã chỉ định hoặc nhà quảng cáo, thì cả nội dung đó và nội dung trong đó đều không được đưa vào kết quả. Nếu chỉ lọc theo những tài nguyên không được bao gồm này, các tệp thu được sẽ trống. Cố gắng lọc theo những tài nguyên không có trong ngữ cảnh cụ thể sẽ không trả về lỗi, vì vậy hãy nhớ kiểm tra xem ngữ cảnh của bạn có chính xác.

Chọn bộ lọc phù hợp

Ngoài bộ ngữ cảnh ở trên, bạn có thể lọc thêm phạm vi của được tạo Tệp dữ liệu có cấu trúc bằng cách chỉ định loại tệp bạn muốn tạo và các tài nguyên cụ thể hoặc nhóm tài nguyên mà bạn muốn đưa vào.

Có ba bộ lọc cho sdfdownloadtask, mỗi bộ lọc đáp ứng một loại thông số kỹ thuật cụ thể. Bạn chỉ có thể chỉ định một lần cho một sdfdownloadtask.

ParentEntityFilter

ParentEntityFilter là biến thể rộng nhất trong số các bộ lọc.

Bằng cách sử dụng trường fileType, bạn có thể liệt kê tất cả những giá trị mà bạn muốn loại tệp mà bạn muốn tạo bằng công việc của mình. Đây là là bắt buộc và nếu để trống hoặc đặt thành FILE_TYPE_UNSPECIFIED, sdfdownloadtask sẽ hoàn tất do lỗi.

Sử dụng filterType và filterIds, bạn có thể tinh chỉnh thêm kết quả của mình. filterType chỉ định loại của tài nguyên để lọc theo và filterIds sẽ xác định các tài nguyên đó theo mã nhận dạng duy nhất của chúng. SDF thu được sẽ bao gồm những tài nguyên do fileType xác định là: các tài nguyên hoặc phần tử con của những tài nguyên được xác định bởi filterType và filterIds.

IdFilter

IdFilter lọc yêu cầu của bạn để chỉ bao gồm các tài nguyên xác định.

IdFilter có một trường cho mọi loại SDF, ngoại trừ Khoảng không quảng cáo Nguồn. Mỗi trường trong số này là một danh sách các mã duy nhất nhận dạng những tài nguyên cụ thể mà bạn muốn đưa vào tệp SDF đã tạo. Các mã nhận dạng được cung cấp phải nằm trong ngữ cảnh đã đặt, 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 chứa và ngược lại. Loại tệp duy nhất được tạo sẽ là các loại tệp đó tương ứng với tài nguyên được xác định trong IdFilter.

InventorySourceFilter

InventorySourceFilter chỉ cho phép lọc và tải xuống SDF chứa tài nguyên Nguồn khoảng không quảng cáo. API này là nền tảng duy nhất bạn có thể sử dụng để nhận thông tin về tài nguyên Nguồn khoảng không quảng cáo của mình.

InventorySourceFilter có một số ít inventorySourceIds, nơi bạn xác định duy nhất Mã của các tài nguyên nguồn khoảng không quảng cáo mà bạn muốn đưa vào SDF. Nếu danh sách được cung cấp cho inventorySourceIds trống, tất cả các nguồn khoảng không quảng cáo theo ngữ 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 mong muốn, bạn có thể tạo yêu cầu và tạo sdfdownloadtask.

Dưới đây là ví dụ về cách tạo sdfdownloadtask bằng cách sử dụ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 của bạn và nhận đường dẫn tải xuống

Khi bạn tạo sdfdownloadtask, đối tượng toán tử sẽ được bị trả lại. Thao tác này thể hiện trạng thái của SDF không đồng bộ tại thời điểm tạo. Bạn có thể kiểm tra hoạt động của mình để để xem liệu tệp đã hoàn tất và sẵn sàng để tải xuống chưa hoặc có báo lỗi hay không, bằng cách sử dụng phương thức sdfdownloadtasks.operations.get.

Sau khi kết thúc, thao tác được trả về sẽ có một giá trị không rỗng Trường done. Thao tác hoàn tất sẽ bao gồm response hoặc error . Nếu có, trường error sẽ có Status chứa mã lỗi và thông báo, cung cấp chi tiết về lỗi mà đã xảy ra. Nếu có trường response, trường này sẽ có một đối tượng có giá trị resourceName xác định thuộc tính được tạo để tải xuống.

Dưới đây là ví dụ về cách kiểm tra yêu cầu của bạn bằng thuật toán 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']
);
Tiếp
Tải tệp xuống