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