मीडिया अपलोड करें

मीडिया आइटम अपलोड करने की प्रोसेस में दो चरण होते हैं:

1. uploads एंडपॉइंट का इस्तेमाल करके, अपनी मीडिया फ़ाइलों के बाइट को Google सर्वर पर अपलोड करें. इससे एक अपलोड टोकन मिलता है. यह अपलोड किए गए बाइट की पहचान करता है.
2. अपलोड टोकन के साथ batchCreate कॉल का इस्तेमाल करके, उपयोगकर्ता के Google Photos खाते में मीडिया आइटम बनाएं.

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

शुरू करने से पहले

अनुमति पाने के ज़रूरी लिंक

किसी उपयोगकर्ता की लाइब्रेरी या एल्बम में मीडिया आइटम अपलोड करने के लिए, photoslibrary.appendonly स्कोप की ज़रूरत होती है. स्कोप के बारे में ज़्यादा जानने के लिए, अनुमति के स्कोप देखें.

स्वीकार किए जाने वाले फ़ाइल टाइप और साइज़

इस टेबल में दिए गए फ़ाइल टाइप अपलोड किए जा सकते हैं.

पहला चरण: बाइट अपलोड करना

अपलोड करने के अनुरोधों का इस्तेमाल करके, Google पर बाइट अपलोड करना. अपलोड करने का अनुरोध पूरा होने पर, अपलोड टोकन मिलता है. यह एक रॉ टेक्स्ट स्ट्रिंग के तौर पर होता है. batchCreate कॉल के साथ मीडिया आइटम बनाने के लिए, इन अपलोड टोकन का इस्तेमाल करें.

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-type: application/octet-stream
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: raw

media-binary-data

upload-token

हमारा सुझाव है कि इमेज की फ़ाइल का साइज़ 50 एमबी से कम हो. 50 एमबी से बड़ी फ़ाइलों की वजह से, परफ़ॉर्मेंस से जुड़ी समस्याएं हो सकती हैं.

Google Photos Library API, फिर से शुरू किए जा सकने वाले अपलोड की सुविधा के साथ काम करता है. फिर से शुरू किए जा सकने वाले अपलोड की सुविधा की मदद से, मीडिया फ़ाइल को कई सेक्शन में बांटा जा सकता है. साथ ही, एक बार में एक सेक्शन अपलोड किया जा सकता है.

दूसरा चरण: मीडिया आइटम बनाना

मीडिया फ़ाइलों के बाइट अपलोड करने के बाद, अपलोड टोकन का इस्तेमाल करके उन्हें Google Photos में मीडिया आइटम के तौर पर बनाया जा सकता है. अपलोड टोकन, जनरेट होने के एक दिन बाद तक मान्य रहता है. मीडिया आइटम हमेशा उपयोगकर्ता की लाइब्रेरी में जोड़ा जाता है. मीडिया आइटम सिर्फ़ आपके ऐप्लिकेशन से बनाए गए ऐल्बम में जोड़े जा सकते हैं. ज़्यादा जानकारी के लिए, अनुमति के स्कोप देखें.

नए मीडिया आइटम बनाने के लिए, newMediaItems की सूची तय करके mediaItems.batchCreate को कॉल करें. हर newMediaItem में एक अपलोड टोकन होता है, जिसे simpleMediaItem में तय किया जाता है. साथ ही, इसमें एक ब्यौरा भी होता है, जिसे उपयोगकर्ता को दिखाया जाता है.

ब्यौरे वाले फ़ील्ड में सिर्फ़ 1,000 वर्ण इस्तेमाल किए जा सकते हैं. साथ ही, इसमें सिर्फ़ ऐसा टेक्स्ट शामिल होना चाहिए जो उपयोगकर्ताओं ने बनाया हो और जो काम का हो. उदाहरण के लिए, "पार्क की हमारी यात्रा" या "छुट्टियों के दौरान किया गया डिनर". फ़ाइल के नाम, प्रोग्राम के हिसाब से काम करने वाले टैग या अपने-आप जनरेट होने वाले अन्य टेक्स्ट जैसे मेटाडेटा को शामिल न करें.

बेहतरीन परफ़ॉर्मेंस के लिए, एक कॉल में कई मीडिया आइटम शामिल करके, mediaItems.batchCreate को किए जाने वाले कॉल की संख्या कम करें. हमेशा पिछले अनुरोध के पूरा होने का इंतज़ार करें. इसके बाद ही, उसी उपयोगकर्ता के लिए अगला कॉल करें.

उपयोगकर्ता की लाइब्रेरी में एक या एक से ज़्यादा मीडिया आइटम बनाए जा सकते हैं. इसके लिए, आपको ब्यौरे और उनसे जुड़े अपलोड टोकन देने होंगे:

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer oauth2-token

{
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

एल्बम में किसी खास जगह पर मीडिया आइटम डालने के लिए, albumId और albumPosition का इस्तेमाल भी किया जा सकता है.

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
    , ...
  ],
  "albumPosition": {
    "position": "after-media-item",
    "relativeMediaItemId": "media-item-id"
  }
}

एल्बम में फ़ोटो की पोज़िशन के बारे में ज़्यादा जानकारी के लिए, फ़ोटो में बदलाव करना लेख पढ़ें.

आइटम बनाने के अनुरोध का जवाब

mediaItems.batchCreate कॉल, बनाए गए हर मीडिया आइटम का नतीजा दिखाता है. newMediaItemResults की सूची में, अनुरोध की स्थिति दिखती है. साथ ही, इसमें अनुरोध के लिए uploadToken भी शामिल होता है. शून्य से अलग स्टेटस कोड का मतलब है कि कोई गड़बड़ी हुई है.

{
  "newMediaItemResults": [
    {
      "uploadToken": "upload-token",
      "status": {
        "message": "Success"
      },
      "mediaItem": {
        "id": "media-item-id",
        "description": "item-description",
        "productUrl": "https://photos.google.com/photo/photo-path",
        "mimeType": "mime-type",
        "mediaMetadata": {
          "width": "media-width-in-px",
          "height": "media-height-in-px",
          "creationTime": "creation-time",
          "photo": {}
        },
        "filename": "filename"
      }
    },
    {
      "uploadToken": "upload-token",
      "status": {
        "code": 13,
        "message": "Internal error"
      }
    }
  ]
}

अगर कोई आइटम जोड़ दिया जाता है, तो mediaItem दिखता है. इसमें आइटम का mediaItemId, productUrl, और mediaMetadata शामिल होता है. ज़्यादा जानकारी के लिए, मीडिया आइटम ऐक्सेस करना लेख पढ़ें.

अगर मीडिया आइटम कोई वीडियो है, तो उसे पहले प्रोसेस किया जाना चाहिए. mediaItem में mediaMetadata होता है. इसमें वीडियो फ़ाइल की प्रोसेसिंग की स्थिति के बारे में बताया जाता है.status नई फ़ाइल अपलोड करने पर, इस्तेमाल के लिए READY होने से पहले, PROCESSING स्टेटस दिखता है. ज़्यादा जानकारी के लिए, मीडिया आइटम ऐक्सेस करना लेख पढ़ें.

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

नतीजे हमेशा उसी क्रम में दिखाए जाते हैं जिस क्रम में अपलोड टोकन सबमिट किए गए थे.

अपलोड करने के सबसे सही तरीके

यहां दिए गए सबसे सही तरीके और संसाधन, अपलोड करने की प्रोसेस को बेहतर बनाने में आपकी मदद करते हैं:

• फिर से कोशिश करने और गड़बड़ी ठीक करने के सबसे सही तरीके अपनाएं. साथ ही, इन बातों का ध्यान रखें:
  • 429 गड़बड़ियां तब हो सकती हैं, जब आपका कोटा खत्म हो गया हो या आपने बहुत कम समय में बहुत ज़्यादा कॉल किए हों. पक्का करें कि जब तक पिछली अनुरोध पूरा नहीं हो जाता, तब तक एक ही उपयोगकर्ता के लिए batchCreate को कॉल न करें.
  • 429 गड़बड़ियों को ठीक करने के लिए, कम से कम 30s समय तक इंतज़ार करना ज़रूरी है. अनुरोधों को फिर से भेजने के लिए, एक्सपोनेंशियल बैकऑफ़ रणनीति का इस्तेमाल करें.
  • सर्वर में कोई गड़बड़ी होने पर, 500 गड़बड़ियां होती हैं. अपलोड करते समय, ऐसा इसलिए होता है, क्योंकि एक ही समय में एक ही उपयोगकर्ता के लिए कई राइट कॉल (जैसे कि batchCreate) किए जाते हैं. अपने अनुरोध की जानकारी देखें और batchCreate को एक साथ कॉल न करें.
• अपलोड फिर से शुरू करने की सुविधा का इस्तेमाल करें. इससे नेटवर्क में रुकावट आने पर भी, अपलोड को ज़्यादा भरोसेमंद तरीके से पूरा किया जा सकता है. साथ ही, बैंडविथ का इस्तेमाल कम किया जा सकता है. ऐसा इसलिए, क्योंकि इस सुविधा की मदद से, अधूरे अपलोड को फिर से शुरू किया जा सकता है. क्लाइंट के मोबाइल डिवाइसों से अपलोड करते समय या बड़ी फ़ाइलें अपलोड करते समय, यह ज़रूरी है.

साथ ही, अपलोड करने की प्रोसेस के हर चरण के लिए, इन सुझावों को ध्यान में रखें: बाइट अपलोड करना और फिर मीडिया आइटम बनाना.

बाइट अपलोड करना

• अपलोड टोकन पाने के लिए, बाइट अपलोड करने की प्रोसेस को साथ-साथ किया जा सकता है.
• हर अपलोड कॉल के लिए, X-Goog-Upload-Content-Type हेडर में हमेशा सही MIME टाइप सेट करें.

मीडिया आइटम बनाना

• एक उपयोगकर्ता के लिए, batchCreate के साथ-साथ कॉल न करें.

  • हर उपयोगकर्ता के लिए, batchCreate को एक के बाद एक कॉल करें.
  • एक से ज़्यादा उपयोगकर्ताओं के लिए, हमेशा हर उपयोगकर्ता के लिए एक के बाद एक batchCreate कॉल करें. सिर्फ़ अलग-अलग उपयोगकर्ताओं के लिए एक साथ कॉल करें.

• batchCreate को किए जाने वाले हर कॉल में, ज़्यादा से ज़्यादा NewMediaItems शामिल करें, ताकि आपको कम से कम कॉल करने पड़ें. ज़्यादा से ज़्यादा 50 आइटम शामिल किए जा सकते हैं.

• उपयोगकर्ताओं की ओर से बनाए गए ब्यौरे वाले टेक्स्ट को सेट करें. ब्यौरे वाले फ़ील्ड में, फ़ाइल के नाम, प्रोग्रामैटिक टैग या अपने-आप जनरेट होने वाले अन्य टेक्स्ट जैसे मेटाडेटा को शामिल न करें.

उदाहरण के लिए सिलसिलेवार तरीके से दिए गए निर्देश

इस उदाहरण में, एक से ज़्यादा उपयोगकर्ताओं के लिए मीडिया आइटम अपलोड करने की प्रोसेस को समझने के लिए, सूडोकोड का इस्तेमाल किया गया है. इस गाइड का मकसद, अपलोड करने की प्रोसेस के दोनों चरणों (रॉ बाइट अपलोड करना और मीडिया आइटम बनाना) के बारे में बताना है. साथ ही, अपलोड करने की प्रोसेस को बेहतर और आसान बनाने के सबसे सही तरीकों के बारे में जानकारी देना है.

पहला चरण: रॉ बाइट अपलोड करना

सबसे पहले, अपने सभी उपयोगकर्ताओं के मीडिया आइटम के लिए रॉ बाइट अपलोड करने के लिए एक कतार बनाएं. हर उपयोगकर्ता के हिसाब से, वापस किए गए हर uploadToken को ट्रैक करें. इन ज़रूरी बातों का ध्यान रखें:

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

CREATE uploadQueue FROM users, filesToUpload
// Upload media bytes in parallel.
START multiple THREADS
  WHILE uploadQueue is not empty
    POP uploadQueue
    UPLOAD file for user
    GET uploadToken
    CHECK and HANDLE errors
    STORE uploadToken for user in uploadTokensQueue
  END

दूसरा चरण: मीडिया आइटम बनाना

पहले चरण में, एक साथ कई उपयोगकर्ताओं के कई बाइट अपलोड किए जा सकते हैं. हालांकि, दूसरे चरण में एक बार में सिर्फ़ एक उपयोगकर्ता के लिए कॉल किया जा सकता है.

// For each user, create media items once 50 upload tokens have been
// saved, or no more uploads are left per user.
WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user
  // Calls can be made in parallel for different users,
  // but only make a single call per user at a time.
  START new thread for (this) user if there is no thread yet
    POP 50 uploadTokens from uploadTokensQueue for user
    CALL mediaItems.batchCreate with uploadTokens
    WAIT UNTIL batchCreate call has completed
    CHECK and HANDLE errors (retry as needed)
  DONE.

जब तक सभी अपलोड और मीडिया बनाने के कॉल पूरे नहीं हो जाते, तब तक इस प्रोसेस को जारी रखें.