स्ट्रक्चर्ड डेटा फ़ाइलें (एसडीएफ़), कॉमा लगाकर अलग की गई वैल्यू (CSV) वाली फ़ाइलें होती हैं. इन्हें खास तौर पर फ़ॉर्मैट किया जाता है. इनका इस्तेमाल, Display & Video 360 संसाधनों के बारे में डेटा को एक साथ वापस पाने और अपडेट करने के लिए किया जाता है. Display & Video 360 API की मदद से, अपनी पसंद के मुताबिक बनाए गए एसडीएफ़ जनरेट और डाउनलोड किए जा सकते हैं. इससे आपको अपने Display & Video 360 संसाधनों पर व्यवस्थित और फ़िल्टर किया गया डेटा वापस पाने में मदद मिलती है.
इस गाइड में, एसडीएफ़ डाउनलोड करने की प्रोसेस बनाने, उसे ट्रैक करने, और उससे मिले एसडीएफ़ डाउनलोड करने का तरीका बताया गया है.
एसडीएफ़ फ़ॉर्मैट और वर्शन के बारे में जानकारी, एसडीएफ़ के रेफ़रंस दस्तावेज़ में मिल सकती है.
टास्क बनाना
एसडीएफ़, एसिंक्रोनस ऑपरेशन से जनरेट होते हैं. इसे 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
बनाने पर, operation ऑब्जेक्ट दिखता है. इस ऑपरेशन से, एसडीएफ़ जनरेट करने के एसिंक्रोनस ऑपरेशन की स्थिति के बारे में पता चलता है. यह स्थिति, एसडीएफ़ जनरेट करने के ऑपरेशन के शुरू होने के समय की होती है. 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'] );