Genel bakış

Yapılandırılmış Veri Dosyaları (SDF'ler) özel olarak biçimlendirilmiş, virgülle ayrılmış değerlerdir (CSV) Display &Video 360 hakkında verileri almak ve güncellemek için kullanılan dosyalar Video 360 kaynakları: toplu hale getirir. Görüntülü Reklam Ağı ve özel SDF'ler oluşturabilir ve indirebilirsiniz. Böylece, Görüntülü Reklam Ağı ve Görüntülü Reklam Ağı'ndaki Video 360 kaynaklar.

Bu kılavuzda, bir SDF İndirme işleminin nasıl oluşturulacağı ve işlemini yapabilir ve elde edilen SDF'leri indirebilirsiniz.

SDF biçimi ve sürümü ile ilgili bilgiler şurada bulunabilir: SDF referans belgeleri

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. İlgili içeriği oluşturmak için kullanılan 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, Görüntülü Reklam ve Yeni sürümleri yayınlanan ve eski sürümleri içeren Video 360 API düzenli olarak kullanımdan kaldırılmıştır. Bu nedenle, kullanıcıların her zaman SDF'nin en son sürümünü kullanmaları önerilir.

İstediğiniz SDF'nin SDF sürümünü version alanına ekleyebilirsiniz. Ayarlanmadıysa veya ayarlanmışsa SDF_VERSION_UNSPECIFIED değerine ayarlanırsa görev, SDF içeriğinin bağlamı olarak kullanılan reklamveren veya iş ortağı kaynağı.

Not: Her iş ortağı kaynağının "Basic Details" (Temel Ayrıntılar) ayarları hakkında daha fazla bilgi edinin. Aksi yapılandırılmadığı sürece reklamverenler bu varsayılan ayarı üst iş ortaklarından devralır.

Bağlamı belirleme

Kullanabileceğiniz herhangi bir kaynakla ilgili verileri içeren bir SDF oluşturabilirsiniz ancak herhangi bir SDF, yalnızca tek bir bağlam içindeki içeriği döndürebilir. iş ortağı veya reklamveren olabilir. Bu bağlam, istek gövdesinde partnerId veya advertiserId alanına giriş yapın. Tam olarak bu ikisinden biri alanlarının ayarlanması gerekir.

Oluşturulan SDF'ye yalnızca belirtilen bağlamdaki kaynaklar dahil edilir. Belirtilen iş ortağına ait olmayan bir kaynağa göre filtrelemeye çalışırsanız veya altındaki içerik de bu karara dahil edilemeyecek, sonuç. Yalnızca bu dahil edilmemiş kaynaklara göre filtre uygularsanız ortaya çıkan dosyalar boş görünür. Belirtilen bağlam dışındaki kaynaklara göre filtrelemeye çalışma bir hata döndürmez. Bu nedenle, bağlamınızın doğru olduğundan emin olun doğru.

Doğru filtreyi seçin

Yukarıdaki içeriğe ek olarak, oluşturmak istediğiniz dosya türlerini belirterek oluşturulan Yapılandırılmış Veri Dosyaları ve dahil etmek istediğiniz belirli kaynakları veya kaynak ailesini seçin.

Not: Yapılandırılmış veri dosyalarının türü, doldurulacak kaynak türünü belirler yapabilirsiniz. Her dosya türü farklı bir sütun yapısına sahiptir. ilgili kaynaktaki bilgileri yansıtması gerekir.

sdfdownloadtask için üç filtre bulunur. Bu filtrelerin her biri bir spesifikasyon türü olabilir. Her biri için yalnızca bir değer atayabilirsiniz sdfdownloadtask

ParentEntityFilter

ParentEntityFilter mevcut seçenekler arasından en geniş olanıdır filtrelerine dokunun.

fileType alanını kullanarak, istediğiniz tüm anahtar kelimeleri listeleyebilirsiniz. Görevinizle oluşturmak istediğiniz dosya türlerini seçin. Bu gerekir ve boş bırakılırsa ya da FILE_TYPE_UNSPECIFIED olarak ayarlanırsa sdfdownloadtask hatasıyla tamamlanacak.

filterType ve filterIds alanlarını kullanarak sonuçlarınızı daha da hassaslaştırabilirsiniz. filterType, türünü belirtir kaynaklara göre filtreleyin ve filterIds bu kaynakları benzersiz kimliklerine göre tanımlar. Ortaya çıkan SDF'ler, fileType tarafından tanımlanan veya kaynakları ya da alt öğelerini filterType ve filterIds.

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

IdFilter

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

IdFilter'te, Envanter hariç her SDF türü için bir alan bulunur Kaynak. Bu alanların her biri, müşterinin kimliğini tanımlayan benzersiz kimliklerin oluşturulan SDF'nize dahil etmek istediğiniz belirli kaynaklar. Sağlanan kimlikler belirlenen bağlam içinde olması gerekir. Ancak bunların doğrudan ilişkili olmaları gerekmez. Siz Bir satır öğesini istemek için belirli bir kampanyayı istemesi gerekmez ve tam tersi de geçerlidir. Oluşturulacak dosya türleri yalnızca onlardan olacaktır IdFilter'nda belirtilen kaynaklara karşılık gelecek şekilde hazırlanır.

InventorySourceFilter

InventorySourceFilter yalnızca filtrelemeye izin verir ve Envanter Kaynağı kaynaklarını içeren SDF'lerin indirilmesini sağlar. Sadece bu filtre uygulayabilirsiniz.

InventorySourceFilter adlı işletmenin tekil bir değeri var Benzersiz Search Ads 360'ı tanımladığınız inventorySourceIds alanı SDF'nize dahil etmek istediğiniz envanter kaynağı kaynaklarının kimlikleri. Öğe inventorySourceIds adresine sağlanan liste boş, tümü belirlenen bağlamdaki envanter kaynakları, oluşturulan SDF'ye dahil edilir.

İstekte bulunun

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

Uyarı: Tek bir kullanıcı, herhangi bir zamanda yirmi sdfdownloadtasks ile sınırlıdır bir kez. Daha fazla öğe oluşturma girişimlerinde hata mesajı verilir.

Aşağıda,sdfdownloadtask 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());

İsteğinizi kontrol etme ve indirme yolunu öğrenme

Bir sdfdownloadtask oluşturduğunuzda bir işlem nesnesi geri döndü. Bu işlem, eşzamansız SDF'nizin durumunu gösterir projenin oluşturulduğu aşamadır. İşleminizi şu şekilde kontrol edebilirsiniz: tamamlanıp indirilmeye hazır olup olmadığını veya hata verip vermediğini anlamak için sdfdownloadtasks.operations.get yöntemini kullanır.

Not: Oluşturulan SDF'lerin boyutuna bağlı olarak işleminiz birkaç saniye ile saatler arasında değişir. Kotadan tasarruf etmek için Aşağıdaki kod örneğinde görüldüğü gibi bir üstel geri çekilme sağlayın.

Tamamlandıktan sonra, döndürülen işlemde null olmayan bir değer olacaktır done alanına giriş yapın. Tamamlanan işlem, bir response veya error girin. Bu seçenek varsa error alanında bir Hata kodu içeren Status ve mesaj görünmektedir. Bu mesaj, meydana geldi. response alanı varsa oluşturulan dosyayı tanımlayan resourceName değerine sahip bir nesne olacaktır indirilecek dosya.

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