Genel bakış

Yapılandırılmış Veri Dosyaları (SDF'ler), Display & Video 360 kaynaklarıyla ilgili verileri toplu olarak almak ve güncellemek için kullanılan, özel olarak biçimlendirilmiş virgülle ayrılmış değer (CSV) dosyalarıdır. Display & Video 360 API aracılığıyla özelleştirilmiş SDF'ler oluşturup indirebilirsiniz. Bu sayede, Display & Video 360 kaynaklarınızla ilgili düzenlenmiş ve filtrelenmiş verileri alabilirsiniz.

Bu kılavuzda, SDF indirme işleminin nasıl oluşturulacağı, bu işlemin nasıl izleneceği ve sonuçta elde edilen SDF'lerin nasıl indirileceği açıklanmaktadır.

SDF biçimi ve sürüm oluşturma hakkında bilgileri SDF referans belgelerinde bulabilirsiniz.

Görev oluşturma

SDF'ler, sdfdownloadtask adı verilen eşzamansız bir işlemle oluşturulur. Bu görevi oluştururken istediğiniz SDF'lerle ilgili parametreleri tanımlarsınız. Bu işlem, sdfdownloadtasks.create yöntemiyle yapılır. Aşağıdaki alt bölümlerde, ayarlayabileceğiniz parametreler açıklanmaktadır.

Bir sürüm belirtin

Yapılandırılmış veri dosyası biçimi, Display & Video 360 API'den bağımsız olarak düzenli aralıklarla güncellenir. Yeni sürümler yayınlanır ve önceki sürümler düzenli olarak kullanımdan kaldırılır. Bu nedenle, kullanıcıların her zaman SDF'nin en son sürümünü kullanması önerilir.

İstek gövdesindeki version alanını kullanarak istediğiniz SDF'nin SDF sürümünü ayarlarsınız. Ayarlanmazsa veya SDF_VERSION_UNSPECIFIED olarak ayarlanırsa görev, SDF içeriğinin bağlamı olarak kullanılan reklamveren ya da iş ortağı kaynağının varsayılan SDF sürümünü kullanır.

Bağlamı ayarlama

Size sunulan tüm kaynaklarla ilgili verileri içeren bir SDF oluşturabilirsiniz ancak her bir SDF yalnızca tek bir iş ortağı veya reklamveren bağlamındaki içeriği döndürebilir. Bu bağlam, istek gövdesinde partnerId veya advertiserId alanı tarafından tanımlanır. Bu iki alandan tam olarak biri ayarlanmalıdır.

Sonuçta elde edilen SDF'ye yalnızca verilen bağlamdaki kaynaklar dahil edilir. Belirtilen iş ortağına veya reklamverene ait olmayan bir kaynağa göre filtreleme yapmaya çalışırsanız bu kaynak ve altındaki içerikler sonuçlara dahil edilmez. Yalnızca bu dahil edilmeyen kaynaklara göre filtreleme yapılıyorsa sonuçta elde edilen dosyalar boş olur. Belirtilen bağlamın dışındaki kaynaklara göre filtreleme girişiminde bulunmak hata döndürmez. Bu nedenle, bağlamınızın doğru olduğundan emin olun.

Doğru filtreyi seçme

Yukarıda ayarlanan bağlama ek olarak, oluşturmak istediğiniz dosya türlerini ve dahil etmek istediğiniz belirli kaynakları veya kaynak ailesini belirterek oluşturulan Yapılandırılmış Veri Dosyalarınızın kapsamını daha da filtreleyebilirsiniz.

sdfdownloadtask için üç filtre mevcuttur. Bu filtrelerin her biri belirli bir spesifikasyon türüne yöneliktir. Tek bir sdfdownloadtask için yalnızca bir tane atayabilirsiniz.

ParentEntityFilter

ParentEntityFilter, mevcut filtreler arasında en kapsamlı olanıdır.

fileType alanını kullanarak görevinizle oluşturmak istediğiniz tüm dosya türlerini listeleyebilirsiniz. Bu alan zorunludur. Boş bırakılırsa veya FILE_TYPE_UNSPECIFIED olarak ayarlanırsa sdfdownloadtask işlemi hatalı bir şekilde tamamlanır.

filterType ve filterIds alanlarını kullanarak sonuçlarınızı daha da daraltabilirsiniz. filterType, filtrelenecek kaynak türünü belirtir ve filterIds bu kaynakları benzersiz kimlikleriyle tanımlar. Elde edilen SDF'ler, fileType ile tanımlanan kaynakların filterType ve filterIds ile tanımlanan kaynaklar veya bu kaynakların alt öğeleri olan kaynakları içerir.

IdFilter

IdFilter, isteğinizi yalnızca tanımlanan kaynakları içerecek şekilde filtreler.

IdFilter, Envanter Kaynağı hariç her SDF türü için bir alana sahiptir. Bu alanların her biri, oluşturulan SDF'nize eklemek istediğiniz belirli kaynakları tanımlayan benzersiz kimliklerin listesidir. Sağlanan kimlikler, ayarlanan bağlam içinde olmalıdır ancak doğrudan ilişkili olmaları gerekmez. İçerdiği bir satır öğesini istemek için belirli bir kampanyayı istemeniz gerekmez ve bunun tersi de geçerlidir. Yalnızca IdFilter içinde tanımlanan kaynaklara karşılık gelen dosya türleri oluşturulur.

InventorySourceFilter

InventorySourceFilter yalnızca envanter kaynağı kaynaklarını içeren SDF'lerin filtrelenmesine ve indirilmesine izin verir. Envanter kaynağı kaynaklarınızla ilgili bilgi edinmek için kullanabileceğiniz tek filtredir.

InventorySourceFilter, SDF'nize dahil etmek istediğiniz envanter kaynağı kaynaklarının benzersiz kimliklerini tanımladığınız tek bir inventorySourceIds alanına sahiptir. inventorySourceIds'ye sağlanan liste boşsa ayarlanan bağlamdaki tüm envanter kaynakları oluşturulan SDF'ye dahil edilir.

İstekte bulunun

İstediğiniz SDF'nin parametrelerini öğrendikten sonra isteği oluşturabilir ve sdfdownloadtask öğesini oluşturabilirsiniz.

Aşağıda, ParentEntityFilter kullanarak nasıl sdfdownloadtask oluşturulacağına dair bir örnek verilmiştir:

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

İsteğinizi kontrol etme ve indirme yolunu alma

sdfdownloadtask oluşturduğunuzda işlem nesnesi döndürülür. Bu işlem, oluşturma sırasında eşzamansız SDF oluşturma işleminizin durumunu gösterir. sdfdownloadtasks.operations.get yöntemini kullanarak işleminizin tamamlanıp tamamlanmadığını, indirilmeye hazır olup olmadığını veya hata verip vermediğini kontrol edebilirsiniz.

İşlem tamamlandığında döndürülen işlemde boş olmayan bir done alanı bulunur. Tamamlanan işlemde response veya error alanı yer alır. Varsa error alanında, hata kodu ve mesaj içeren bir Status nesnesi bulunur. Bu nesne, oluşan hatanın ayrıntılarını sağlar. response alanı varsa indirmek için oluşturulan dosyayı tanımlayan bir resourceName değerine sahip bir nesne içerir.

İsteğinizi eksponansiyel geri yüklemeyle nasıl kontrol edeceğinize dair bir örneği aşağıda bulabilirsiniz:

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