स्ट्रक्चर्ड डेटा फ़ाइलें (एसडीएफ़) खास तौर पर फ़ॉर्मैट की गई, कॉमा लगाकर अलग की गई वैल्यू (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'] );