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ğerler (CSV) dosyalarıdır. Display & Video 360 API'si 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 elde edilen SDF'lerin nasıl indirileceği açıklanmaktadır.

SDF biçimi ve sürüm oluşturma hakkında bilgi edinmek için SDF referans dokümanlarını inceleyin.

Görev oluşturma

SDF'ler, sdfdownloadtask olarak adlandırılan 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öntemi aracılığıyla yapılır. Aşağıdaki alt bölümlerde, ayarlayabileceğiniz parametreler açıklanmaktadır.

Sürüm belirtin

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

İsteğin gövdesinde version alanını kullanarak istediğiniz SDF'nin SDF sürümünü ayarlarsınız. Ayarlanmamışsa veya SDF_VERSION_UNSPECIFIED olarak ayarlanmışsa görev, SDF içeriğinin bağlamı olarak kullanılan reklamveren veya iş ortağı kaynağının varsayılan SDF sürümünü kullanır.

Not: Her iş ortağı kaynağının, API'deki "Temel Ayrıntılar" ayarlarında yapılandırılmış bir varsayılan SDF sürümü vardır. Aksi yapılandırılmamışsa reklamverenler bu varsayılan ayarı üst iş ortaklarından devralır.

Bağlamı ayarlama

Kullanabileceğiniz tüm kaynaklarla ilgili veriler içeren bir SDF oluşturabilirsiniz ancak her bir SDF yalnızca tek bir iş ortağı veya reklamveren bağlamında içerik döndürebilir. Bu bağlam, istek gövdesinde partnerId veya advertiserId alanıyla tanımlanır. Bu iki alandan tam olarak biri ayarlanmalıdır.

Yalnızca belirli bağlamdaki kaynaklar, oluşturulan SDF'ye dahil edilir. Belirtilen iş ortağına veya reklamverene ait olmayan bir kaynağa göre filtrelemeye çalışırsanız bu kaynak ve altındaki içerikler sonuçlara dahil edilmez. Yalnızca bu dahil edilmeyen kaynaklara göre filtreleme yaparsanız oluşturulan dosyalar boş olur. Belirtilen bağlamın dışındaki kaynaklara göre filtreleme yapmaya çalışmak 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 ailelerini belirterek oluşturulan Yapılandırılmış Veri Dosyalarınızın kapsamını daha da filtreleyebilirsiniz.

Not: Yapılandırılmış Veri Dosyası'nın türü, dosyayı dolduran kaynak türünü belirler. Her dosya türünün, ilgili kaynakta bulunan bilgileri yansıtan farklı bir sütun yapısı vardır.

sdfdownloadtask için her biri belirli bir spesifikasyon türüne göre üç filtre mevcuttur. Tek bir sdfdownloadtask için yalnızca bir tane atayabilirsiniz.

ParentEntityFilter

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

fileType alanını kullanarak, görevinizle birlikte oluşturmak istediğiniz tüm dosya türlerini listeleyebilirsiniz. Bu zorunludur ve boş bırakılırsa veya FILE_TYPE_UNSPECIFIED olarak ayarlanırsa sdfdownloadtask yanlışlıkla tamamlanır.

filterType ve filterIds alanlarını kullanarak sonuçlarınızı daha da hassaslaştırabilirsiniz. filterType, filtrelenecek kaynak türünü belirtir ve filterIds bu kaynakları benzersiz kimliklerine göre tanımlar. Elde edilen SDF'ler, filterType ve filterIds tarafından tanımlanan kaynakların ya da bu kaynakların alt öğelerinin fileType tarafından tanımlanan kaynaklarını içerir.

Not: FILTER_TYPE_NONE, göreve herhangi bir filtre uygulamaz ancak yalnızca advertiserId belirtildiğinde geçerlidir. Aksi takdirde, sdfdownloadtask oluşturulduğunda bir hata döndürülür.

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 dahil etmek istediğiniz belirli kaynakları tanımlayan benzersiz kimliklerin bir listesidir. Sağlanan kimlikler, bağlam kümesi içinde olmalıdır ancak doğrudan alakalı olmaları gerekmez. İçerdiği bir satır öğesini istemek için belirli bir kampanyayı istemeniz gerekmez ve bunun tersi de geçerlidir. Oluşturulan tek dosya türleri, IdFilter dosyasında tanımlanan kaynaklara karşılık gelen dosya türleridir.

InventorySourceFilter

InventorySourceFilter yalnızca envanter kaynağı kaynakları içeren SDF'lerin filtrelenmesine ve indirilmesine olanak tanır. 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 tekil bir inventorySourceIds alanına sahiptir. inventorySourceIds parametresine sağlanan liste boşsa ayarlanan bağlam kapsamındaki 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.

Uyarı: Tek bir kullanıcı, aynı anda yirmi sdfdownloadtasks ile sınırlıdır. Daha fazla oluşturma girişimleri hata döndürür.

Aşağıda, ParentEntityFilter kullanarak sdfdownloadtask oluşturma örneği 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 edin ve indirme yolunu alın

Bir sdfdownloadtask oluşturduğunuzda bir işlem nesnesi döndürülür. Bu işlem, eşzamansız SDF oluşturma işleminizin oluşturulma anındaki durumunu gösterir. sdfdownloadtasks.operations.get yöntemini kullanarak işleminizin tamamlanıp tamamlanmadığını ve indirmeye hazır olup olmadığını ya da hata atıp atmadığını kontrol edebilirsiniz.

Not: Oluşturulan SDF'lerin boyutuna bağlı olarak işleminiz birkaç saniyeden birkaç saate kadar sürebilir. Kotayı korumak için aşağıdaki kod örneğinde gösterilen gibi üssel bir geri çekilme uygulayın.

İşlem tamamlandığında döndürülen işlemde boş olmayan bir done alanı bulunur. Tamamlanan işlem, bir response veya error alanı içerir. Varsa error alanında, hata kodu ve mesaj içeren bir Status nesnesi bulunur. Bu mesaj, gerçekleşen hatayla ilgili ayrıntıları sağlar. response alanı varsa bu alanda, oluşturulan indirilebilir dosyayı tanımlayan bir resourceName değeri içeren bir nesne bulunur.

Eksponansiyel geri yükleme kullanarak isteğinizi nasıl kontrol edeceğinizle ilgili bir örnek aşağıda verilmiştir:

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