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. Böylece, Display & Video 360 kaynaklarınızda düzenli ve filtrelenmiş veriler alabilirsiniz.

Bu kılavuzda, SDF İndirme 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şturmayla ilgili 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, sdfdownloadtasks.create yöntemi kullanılarak gerçekleştirilir. 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. Bunun sonucunda 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ı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ü ayarlayabilirsiniz. Ayarlanmazsa veya SDF_VERSION_UNSPECIFIED olarak ayarlanırsa 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ılmadığı sürece reklamverenler bu varsayılan değeri üst iş ortaklarından devralır.

Bağlamı belirleyin

Kullanabileceğiniz tüm kaynaklarla ilgili veriler içeren bir SDF oluşturabilirsiniz ancak her 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ı tarafından tanımlanır. Bu iki alandan tam olarak biri ayarlanmalıdır.

Oluşturulan SDF'ye yalnızca belirtilen 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 veya bunun altındaki içerik sonuçlara dahil edilmez. Yalnızca bu dahil edilmeyen kaynaklara göre filtreleme yapılırsa elde edilen dosyalar boş olur. Belirtilen bağlamın dışında kaynaklara göre filtrelemeye çalışmak hata döndürmez. Bu nedenle, bağlamınızın doğru olup olmadığını kontrol ettiğinizden emin olun.

Doğru filtreyi seçme

Yukarıda belirtilen bağlama ek olarak, oluşturmak istediğiniz dosya türlerini ve eklemek istediğiniz belirli kaynakları veya kaynak ailesini belirterek, oluşturulan Yapılandırılmış Veri Dosyalarınızın kapsamını daha ayrıntılı bir şekilde filtreleyebilirsiniz.

Not: Yapılandırılmış veri dosyasının türü, dosyayı dolduran kaynak türünü belirtir. Her dosya türü, söz konusu kaynaktaki bilgileri yansıtan farklı bir sütun yapısına sahiptir.

sdfdownloadtask için üç filtre bulunur. Her filtre, belirli bir spesifikasyon türüne uygundur. Tek bir sdfdownloadtask için yalnızca bir giriş atayabilirsiniz.

ParentEntityFilter

ParentEntityFilter mevcut filtreler arasında en geniş olandır.

fileType alanını kullanarak, görevinizle oluşturmak istediğiniz tüm dosya türlerini listeleyebilirsiniz. Bu zorunludur. Boş bırakılır veya FILE_TYPE_UNSPECIFIED olarak ayarlanırsa sdfdownloadtask hatalı olarak tamamlanacaktı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. Ortaya çıkan SDF'ler, fileType tarafından tanımlanan ve filterType ve filterIds tarafından tanımlanan kaynakların ya da alt öğeleri olan kaynakları içerecektir.

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

IdFilter

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

IdFilter'te, Envanter Kaynağı hariç her SDF türü için bir alan bulunur. Bu alanların her biri, oluşturulan SDF'nize dahil etmek istediğiniz belirli kaynakları tanımlayan benzersiz kimliklerin bir listesidir. Sağlanan kimliklerin bağlam kümesinde olması gerekir ancak doğrudan ilişkili olmaları gerekmez. Belirli bir kampanyayı içerdiği satır öğesini istemek için kampanya istemeniz (veya tam tersi) gerekmez. Oluşturulan tek dosya türü, IdFilter'da belirtilen kaynaklara karşılık gelenlerdir.

InventorySourceFilter

InventorySourceFilter, yalnızca Envanter Kaynağı kaynaklarını içeren SDF'lerin filtrelenmesine ve indirilmesine izin verir. Envanter Kaynağı kaynaklarınız hakkında bilgi almak için kullanabileceğiniz tek filtredir.

InventorySourceFilter, SDF'nize dahil etmek istediğiniz envanter kaynağı kaynaklarının benzersiz kimliklerini belirttiğiniz tek bir inventorySourceIds alanına sahiptir. inventorySourceIds için sağlanan liste boşsa belirlenen bağlam altındaki tüm envanter kaynakları, oluşturulan SDF'ye dahil edilir.

İstekte bulunun

İstediğiniz SDF'nin parametrelerini öğrendiğinizde isteği ve sdfdownloadtask dosyasını oluşturabilirsiniz.

Uyarı: Tek bir kullanıcı, aynı anda en fazla yirmi sdfdownloadtasks çalışabilir. Daha fazla dosya oluşturmaya çalışırsanız hata döndürülür.

ParentEntityFilter kullanarak sdfdownloadtask oluşturma işleminin bir örneğini aşağıda bulabilirsiniz:

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

sdfdownloadtask oluşturduğunuzda bir işlem nesnesi döndürülür. Bu işlem, eşzamansız SDF oluşturma işleminizin anlık durumunu gösterir. sdfdownloadtasks.operations.get yöntemini kullanarak işleminizi kontrol ederek tamamlandığını ve indirilmeye hazır olup olmadığını ya da hata verip vermediğini görebilirsiniz.

Not: Oluşturulan SDF'lerin boyutuna bağlı olarak işleminiz, birkaç saniye ila birkaç saat arasında sürebilir. Kotadan tasarruf etmek için aşağıdaki kod örneğinde görülen gibi bir üstel geri yükleme işlemi uygulayın.

Tamamlandıktan sonra, döndürülen işlemde boş olmayan bir done alanı olur. Tamamlanan işlem bir response veya error alanı içerir. Varsa error alanında, oluşan hatanın ayrıntılarını içeren hata kodu ve mesaj içeren bir Status nesnesi bulunur. response alanı mevcutsa indirilmek üzere oluşturulan dosyayı tanımlayan resourceName değerine sahip bir nesne bulunur.

Aşağıda, eksponansiyel geri yükleme kullanarak isteğinizi nasıl kontrol edeceğinize dair bir örnek 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']
);