स्टोरेज एपीआई

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

आपको यह भी सोचना होगा कि आपका ऐप्लिकेशन ऑफ़लाइन होने पर डेटा का इस्तेमाल कैसे किया जाता है (ऑफ़लाइन पहले देखें देखें). इस दस्तावेज़ में, डेटा को स्थानीय तौर पर भेजने, पाने, और सेव करने के स्टोरेज के विकल्पों के बारे में खास जानकारी दी गई है. दस्तावेज़ के बचे हुए हिस्से में, Chrome के File System और Sync File System API को इस्तेमाल करने का तरीका बताया गया है. fileSystem API और syncFileSystem API भी देखें.

स्टोरेज के विकल्प

पैकेज किए गए ऐप्लिकेशन, डेटा भेजने और पाने के लिए कई अलग-अलग तरीकों का इस्तेमाल करते हैं. बाहरी डेटा (संसाधन, वेब पेज) के लिए, आपको कॉन्टेंट की सुरक्षा के बारे में नीति (सीएसपी) के बारे में पता होना चाहिए. Chrome एक्सटेंशन की तरह ही, रिमोट सर्वर से संपर्क करने के लिए क्रॉस-ऑरिजिन XMLHttpRequests का इस्तेमाल किया जा सकता है. आपके पास बाहरी पेजों को भी अलग करने का विकल्प होता है. ऐसा करने से, आपके ऐप्लिकेशन के बाकी हिस्से सुरक्षित रहते हैं. ज़्यादा जानकारी के लिए, बाहरी वेब पेज एम्बेड करना लेख पढ़ें.

डेटा को स्थानीय तौर पर सेव करते समय, कम मात्रा में स्ट्रिंग डेटा सेव करने के लिए Chrome Storage API और स्ट्रक्चर्ड डेटा को सेव करने के लिए IndexedDB का इस्तेमाल किया जा सकता है. IndexedDB से, आप किसी ऑब्जेक्ट स्टोर में JavaScript ऑब्जेक्ट को बनाए रख सकते हैं. साथ ही, स्टोर के इंडेक्स का इस्तेमाल करके डेटा के लिए क्वेरी कर सकते हैं (ज़्यादा जानने के लिए, HTML5 Rock का आसान टूडो लिस्ट ट्यूटोरियल देखें). बाइनरी डेटा जैसे दूसरे सभी तरह के डेटा के लिए, फ़ाइल सिस्टम और सिंक फ़ाइल सिस्टम एपीआई का इस्तेमाल करें.

Chrome का Filesystem और Sync Filesystem API HTML5 FileSystem API को विस्तृत करता है. Chrome के Filesystem API से, ऐप्लिकेशन उपयोगकर्ता के लोकल फ़ाइल सिस्टम के सैंडबॉक्स किए गए सेक्शन को बना सकते हैं, पढ़ सकते हैं, नेविगेट कर सकते हैं, और उसमें लिख सकते हैं. उदाहरण के लिए, कोई फ़ोटो-शेयर करने वाला ऐप्लिकेशन, उपयोगकर्ता की चुनी गई किसी भी फ़ोटो को पढ़ने और लिखने के लिए, Filesystem API का इस्तेमाल कर सकता है.

Chrome के Sync Filesystem API से, ऐप्लिकेशन उपयोगकर्ता की Google डिस्क पर डेटा सेव कर सकते हैं और सिंक कर सकते हैं ताकि अलग-अलग क्लाइंट के लिए एक ही डेटा उपलब्ध हो सके. उदाहरण के लिए, क्लाउड-बैक्ड टेक्स्ट एडिटर ऐप्लिकेशन, उपयोगकर्ता के Google Drive खाते में नई टेक्स्ट फ़ाइलों को अपने-आप सिंक कर सकता है. जब उपयोगकर्ता किसी नए क्लाइंट में टेक्स्ट एडिटर खोलता है, तो Google Drive, टेक्स्ट एडिटर के उस इंस्टेंस में नई टेक्स्ट फ़ाइलें भेजता है.

Chrome Filesystem API का इस्तेमाल करना

फ़ाइल सिस्टम की अनुमति जोड़ी जा रही है

Chrome के फ़ाइल सिस्टम एपीआई का इस्तेमाल करने के लिए, आपको मेनिफ़ेस्ट में "fileSystem" अनुमति जोड़नी होगी, ताकि आप उपयोगकर्ता से स्थायी डेटा सेव करने की अनुमति ले सकें.

"permissions": [
  "...",
  "fileSystem"
]

फ़ाइलें चुनने के लिए उपयोगकर्ता के विकल्प

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

fileEntry का पाथ पाना

उपयोगकर्ता ने जिस फ़ाइल को चुना है उसका पूरा पाथ पाने के लिए, fileEntry को getDisplayPath() पर कॉल करें:

function displayPath(fileEntry) {
  chrome.fileSystem.getDisplayPath(fileEntry, function(path) {
    console.log(path)
  });
}

खींचें और छोड़ें सुविधा को लागू करना

अगर आपको 'खींचें और छोड़ें' विकल्प लागू करना है, तो filesystem-access सैंपल में मौजूद, 'खींचें और छोड़ें' फ़ाइल कंट्रोलर (dnd.js) इस्तेमाल करना बेहतर होगा. कंट्रोलर, 'खींचें और छोड़ें' सुविधा की मदद से, DataTransferItem से फ़ाइल एंट्री बनाता है. इस उदाहरण में, fileEntry को पहले छोड़े गए आइटम पर सेट किया गया है.

var dnd = new DnDFileController('body', function(data) {
  var fileEntry = data.items[0].webkitGetAsEntry();
  displayPath(fileEntry);
});

फ़ाइल पढ़ना

यह कोड फ़ाइल (रीड-ओनली ऐक्सेस) खोलता है और उसे FileReader ऑब्जेक्ट का इस्तेमाल करके, टेक्स्ट के तौर पर पढ़ता है. अगर फ़ाइल मौजूद नहीं है, तो गड़बड़ी होती है.

var chosenFileEntry = null;

chooseFileButton.addEventListener('click', function(e) {
  chrome.fileSystem.chooseEntry({type: 'openFile'}, function(readOnlyEntry) {

    readOnlyEntry.file(function(file) {
      var reader = new FileReader();

      reader.onerror = errorHandler;
      reader.onloadend = function(e) {
        console.log(e.target.result);
      };

      reader.readAsText(file);
    });
    });
});

फ़ाइल लिखना

फ़ाइल लिखने के दो सामान्य इस्तेमाल के उदाहरण हैं "सेव करें" और "इस रूप में सेव करें". यह कोड, रीड-ओनली chosenFileEntry से एक writableEntry बनाता है और चुनी गई फ़ाइल को उसमें लिख देता है.

 chrome.fileSystem.getWritableEntry(chosenFileEntry, function(writableFileEntry) {
    writableFileEntry.createWriter(function(writer) {
      writer.onerror = errorHandler;
      writer.onwriteend = callback;

    chosenFileEntry.file(function(file) {
      writer.write(file);
    });
  }, errorHandler);
});

यह कोड "इस रूप में सेव करें" फ़ंक्शन के साथ एक नई फ़ाइल बनाता है और writer.write() तरीके का इस्तेमाल करके, फ़ाइल में नया ब्लॉब लिखता है.

chrome.fileSystem.chooseEntry({type: 'saveFile'}, function(writableFileEntry) {
    writableFileEntry.createWriter(function(writer) {
      writer.onerror = errorHandler;
      writer.onwriteend = function(e) {
        console.log('write complete');
      };
      writer.write(new Blob(['1234567890'], {type: 'text/plain'}));
    }, errorHandler);
});

Chrome Sync Filesystem API का इस्तेमाल करना

सिंक किए जा सकने वाले फ़ाइल स्टोरेज का इस्तेमाल करके, लौटाए गए डेटा ऑब्जेक्ट को FileSystem API में लोकल ऑफ़लाइन फ़ाइल सिस्टम की तरह ही ऑपरेट किया जा सकता है. हालांकि, उस डेटा को Google Drive में जोड़ने (और अपने-आप) सिंक होने की प्रोसेस के दौरान, इन ऑब्जेक्ट को प्रोसेस किया जा सकता है.

फ़ाइल सिस्टम को सिंक करने की अनुमति जोड़ी जा रही है

Chrome के Sync Filesystem API का इस्तेमाल करने के लिए, आपको मेनिफ़ेस्ट में "syncFileSystem" अनुमति जोड़ना होगा, ताकि आप स्थायी डेटा को सेव और सिंक करने के लिए उपयोगकर्ता से अनुमति ले सकें.

"permissions": [
  "...",
  "syncFileSystem"
]

सिंक किया जा सकने वाला फ़ाइल स्टोरेज शुरू किया जा रहा है

अपने ऐप्लिकेशन में सिंक किया जा सकने वाला फ़ाइल स्टोरेज शुरू करने के लिए, बस syncFileSystem.requestFileSystem को कॉल करें. इस तरीके से, Google Drive का इस्तेमाल करके सिंक किया जा सकने वाला फ़ाइल सिस्टम दिखाया जाता है. उदाहरण के लिए:

chrome.syncFileSystem.requestFileSystem(function (fs) {
   // FileSystem API should just work on the returned 'fs'.
   fs.root.getFile('test.txt', {create:true}, getEntryCallback, errorCallback);
});

फ़ाइल के सिंक होने की स्थिति के बारे में जानकारी

मौजूदा फ़ाइल के लिए सिंक की स्थिति पाने के लिए, syncFileSystem.getFileStatus का इस्तेमाल करें:

chrome.syncFileSystem.getFileStatus(entry, function(status) {...});

फ़ाइल सिंक करने की स्थिति की वैल्यू इनमें से कोई एक हो सकती है: 'synced', 'pending' या 'conflicting'. 'सिंक की गई' का मतलब है कि फ़ाइल पूरी तरह सिंक हो गई है. ऐसा कोई भी स्थानीय बदलाव मौजूद नहीं है जिसे Google Drive के साथ सिंक न किया गया हो. हालांकि, Google Drive की साइड में कुछ ऐसे बदलाव हो सकते हैं जिन्हें अभी तक फ़ेच नहीं किया गया है.

'मंज़ूरी मिलनी बाकी है' का मतलब है कि फ़ाइल में ऐसे बदलाव हैं जिनकी मंज़ूरी बाकी है. यह बदलाव अभी तक Google Drive के साथ सिंक नहीं हुआ है. अगर ऐप्लिकेशन ऑनलाइन चल रहा है, तो स्थानीय बदलाव (करीब) Google Drive के साथ तुरंत सिंक हो जाते हैं. साथ ही, syncFileSystem.onFileStatusChanged इवेंट को 'synced' स्थिति के साथ सक्रिय किया जाता है (ज़्यादा जानकारी के लिए नीचे देखें).

जब फ़ाइल की स्थिति 'conflicting' में बदल जाती है, तब syncFileSystem.onFileStatusChanged ट्रिगर होते हैं. 'विरोधी' का मतलब है कि लोकल स्टोरेज और Google Drive, दोनों में कॉन्फ़्लिक्टिंग चेंज हुए हैं. फ़ाइल इस स्थिति में सिर्फ़ तब हो सकती है, जब विवाद सुलझाने की नीति 'manual' पर सेट हो. डिफ़ॉल्ट नीति 'last_write_win' है और विवादों का समाधान, आखिरी बार लिखने के बाद आसान नीति के ज़रिए अपने-आप कर दिया जाता है. ऐसे में, सिस्टम की विरोधाभास समाधान नीति को syncFileSystem.setConflictResolutionPolicy के ज़रिए बदला जा सकता है.

अगर विवाद के समाधान की नीति, 'manual' पर सेट है और फ़ाइल की स्थिति 'conflicting' है, तो ऐप्लिकेशन अब भी फ़ाइल को लोकल ऑफ़लाइन फ़ाइल के तौर पर पढ़ सकता है और लिख सकता है. हालांकि, बदलावों को सिंक नहीं किया जाएगा. साथ ही, विवाद के हल होने तक, फ़ाइल को दूसरे क्लाइंट पर कहीं से भी किए जाने वाले बदलावों से अलग रखा जाएगा. किसी विरोध का समाधान करने का सबसे आसान तरीका फ़ाइल के स्थानीय वर्शन को हटाना या उसका नाम बदलना है. इससे रिमोट वर्शन को हर हाल में सिंक किया जाता है, गड़बड़ी की स्थिति को ठीक किया जाता है, और onFileStatusChanged इवेंट को 'synced' स्टेटस के साथ ट्रिगर किया जाता है.

सिंक की गई स्थिति में हुए बदलावों को सुना जा रहा है

फ़ाइल के सिंक होने की स्थिति बदलने पर, syncFileSystem.onFileStatusChanged इवेंट ट्रिगर होता है. उदाहरण के लिए, मान लें कि किसी फ़ाइल में बदलाव लागू होने बाकी हैं और वह 'मंज़ूरी बाकी है' स्थिति में है. हो सकता है कि ऐप्लिकेशन ऑफ़लाइन स्थिति में हो, ताकि बदलाव सिंक होने वाला हो. जब सिंक सेवा, मंज़ूरी बाकी होने वाले स्थानीय बदलाव का पता लगाती है और उस बदलाव को Google Drive में अपलोड करती है, तो सेवा onFileStatusChanged इवेंट को नीचे दी गई वैल्यू के साथ ट्रिगर करती है: { fileEntry:a fileEntry for the file, status: 'synced', action: 'updated', direction: 'local_to_remote' }.

इसी तरह, स्थानीय गतिविधियों पर ध्यान दिए बिना, सिंक सेवा किसी दूसरे क्लाइंट की तरफ़ से कहीं से भी किए गए बदलावों का पता लगा सकती है और उन बदलावों को Google Drive से लोकल स्टोरेज में डाउनलोड कर सकती है. अगर रिमोट में किया गया बदलाव किसी नई फ़ाइल को जोड़ने के लिए किया गया था, तो नीचे दी गई वैल्यू वाला इवेंट ट्रिगर होता है: { fileEntry: a fileEntry for the file, status: 'synced', action: 'added', direction: 'remote_to_local' }.

अगर लोकल और रिमोट, दोनों साइड में एक ही फ़ाइल के लिए कॉन्फ़्लिक्टिंग वाले बदलाव हैं और विरोधाभास को हल करने की नीति 'manual' पर सेट की जाती है, तो फ़ाइल का स्टेटस conflicting की स्थिति में बदल जाता है और उसे सिंक सेवा से अलग कर दिया जाता है. साथ ही, समस्या का समाधान होने तक उसे सिंक नहीं किया जाएगा. इस मामले में, नीचे दी गई वैल्यू वाला इवेंट ट्रिगर होगा: { fileEntry: a fileEntry for the file, status: 'conflicting', action: null, direction: null }.

इस इवेंट के लिए, ऐसा लिसनर जोड़ा जा सकता है जो स्टेटस में हुए किसी भी बदलाव के बाद जवाब दे. उदाहरण के लिए, Chrome Music Player ऐप्लिकेशन, Google Drive से सिंक किए गए किसी भी नए संगीत को सुनता है, लेकिन अब तक किसी खास क्लाइंट के लिए उपयोगकर्ता के लोकल स्टोरेज में इंपोर्ट नहीं किया गया है. कोई भी संगीत उस क्लाइंट के साथ सिंक हो जाता है:

chrome.syncFileSystem.onFileStatusChanged.addListener(function(fileInfo) {
  if (fileInfo.status === 'synced') {
    if (fileInfo.direction === 'remote_to_local') {
      if (fileInfo.action === 'added') {
        db.add(fileInfo.fileEntry);
      } else if (fileInfo.action === 'deleted') {
        db.remove(fileInfo.fileEntry);
      }
    }
  }
});

एपीआई के इस्तेमाल की जांच की जा रही है

यह देखने के लिए कि एपीआई कितना डेटा इस्तेमाल कर रहा है, ऐप्लिकेशन की लोकल सैंडबॉक्स डायरेक्ट्री या syncFileSystem.getUsageAndQuota से मिली इस्तेमाल की बाइट की क्वेरी करें:

chrome.syncFileSystem.getUsageAndQuota(fileSystem, function (storageInfo) {
   updateUsageInfo(storageInfo.usageBytes);
   updateQuotaInfo(storageInfo.quotaBytes);
});

आपके पास उपयोगकर्ता का सिंक किया गया बैकएंड सेवा स्टोरेज (Google Drive में) देखने का विकल्प भी होता है. सिंक की गई फ़ाइलें एक छिपे हुए Google Drive फ़ोल्डर, Chrome Syncable FileSystem में सेव की जाती हैं. यह फ़ोल्डर आपकी 'मेरी ड्राइव' सूची में नहीं दिखेगा. हालांकि, इसे खोजने के लिए खोज बॉक्स में फ़ोल्डर का नाम खोजें. (ध्यान दें कि रिमोट फ़ोल्डर का लेआउट, रिलीज़ के बीच पुराने सिस्टम के साथ काम करने की गारंटी नहीं देता है.)