इस पेज का अनुवाद Cloud Translation API से किया गया है.

खास जानकारी

स्ट्रक्चर्ड डेटा फ़ाइलें (एसडीएफ़) खास तौर पर फ़ॉर्मैट की गई, कॉमा लगाकर अलग की गई वैल्यू (CSV) वाली फ़ाइलें होती हैं. इनका इस्तेमाल, Display & Video 360 के संसाधनों से जुड़ा डेटा एक साथ वापस पाने और अपडेट करने के लिए किया जाता है. Display & Video 360 API की मदद से, पसंद के मुताबिक एसडीएफ़ जनरेट और डाउनलोड किए जा सकते हैं. इससे Display & Video 360 के संसाधनों पर, व्यवस्थित और फ़िल्टर किया गया डेटा वापस पाया जा सकता है.

इस गाइड में बताया गया है कि SDF डाउनलोड कार्रवाई कैसे बनाएं, उस कार्रवाई को कैसे ट्रैक करें, और उससे बनने वाले SDF कैसे डाउनलोड करें.

एसडीएफ़ फ़ॉर्मैट और वर्शन के बारे में जानकारी, एसडीएफ़ से जुड़े दस्तावेज़ में मिल सकती है.

टास्क बनाना

एसडीएफ़ एसिंक्रोनस ऑपरेशन से जनरेट होते हैं, जिसे sdfdownloadtask कहा जाता है. इस टास्क को बनाते समय, अपनी पसंद के एसडीएफ़ से जुड़े पैरामीटर तय किए जाते हैं. ऐसा sdfdownloadtasks.create तरीके से किया जाता है. नीचे दिए गए सब-सेक्शन, उन पैरामीटर के बारे में बताते हैं जिन्हें सेट किया जा सकता है.

वर्शन चुनें

स्ट्रक्चर्ड डेटा फ़ाइल फ़ॉर्मैट को नियमित रूप से Display & Video 360 API से स्वतंत्र रूप से अपडेट किया जाता है. इसमें नए और पुराने वर्शन रिलीज़ किए जाते हैं समय-समय पर बंद किया जाता है. इस वजह से, लोगों को हमेशा एसडीएफ़ का सबसे नया वर्शन इस्तेमाल करने का सुझाव दिया जाता है.

अनुरोध के मुख्य हिस्से में मौजूद version फ़ील्ड का इस्तेमाल करके, अपनी पसंद के एसडीएफ़ का एसडीएफ़ वर्शन सेट किया जाता है. अगर इस टास्क को SDF_VERSION_UNSPECIFIED पर सेट या सेट नहीं किया जाता है, तो यह टास्क विज्ञापन देने वाले या पार्टनर के रिसॉर्स के डिफ़ॉल्ट एसडीएफ़ वर्शन का इस्तेमाल करेगा. इसे एसडीएफ़ कॉन्टेंट के संदर्भ के तौर पर इस्तेमाल किया जाएगा.

संदर्भ सेट करें

अपने पास मौजूद किसी भी संसाधन का डेटा वाला एसडीएफ़ जनरेट किया जा सकता है. हालांकि, कोई भी एसडीएफ़ सिर्फ़ एक पार्टनर या विज्ञापन देने वाले के लिए कॉन्टेंट दिखा सकता है. यह कॉन्टेक्स्ट, अनुरोध के मुख्य हिस्से में partnerId या advertiserId फ़ील्ड के ज़रिए बताया गया है. इन दोनों में से कोई एक फ़ील्ड सेट होना चाहिए.

एसडीएफ़ में, सिर्फ़ दिए गए संदर्भ से जुड़े संसाधनों को शामिल किया जाएगा. अगर किसी ऐसे संसाधन के हिसाब से फ़िल्टर करने की कोशिश की जाती है जिसका मालिकाना हक, पार्टनर या विज्ञापन देने वाले के पास नहीं है, तो नतीजों में न तो उस संसाधन को शामिल किया जाएगा और न ही उसके कॉन्टेंट को. अगर सिर्फ़ इन बिना शामिल किए गए संसाधनों के हिसाब से फ़िल्टर किया जाता है, तो नतीजे के तौर पर मिलने वाली फ़ाइलें खाली रहेंगी. किसी दिए गए संदर्भ से बाहर के रिसॉर्स के हिसाब से फ़िल्टर करने पर कोई गड़बड़ी नहीं मिलेगी. इसलिए, जांच लें कि आपका कॉन्टेक्स्ट सही है.

सही फ़िल्टर चुनें

ऊपर सेट किए गए संदर्भ के अलावा, अपनी जनरेट की गई स्ट्रक्चर्ड डेटा फ़ाइलों के स्कोप को और फ़िल्टर किया जा सकता है. इसके लिए, आपको फ़ाइल के उन टाइप की जानकारी देनी होगी जिन्हें आपको जनरेट करना है और जिन संसाधनों या रिसॉर्स के फ़ैमिली ग्रुप को शामिल करना है.

sdfdownloadtask के लिए तीन फ़िल्टर उपलब्ध हैं. हर फ़िल्टर किसी खास जानकारी के लिए है. एक sdfdownloadtask के लिए सिर्फ़ एक असाइन किया जा सकता है.

ParentEntityFilter

उपलब्ध फ़िल्टर में से सबसे बड़ा फ़िल्टर ParentEntityFilter है.

fileType फ़ील्ड का इस्तेमाल करके, उन सभी फ़ाइल टाइप की सूची बनाई जा सकती है जिन्हें आपको अपने टास्क के साथ जनरेट करना है. यह ज़रूरी है. अगर इसे खाली छोड़ दिया जाता है या FILE_TYPE_UNSPECIFIED पर सेट किया जाता है, तो आपका sdfdownloadtask गलती से पूरा हो जाएगा.

filterType और filterIds फ़ील्ड का इस्तेमाल करके, नतीजों को और बेहतर बनाया जा सकता है. filterType बताता है कि किस तरह के रिसॉर्स के हिसाब से फ़िल्टर किया जा सकता है. साथ ही, filterIds इन रिसॉर्स की पहचान, उनके यूनीक आईडी से करता है. एसडीएफ़ में, fileType के बताए गए संसाधन शामिल होंगे. ये संसाधन filterType और filterIds से मिले संसाधन या चाइल्ड रिसॉर्स हैं.

IdFilter

IdFilter आपके अनुरोध को फ़िल्टर करके, सिर्फ़ उन संसाधनों को शामिल करता है जिनकी पहचान की गई होती है.

IdFilter में हर तरह के एसडीएफ़ के लिए एक फ़ील्ड होता है. हालांकि, इसमें इन्वेंट्री सोर्स शामिल नहीं है. इनमें से हर फ़ील्ड यूनीक आईडी की सूची होती है. इससे उन खास संसाधनों की पहचान होती है जिन्हें आपको अपने जनरेट किए गए एसडीएफ़ में शामिल करना है. दिए गए आईडी, कॉन्टेक्स्ट सेट के अंदर होने चाहिए, लेकिन उनका सीधे तौर पर एक-दूसरे से जुड़ा होना ज़रूरी नहीं है. आपको किसी अभियान में शामिल लाइन आइटम का अनुरोध करने के लिए या किसी खास अभियान का अनुरोध करने की ज़रूरत नहीं है. सिर्फ़ वही फ़ाइल टाइप जनरेट किए जाएंगे जो IdFilter में दिए गए संसाधनों से मेल खाते हैं.

InventorySourceFilter

InventorySourceFilter सिर्फ़ इन्वेंट्री सोर्स रिसॉर्स वाले एसडीएफ़ को फ़िल्टर करने और डाउनलोड करने की अनुमति देता है. अपने इन्वेंट्री सोर्स संसाधनों के बारे में जानकारी पाने के लिए, सिर्फ़ इस फ़िल्टर का इस्तेमाल किया जा सकता है.

InventorySourceFilter में एक सिंगल inventorySourceIds फ़ील्ड होता है, जहां इन्वेंट्री सोर्स के उन संसाधनों के यूनीक आईडी की पहचान की जाती है जिन्हें आपको अपने एसडीएफ़ में शामिल करना है. अगर inventorySourceIds के लिए दी गई सूची खाली है, तो सेट किए गए कॉन्टेक्स्ट में मौजूद इन्वेंट्री के सभी सोर्स, जनरेट किए गए एसडीएफ़ में शामिल किए जाएंगे.

अनुरोध करें

अपनी पसंद के एसडीएफ़ के पैरामीटर जानने के बाद, अनुरोध करें और sdfdownloadtask बनाएं.

यहां दिए गए उदाहरण में बताया गया है कि ParentEntityFilter का इस्तेमाल करके, sdfdownloadtask कैसे बनाया जाता है:

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

अपने अनुरोध की जांच करें और डाउनलोड पाथ पाएं

जब कोई sdfdownloadtask बनाया जाता है, तो ऑपरेशन ऑब्जेक्ट दिखाया जाता है. यह कार्रवाई, बनाए जाने के समय आपके एसिंक्रोनस एसडीएफ़ जनरेट करने के ऑपरेशन की स्थिति को दिखाती है. sdfdownloadtasks.operations.get तरीके का इस्तेमाल करके, यह पता लगाया जा सकता है कि क्या यह पूरा हो गया है और डाउनलोड के लिए तैयार है या फिर कोई गड़बड़ी हुई है.

प्रक्रिया पूरी होने के बाद, वापस की गई कार्रवाई में एक गैर-शून्य done फ़ील्ड होगा. पूरी कार्रवाई में या तो response या error फ़ील्ड शामिल होगा. अगर यह मौजूद है, तो error फ़ील्ड में एक Status ऑब्जेक्ट होगा, जिसमें गड़बड़ी कोड और मैसेज होगा. इनसे हुई गड़बड़ी की जानकारी मिलती है. अगर response फ़ील्ड मौजूद है, तो इसमें resourceName वैल्यू वाला एक ऑब्जेक्ट होगा, जो जनरेट की गई फ़ाइल की पहचान करेगा.

एक्सपोनेन्शियल बैकऑफ़ का इस्तेमाल करके अपने अनुरोध की जाँच करने का तरीका यहां दिया गया है:

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

आगे बढ़ें

फ़ाइल डाउनलोड करें