अटैचमेंट अपलोड किए जा रहे हैं

Gmail API की मदद से, ड्राफ़्ट बनाते या अपडेट करते समय या मैसेज डालते या भेजते समय, फ़ाइल का डेटा अपलोड किया जा सकता है.

अपलोड के विकल्प

Gmail API की मदद से, कुछ खास तरह का बाइनरी डेटा या मीडिया अपलोड किया जा सकता है. मीडिया अपलोड करने की सुविधा वाले किसी भी तरीके के लिए, रेफ़रंस पेज पर अपलोड किए जा सकने वाले डेटा की खास विशेषताओं के बारे में बताया गया है:

  • अपलोड की जा सकने वाली फ़ाइल का ज़्यादा से ज़्यादा साइज़: इस तरीके से, ज़्यादा से ज़्यादा कितना डेटा स्टोर किया जा सकता है.
  • स्वीकार किए गए मीडिया MIME टाइप: इस तरीके का इस्तेमाल करके, इस तरह का बाइनरी डेटा सेव किया जा सकता है.

अपलोड करने के अनुरोध इनमें से किसी भी तरीके से किए जा सकते हैं. uploadType अनुरोध पैरामीटर के साथ इस्तेमाल किए जा रहे तरीके की जानकारी दें.

  • आसान अपलोड: uploadType=media. छोटी फ़ाइलों को तुरंत ट्रांसफ़र करने के लिए. उदाहरण के लिए, 5 एमबी या उससे कम साइज़ की फ़ाइलें.
  • मल्टीपार्ट अपलोड: uploadType=multipart. छोटी फ़ाइलों और मेटाडेटा को तुरंत ट्रांसफ़र करने के लिए. यह एक ही अनुरोध में, फ़ाइल के साथ-साथ उसके बारे में बताने वाले मेटाडेटा को भी ट्रांसफ़र करता है.
  • फिर से शुरू किया जा सकने वाला अपलोड: uploadType=resumable. भरोसेमंद तरीके से ट्रांसफ़र करने के लिए, खास तौर पर बड़ी फ़ाइलों के लिए ज़रूरी है. इस तरीके में, सेशन शुरू करने के अनुरोध का इस्तेमाल किया जाता है. इसमें मेटाडेटा शामिल किया जा सकता है. हालांकि, ऐसा करना ज़रूरी नहीं है. ज़्यादातर ऐप्लिकेशन के लिए, यह एक अच्छी रणनीति है. ऐसा इसलिए है, क्योंकि यह छोटी फ़ाइलों के लिए भी काम करती है. हालांकि, इसके लिए हर अपलोड के लिए एक अतिरिक्त एचटीटीपी अनुरोध करना पड़ता है.

मीडिया अपलोड करते समय, किसी खास यूआरआई का इस्तेमाल किया जाता है. असल में, मीडिया अपलोड करने की सुविधा वाले तरीकों में दो यूआरआई एंडपॉइंट होते हैं:

  • मीडिया के लिए /upload यूआरआई. अपलोड एंडपॉइंट का फ़ॉर्मैट, स्टैंडर्ड संसाधन यूआरआई होता है. इसमें “/upload” प्रीफ़िक्स होता है. मीडिया डेटा को खुद ट्रांसफ़र करते समय, इस यूआरआई का इस्तेमाल करें.

    उदाहरण: POST /upload/gmail/v1/users/userId/messages/send

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

    उदाहरण: POST /gmail/v1/users/userId/messages/send

आसानी से अपलोड करना

फ़ाइल अपलोड करने का सबसे आसान तरीका, अपलोड करने का अनुरोध करना है. यह विकल्प तब चुनें, जब:

  • फ़ाइल इतनी छोटी हो कि अगर इंटरनेट कनेक्शन टूट जाए, तो उसे फिर से पूरी तरह से अपलोड किया जा सके.
  • भेजने के लिए कोई मेटाडेटा नहीं है. ऐसा तब हो सकता है, जब आपने इस संसाधन के लिए मेटाडेटा को किसी अलग अनुरोध में भेजने का प्लान किया हो या कोई मेटाडेटा काम न करता हो या उपलब्ध न हो.

आसान अपलोड का इस्तेमाल करने के लिए, तरीके के /upload यूआरआई पर POST या PUT अनुरोध करें और क्वेरी पैरामीटर uploadType=media जोड़ें. उदाहरण के लिए:

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=media

आसानी से अपलोड करने का अनुरोध करते समय, इन एचटीटीपी हेडर का इस्तेमाल किया जा सकता है:

  • Content-Type. एपीआई के रेफ़रंस में बताए गए, अपलोड किए जाने वाले मीडिया डेटा के टाइप में से किसी एक पर सेट करें.
  • Content-Length. अपलोड किए जा रहे बाइट की संख्या पर सेट करें. अगर चंक किए गए ट्रांसफ़र को कोड में बदलने की सुविधा का इस्तेमाल किया जा रहा है, तो इसकी ज़रूरत नहीं है.

उदाहरण: आसानी से अपलोड करना

यहां दिए गए उदाहरण में, Gmail API के लिए, अपलोड करने के सामान्य अनुरोध का इस्तेमाल दिखाया गया है.

POST /upload/gmail/v1/users/userId/messages/send?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: message/rfc822
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

Email Message data

अनुरोध पूरा होने पर, सर्वर किसी भी मेटाडेटा के साथ एचटीटीपी 200 OK स्टेटस कोड दिखाता है:

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

मल्टीपार्ट अपलोड

अगर आपके पास ऐसा मेटाडेटा है जिसे आपको अपलोड किए जाने वाले डेटा के साथ भेजना है, तो एक multipart/related अनुरोध किया जा सकता है. अगर भेजा जा रहा डेटा इतना छोटा है कि कनेक्शन टूटने पर उसे फिर से पूरा अपलोड किया जा सकता है, तो यह एक अच्छा विकल्प है.

एक से ज़्यादा फ़ाइलों को अपलोड करने की सुविधा का इस्तेमाल करने के लिए, /upload यूआरआई वाले तरीके के लिए POST या PUT अनुरोध करें. साथ ही, क्वेरी पैरामीटर uploadType=multipart जोड़ें. उदाहरण के लिए:

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=multipart

एक से ज़्यादा हिस्सों में अपलोड करने का अनुरोध करते समय, इन टॉप-लेवल एचटीटीपी हेडर का इस्तेमाल किया जा सकता है:

  • Content-Type. इसे multipart/related पर सेट करें और अनुरोध के हिस्सों की पहचान करने के लिए, वह बॉर्डर स्ट्रिंग शामिल करें जिसका इस्तेमाल किया जा रहा है.
  • Content-Length. इसे अनुरोध के मुख्य हिस्से में मौजूद बाइट की कुल संख्या पर सेट करें. अनुरोध का मीडिया हिस्सा, इस तरीके के लिए तय किए गए फ़ाइल के ज़्यादा से ज़्यादा साइज़ से कम होना चाहिए.

अनुरोध के मुख्य हिस्से को multipart/related कॉन्टेंट टाइप [RFC2387] के तौर पर फ़ॉर्मैट किया जाता है. इसमें दो हिस्से होते हैं. हिस्सों की पहचान, बॉर्डर स्ट्रिंग से की जाती है. आखिरी बॉर्डर स्ट्रिंग के बाद दो हाइफ़न होते हैं.

कई हिस्सों वाले अनुरोध के हर हिस्से के लिए, एक अतिरिक्त Content-Type हेडर की ज़रूरत होती है:

  1. मेटाडेटा वाला हिस्सा: यह पहले होना चाहिए. साथ ही, Content-Type को स्वीकार किए गए मेटाडेटा फ़ॉर्मैट में से किसी एक से मैच करना चाहिए.
  2. मीडिया का हिस्सा: यह दूसरे नंबर पर होना चाहिए. साथ ही, Content-Type को उस तरीके के स्वीकार किए गए मीडिया MIME टाइप से मेल खाना चाहिए.

अपलोड की गई फ़ाइलों के लिए स्वीकार किए जाने वाले मीडिया MIME टाइप और साइज़ की सीमाओं की सूची के लिए, हर तरीके का एपीआई रेफ़रंस देखें.

ध्यान दें: इससे जुड़ा डेटा अपलोड किए बिना, सिर्फ़ मेटाडेटा का हिस्सा बनाने या अपडेट करने के लिए, स्टैंडर्ड रिसॉर्स एंडपॉइंट पर POST या PUT अनुरोध भेजें: https://www.googleapis.com/gmail/v1/users/userId/messages/send

उदाहरण: कई हिस्सों में अपलोड करना

नीचे दिए गए उदाहरण में, Gmail API के लिए एक से ज़्यादा फ़ाइलें अपलोड करने का अनुरोध दिखाया गया है.

POST /upload/gmail/v1/users/userId/messages/send?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

--foo_bar_baz
Content-Type: message/rfc822

Email Message data
--foo_bar_baz--

अगर अनुरोध पूरा हो जाता है, तो सर्वर किसी भी मेटाडेटा के साथ एचटीटीपी 200 OK स्टेटस कोड दिखाता है:

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

फिर से अपलोड किया जा सकता है

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

फिर से शुरू किए जा सकने वाले अपलोड का इस्तेमाल करने के लिए, यह तरीका अपनाएं:

  1. फिर से शुरू किया जा सकने वाला सेशन शुरू करें. अपलोड यूआरआई के लिए शुरुआती अनुरोध करें. अगर मेटाडेटा है, तो उसे भी शामिल करें.
  2. फिर से शुरू किए जा सकने वाले सेशन का यूआरआई सेव करें. शुरुआती अनुरोध के जवाब में मिले सेशन यूआरआई को सेव करें. इस सेशन में बाकी अनुरोधों के लिए, इसका इस्तेमाल किया जाएगा.
  3. फ़ाइल अपलोड करें. मीडिया फ़ाइल को फिर से शुरू किए जा सकने वाले सेशन के यूआरआई पर भेजें.

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

ध्यान दें: अपलोड यूआरआई की समयसीमा एक हफ़्ते के बाद खत्म हो जाती है.

पहला चरण: फिर से शुरू किया जा सकने वाला सेशन शुरू करना

फिर से शुरू किया जा सकने वाला अपलोड शुरू करने के लिए, अपलोड करने के तरीके के /upload यूआरएल पर POST या PUT अनुरोध करें और क्वेरी पैरामीटर uploadType=resumable जोड़ें. उदाहरण के लिए:

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable

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

शुरुआती अनुरोध के साथ, इन एचटीटीपी हेडर का इस्तेमाल करें:

  • X-Upload-Content-Type. बाद के अनुरोधों में ट्रांसफ़र किए जाने वाले अपलोड किए गए डेटा के मीडिया MIME टाइप पर सेट करें.
  • X-Upload-Content-Length. इसकी वैल्यू, अपलोड किए गए उस डेटा के बाइट की संख्या पर सेट करें जिसे बाद के अनुरोधों में ट्रांसफ़र करना है.  अगर अनुरोध करने के समय, स्ट्रिंग की लंबाई की जानकारी नहीं है, तो इस हेडर को छोड़ा जा सकता है.
  • अगर मेटाडेटा दिया जा रहा है, तो: Content-Type. मेटाडेटा के डेटा टाइप के हिसाब से सेट करें.
  • Content-Length. इस शुरुआती अनुरोध के मुख्य हिस्से में दी गई बाइट की संख्या पर सेट करें. अगर चंक किए गए ट्रांसफ़र को कोड में बदलने की सुविधा का इस्तेमाल किया जा रहा है, तो इसकी ज़रूरत नहीं है.

अपलोड की गई फ़ाइलों के लिए स्वीकार किए जाने वाले मीडिया MIME टाइप और साइज़ की सीमाओं की सूची के लिए, हर तरीके का एपीआई रेफ़रंस देखें.

उदाहरण: फिर से शुरू किया जा सकने वाला सेशन शुरू करने का अनुरोध

यहां दिए गए उदाहरण में, Gmail API के लिए फिर से शुरू किया जा सकने वाला सेशन शुरू करने का तरीका बताया गया है.

POST /upload/gmail/v1/users/userId/messages/send?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: message/rfc822
X-Upload-Content-Length: 2000000

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

ध्यान दें: मेटाडेटा के बिना, फिर से शुरू किए जा सकने वाले अपडेट के शुरुआती अनुरोध के लिए, अनुरोध के मुख्य हिस्से को खाली छोड़ दें और Content-Length हेडर को 0 पर सेट करें.

अगले सेक्शन में, रिस्पॉन्स को मैनेज करने का तरीका बताया गया है.

दूसरा चरण: फिर से शुरू किए जा सकने वाले सेशन का यूआरआई सेव करना

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

उदाहरण: फिर से शुरू किया जा सकने वाला सेशन शुरू करने का रिस्पॉन्स

पहले चरण में किए गए अनुरोध का जवाब यहां दिया गया है:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

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

सेशन यूआरआई को कॉपी करके सेव करें, ताकि आप बाद के अनुरोधों के लिए इसका इस्तेमाल कर सकें.

चरण 3: फ़ाइल अपलोड करें

फ़ाइल अपलोड करने के लिए, पिछले चरण में मिले अपलोड यूआरआई पर PUT अनुरोध भेजें. अपलोड करने के अनुरोध का फ़ॉर्मैट यह है:

PUT session_uri

फ़ाइल अपलोड करने के लिए, फिर से शुरू किए जा सकने वाले अनुरोध करते समय इस्तेमाल किए जाने वाले एचटीटीपी हेडर में Content-Length शामिल होता है. इसे इस अनुरोध में अपलोड किए जा रहे बाइट की संख्या पर सेट करें. आम तौर पर, यह अपलोड की जाने वाली फ़ाइल का साइज़ होता है.

उदाहरण: फ़ाइल अपलोड करने का अनुरोध, जिसे फिर से शुरू किया जा सकता है

यहां मौजूदा उदाहरण के लिए, 2,000,000 बाइट की ईमेल मैसेज फ़ाइल को अपलोड करने के लिए, फिर से शुरू किया जा सकने वाला अनुरोध दिया गया है.

PUT https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: message/rfc822

bytes 0-1999999

अनुरोध पूरा होने पर, सर्वर इस संसाधन से जुड़े किसी भी मेटाडेटा के साथ HTTP 201 Created का जवाब देता है. अगर फिर से शुरू किए जा सकने वाले सेशन का शुरुआती अनुरोध PUT था, तो किसी मौजूदा संसाधन को अपडेट करने के लिए, सफलता का रिस्पॉन्स  200 OK होगा. साथ ही, इस संसाधन से जुड़ा कोई भी मेटाडेटा भी होगा.

अगर अपलोड के अनुरोध में रुकावट आती है या आपको सर्वर से HTTP 503 Service Unavailable या कोई अन्य 5xx जवाब मिलता है, तो रुका हुआ अपलोड फिर से शुरू करना में बताए गए तरीके का पालन करें.  

फ़ाइल को अलग-अलग हिस्सों में अपलोड करना

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

बीच में रुके हुए अपलोड को फिर से शुरू करना

अगर अपलोड का अनुरोध, जवाब मिलने से पहले ही खत्म हो जाता है या आपको सर्वर से एचटीटीपी 503 Service Unavailable रिस्पॉन्स मिलता है, तो आपको बीच में रुके हुए अपलोड को फिर से शुरू करना होगा. ऐसा करने के लिए:

  1. अनुरोध की स्थिति. अपलोड के यूआरआई पर खाली PUT अनुरोध भेजकर, अपलोड की मौजूदा स्थिति के बारे में क्वेरी करें. इस अनुरोध के लिए, एचटीटीपी हेडर में Content-Range हेडर शामिल होना चाहिए. इससे पता चलता है कि फ़ाइल में मौजूदा स्थिति की जानकारी नहीं है.  उदाहरण के लिए, अगर आपकी फ़ाइल की कुल लंबाई 2,000,000 है, तो Content-Range को */2000000 पर सेट करें. अगर आपको फ़ाइल का पूरा साइज़ नहीं पता है, तो Content-Range को */* पर सेट करें.

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

  2. अपलोड किए गए बाइट की संख्या देखें. स्टेटस क्वेरी से मिले रिस्पॉन्स को प्रोसेस करें. सर्वर अपने रिस्पॉन्स में Range हेडर का इस्तेमाल करके बताता है कि उसे अब तक कौनसे बाइट मिले हैं.  उदाहरण के लिए, 0-299999 का Range हेडर बताता है कि फ़ाइल के पहले 3,00,000 बाइट मिल चुके हैं.
  3. बचे हुए डेटा को अपलोड करें. आखिर में, अब जब आपको पता है कि अनुरोध को कहां से फिर से शुरू करना है, तो बाकी डेटा या मौजूदा चंक भेजें. ध्यान दें कि दोनों ही मामलों में, आपको बाकी डेटा को अलग चंक के तौर पर इस्तेमाल करना होगा. इसलिए, अपलोड फिर से शुरू करने पर, आपको Content-Range हेडर भेजना होगा.
उदाहरण: बीच में रुके हुए अपलोड को फिर से शुरू करना

1) अपलोड की स्थिति का अनुरोध करें.

नीचे दिए गए अनुरोध में Content-Range हेडर का इस्तेमाल करके यह बताया गया है कि 2,000,000 बाइट की फ़ाइल में मौजूदा स्थिति की जानकारी नहीं है.

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2) रिस्पॉन्स से, अब तक अपलोड किए गए बाइट की संख्या निकालें.

सर्वर के रिस्पॉन्स में Range हेडर का इस्तेमाल करके यह दिखाया जाता है कि उसे फ़ाइल के पहले 43 बाइट अब तक मिल चुके हैं. Range हेडर की ऊपरी वैल्यू का इस्तेमाल करके, यह तय करें कि फिर से शुरू किया गया अपलोड कहां से शुरू किया जाए.

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

ध्यान दें: ऐसा हो सकता है कि अपलोड पूरा होने पर, स्टेटस 201 Created या 200 OK दिखे. ऐसा तब हो सकता है, जब सभी बाइट अपलोड होने के बाद, क्लाइंट को सर्वर से जवाब मिलने से पहले ही कनेक्शन टूट गया हो.

3) अपलोड को वहीं से शुरू करें जहां से यह रुका था.

नीचे दिया गया अनुरोध, फ़ाइल के बचे हुए बाइट भेजकर अपलोड को फिर से शुरू करता है. यह बाइट 43 से शुरू होता है.

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

सबसे सही तरीके

मीडिया अपलोड करते समय, गड़बड़ी को हैंडल करने के सबसे सही तरीकों के बारे में जानना मददगार होता है.

  • कनेक्शन में रुकावट या 5xx से जुड़ी गड़बड़ियों की वजह से, अपलोड होने में रुकावट आने पर, उन्हें फिर से शुरू करना या अपलोड करने की कोशिश करना. इन गड़बड़ियों में ये शामिल हैं:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • अगर अपलोड के अनुरोधों को फिर से शुरू करने या दोबारा कोशिश करने पर, 5xx सर्वर की कोई गड़बड़ी दिखती है, तो एक्सपोनेंशियल बैकऑफ़ की रणनीति का इस्तेमाल करें. अगर सर्वर पर ज़्यादा लोड आ रहा है, तो ये गड़बड़ियां हो सकती हैं. ज़्यादा अनुरोधों या ज़्यादा नेटवर्क ट्रैफ़िक के दौरान, एक्सपोनेंशियल बैकऑफ़ से इस तरह की समस्याओं को कम करने में मदद मिल सकती है.
  • अन्य तरह के अनुरोधों को एक्सपोनेंशियल बैकऑफ़ की मदद से मैनेज नहीं किया जाना चाहिए. हालांकि, उनमें से कई अनुरोधों को फिर से भेजा जा सकता है. इन अनुरोधों को दोबारा भेजते समय, उन्हें ज़्यादा बार न भेजें. उदाहरण के लिए, आपका कोड गड़बड़ी की रिपोर्ट करने से पहले, ज़्यादा से ज़्यादा 10 बार या उससे कम बार कोशिश कर सकता है.
  • फिर से शुरू किए जा सकने वाले अपलोड करते समय, 404 Not Found और 410 Gone गड़बड़ियों को ठीक करने के लिए, पूरा अपलोड फिर से शुरू करें.

एक्सपोनेंशियल बैकऑफ़

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

सही तरीके से इस्तेमाल करने पर, एक्सपोनेंशियल बैकऑफ़, बैंडविड्थ के इस्तेमाल की क्षमता को बढ़ाता है. साथ ही, सही जवाब पाने के लिए ज़रूरी अनुरोधों की संख्या को कम करता है और एक साथ कई अनुरोधों को प्रोसेस करने की क्षमता को बढ़ाता है.

आसान एक्सपोनेंशियल बैकऑफ़ लागू करने का तरीका यह है:

  1. एपीआई से अनुरोध करें.
  2. आपको HTTP 503 वाला जवाब मिलता है. इससे पता चलता है कि आपको अनुरोध फिर से करना चाहिए.
  3. 1 सेकंड + random_number_milliseconds इंतज़ार करें और फिर से कोशिश करें.
  4. आपको HTTP 503 वाला जवाब मिलता है. इससे पता चलता है कि आपको अनुरोध फिर से करना चाहिए.
  5. दो सेकंड + random_number_milliseconds इंतज़ार करें और फिर से कोशिश करें.
  6. आपको HTTP 503 कोड वाला जवाब मिलता है. इससे पता चलता है कि आपको अनुरोध फिर से करना चाहिए.
  7. चार सेकंड + random_number_milliseconds इंतज़ार करें और फिर से कोशिश करें.
  8. आपको HTTP 503 कोड वाला जवाब मिलता है. इससे पता चलता है कि आपको अनुरोध फिर से करना चाहिए.
  9. 8 सेकंड + random_number_milliseconds इंतज़ार करें और फिर से कोशिश करें.
  10. आपको HTTP 503 वाला जवाब मिलता है. इससे पता चलता है कि आपको अनुरोध फिर से करना चाहिए.
  11. 16 सेकंड + random_number_milliseconds इंतज़ार करें और फिर से कोशिश करें.
  12. बंद करो। गड़बड़ी की शिकायत करें या उसे लॉग करें.

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

ध्यान दें: इंतज़ार का समय हमेशा (2 ^ n) + random_number_milliseconds होता है. यहां n, एक ऐसा पूर्णांक होता है जो लगातार बढ़ता रहता है और जिसे शुरुआत में 0 के तौर पर तय किया जाता है. हर बार (हर अनुरोध) के लिए, पूर्णांक n को 1 से बढ़ाया जाता है.

एल्गोरिदम, n के 5 होने पर बंद हो जाता है. यह सीमा, क्लाइंट को बार-बार कोशिश करने से रोकती है. साथ ही, किसी अनुरोध को "ठीक नहीं की जा सकने वाली गड़बड़ी" माना जाने से पहले, करीब 32 सेकंड की देरी होती है. ज़्यादा बार कोशिश करने की सुविधा चालू रखी जा सकती है. खास तौर पर, अगर लंबी अवधि तक अपलोड किया जा रहा है, तो ऐसा करना ज़रूरी है. हालांकि, कोशिश करने के बीच में लगने वाले समय को एक मिनट से कम रखें.

एपीआई क्लाइंट लाइब्रेरी से जुड़ी गाइड