بررسی اجمالی

فایل‌های داده‌های ساختاریافته (SDF) فایل‌هایی با فرمت خاص با مقدار جدا شده با کاما (CSV) هستند که برای بازیابی و به‌روزرسانی داده‌های مربوط به منابع Display & Video 360 به صورت انبوه استفاده می‌شوند. از طریق Display & Video 360 API، می‌توانید SDF‌های سفارشی‌سازی‌شده را تولید و دانلود کنید، که به شما امکان می‌دهد داده‌های سازمان‌یافته و فیلتر شده را در منابع Display & Video 360 خود بازیابی کنید.

این راهنما نحوه ایجاد عملیات دانلود SDF، ردیابی آن عملیات و دانلود SDF های حاصل را شرح می دهد.

اطلاعات مربوط به قالب و نسخه SDF را می توان در اسناد مرجع SDF یافت.

یک کار ایجاد کنید

SDF ها توسط یک عملیات ناهمزمان به نام sdfdownloadtask تولید می شوند. هنگام ایجاد این وظیفه، پارامترهای مربوط به SDF های مورد نظر خود را تعریف می کنید. این کار از طریق متد sdfdownloadtasks.create انجام می شود. در زیر بخش های زیر پارامترهایی را که می توانید تنظیم کنید توضیح می دهد.

یک نسخه را مشخص کنید

قالب فایل داده ساختاریافته به طور منظم مستقل از Display & Video 360 API به‌روزرسانی می‌شود، با نسخه‌های جدید منتشر شده و نسخه‌های قدیمی به طور منظم منسوخ می‌شوند . به همین دلیل، همیشه توصیه می شود که کاربران از جدیدترین نسخه SDF استفاده کنند .

شما نسخه SDF SDF مورد نظر خود را با استفاده از قسمت version در بدنه درخواست تنظیم می کنید. اگر روی SDF_VERSION_UNSPECIFIED تنظیم یا تنظیم نشود، این کار از نسخه پیش‌فرض SDF تبلیغ‌کننده یا منبع شریک استفاده می‌کند که به عنوان زمینه محتوای SDF استفاده می‌شود.

توجه: هر منبع شریک دارای یک نسخه پیش‌فرض SDF است که در تنظیمات «جزئیات اساسی» در API پیکربندی شده است. مگر اینکه پیکربندی دیگری انجام شود، تبلیغ‌کنندگان این پیش‌فرض را از شریک اصلی خود به ارث می‌برند.

زمینه را تنظیم کنید

شما می‌توانید یک SDF حاوی داده‌های مربوط به هر منبعی که در دسترس شماست تولید کنید، اما هر SDF فردی فقط می‌تواند محتوا را در چارچوب یک شریک یا تبلیغ‌کننده بازگرداند. این زمینه در بدنه درخواست توسط قسمت partnerId یا advertiserId تعریف شده است. دقیقا یکی از این دو فیلد باید تنظیم شود.

فقط منابع در چارچوب داده شده در SDF حاصل گنجانده خواهد شد. اگر سعی کنید منبعی را فیلتر کنید که متعلق به شریک یا تبلیغ‌کننده مشخص‌شده نیست، نه آن و نه محتوای زیر آن در نتایج گنجانده نمی‌شود. اگر فقط توسط این منابع نامشخص فیلتر شود، فایل های حاصل خالی خواهند بود. تلاش برای فیلتر کردن بر اساس منابع خارج از زمینه داده شده ، خطایی را بر نمی گرداند ، بنابراین مطمئن شوید که زمینه شما درست است.

فیلتر مناسب را انتخاب کنید

علاوه بر مجموعه زمینه بالا، می‌توانید با تعیین انواع فایل‌هایی که می‌خواهید تولید کنید و منابع خاص یا خانواده‌ای از منابعی که می‌خواهید شامل شود، دامنه فایل‌های داده ساختاریافته خود را فیلتر کنید.

توجه: نوع فایل داده ساختاریافته، نوع منبعی را که آن فایل را پر می کند، دیکته می کند. هر نوع فایل دارای ساختار ستونی متفاوتی است که اطلاعات موجود برای آن منبع را منعکس می کند.

سه فیلتر در دسترس برای یک sdfdownloadtask وجود دارد که هر کدام به نوع خاصی از مشخصات مربوط می شود. شما فقط می توانید برای یک sdfdownloadtask تخصیص دهید.

ParentEntityFilter

ParentEntityFilter گسترده ترین فیلتر موجود است.

با استفاده از فیلد fileType ، می‌توانید تمام انواع فایل‌های دلخواه را که می‌خواهید با کار خود ایجاد کنید، فهرست کنید. این مورد ضروری است، و اگر خالی بماند یا روی FILE_TYPE_UNSPECIFIED تنظیم شود، sdfdownloadtask شما به اشتباه تکمیل خواهد شد.

با استفاده از فیلدهای filterType و filterIds ، می توانید نتایج خود را بیشتر اصلاح کنید. filterType نوع منابعی را برای فیلتر کردن مشخص می کند و filterIds آن منابع را با شناسه منحصر به فردشان شناسایی می کند. SDFهای به دست آمده شامل منابع شناسایی شده توسط fileType هستند که یا منابع یا فرزندان منابع شناسایی شده توسط filterType و filterIds هستند.

توجه: FILTER_TYPE_NONE هیچ فیلتری را برای کار اعمال نمی‌کند، اما فقط زمانی قابل اعمال است که advertiserId مشخص شده باشد. در غیر این صورت، پس از ایجاد sdfdownloadtask ، یک خطا برگردانده خواهد شد.

IDFilter

IdFilter درخواست شما را فیلتر می کند تا فقط شامل منابع شناسایی شده باشد.

IdFilter برای هر نوع SDF، به استثنای منبع موجودی، یک فیلد دارد. هر یک از این فیلدها فهرستی از شناسه‌های منحصربه‌فرد است که منابع خاصی را که می‌خواهید در SDF ایجاد شده خود بگنجانید، شناسایی می‌کند. شناسه های ارائه شده باید در مجموعه زمینه باشند، اما نیازی به ارتباط مستقیم ندارند. برای درخواست یک کمپین خاص، نیازی به درخواست یک کمپین خاص ندارید و بالعکس. تنها انواع فایل های تولید شده مربوط به منابع شناسایی شده در IdFilter خواهد بود.

InventorySourceFilter

InventorySourceFilter فقط اجازه فیلتر کردن و دانلود SDF های حاوی منابع Inventory Source را می دهد. این تنها فیلتری است که می توانید برای دریافت اطلاعات در مورد منابع منبع موجودی خود از آن استفاده کنید.

InventorySourceFilter دارای یک فیلد inventorySourceIds منحصر به فرد است که در آن شناسه های منحصر به فرد منابع منبع موجودی را که می خواهید در SDF خود قرار دهید شناسایی می کنید. اگر لیست ارائه شده به inventorySourceIds خالی باشد، تمام منابع موجودی تحت شرایط تنظیم شده در SDF ایجاد شده گنجانده می شود.

درخواست دادن

هنگامی که پارامترهای SDF مورد نظر خود را دانستید، می توانید درخواست را بسازید و sdfdownloadtask ایجاد کنید.

اخطار: یک کاربر محدود به بیست وظیفه بارگیری sdfdownloadtasks در هر زمان است. تلاش برای ایجاد موارد بیشتر با خطا مواجه می شود.

در اینجا مثالی از نحوه ایجاد یک sdfdownloadtask با استفاده از ParentEntityFilter آورده شده است:

جاوا

// 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());

پایتون

# 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 می‌توانید عملیات خود را بررسی کنید تا ببینید آیا کامل شده و آماده دانلود است یا خطایی ایجاد کرده است.

توجه: بسته به اندازه SDF هایی که تولید می شوند، عملیات شما می تواند از چند ثانیه تا احتمالاً چند ساعت طول بکشد. برای حفظ سهمیه، یک عقب‌نشینی نمایی مانند آنچه در نمونه کد زیر مشاهده می‌شود، معرفی کنید.

پس از اتمام، عملیات برگشتی دارای یک فیلد غیر done خواهد بود. عملیات تمام شده شامل یک قسمت response یا error خواهد بود. در صورت وجود، فیلد error دارای یک شیء Status است که حاوی یک کد خطا و پیام است که جزئیات خطای رخ داده را ارائه می دهد. اگر فیلد response موجود باشد، یک شی با مقدار resourceName خواهد داشت که فایل تولید شده را برای دانلود شناسایی می کند.

در اینجا مثالی از نحوه بررسی درخواست خود با استفاده از عقب نشینی نمایی آورده شده است:

جاوا

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());

پایتون

# 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']
);