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

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

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

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

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

आसान तरीके से अपलोड करने के लिए, POST या PUT अनुरोध को /upload यूआरआई पर भेजें. साथ ही, क्वेरी पैरामीटर 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 अनुरोध किया जा सकता है. अगर भेजा जा रहा डेटा इतना छोटा है कि कनेक्शन फ़ेल होने पर उसे फिर से पूरी तरह अपलोड किया जा सकता है, तो यह तरीका सबसे सही है.

मल्टीपार्ट अपलोड का इस्तेमाल करने के लिए, POST या PUT अनुरोध को तरीके के /upload यूआरआई पर भेजें और क्वेरी पैरामीटर 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. फ़ाइल अपलोड करें. मीडिया फ़ाइल को फिर से शुरू किए जा सकने वाले सेशन के यूआरआई पर भेजें.

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

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

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

फिर से शुरू किए जा सकने वाले अपलोड की प्रोसेस शुरू करने के लिए, POST या PUT अनुरोध को /upload यूआरआई पर भेजें. साथ ही, क्वेरी पैरामीटर 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 शामिल है. इस वैल्यू को, इस अनुरोध में अपलोड किए जा रहे बाइट की संख्या पर सेट करें. आम तौर पर, यह अपलोड की गई फ़ाइल का साइज़ होता है.

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

यहां मौजूदा उदाहरण के लिए, 20,00,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 हेडर शामिल होना चाहिए. इससे पता चलता है कि फ़ाइल में मौजूदा पोज़िशन की जानकारी नहीं है.  उदाहरण के लिए, अगर आपकी फ़ाइल की कुल लंबाई 20,00,000 है, तो Content-Range को */2000000 पर सेट करें. अगर आपको फ़ाइल के पूरे साइज़ के बारे में नहीं पता है, तो Content-Range को */* पर सेट करें.

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

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

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

इस अनुरोध में Content-Range हेडर का इस्तेमाल किया गया है. इससे पता चलता है कि 20,00,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 सर्वर की गड़बड़ी दिखती है, तो एक्सपोनेंशियल बैकऑफ़ रणनीति का इस्तेमाल करें. अगर सर्वर पर बहुत ज़्यादा लोड है, तो ये गड़बड़ियां हो सकती हैं. अनुरोधों की संख्या ज़्यादा होने या नेटवर्क ट्रैफ़िक ज़्यादा होने पर, इस तरह की समस्याओं को कम करने में एक्सपोनेंशियल बैकऑफ़ मदद कर सकता है.
  • अन्य तरह के अनुरोधों को एक्स्पोनेंशियल बैकऑफ़ से हैंडल नहीं किया जाना चाहिए. हालांकि, इनमें से कुछ अनुरोधों को फिर से आज़माया जा सकता है. इन अनुरोधों को फिर से भेजने की कोशिश करते समय, इनकी संख्या सीमित रखें. उदाहरण के लिए, आपका कोड गड़बड़ी की सूचना देने से पहले, फिर से कोशिश करने की संख्या को दस या उससे कम तक सीमित कर सकता है.
  • अपलोड फिर से शुरू करने की सुविधा का इस्तेमाल करते समय, 404 Not Found और 410 Gone गड़बड़ियों को ठीक करें. इसके लिए, पूरे अपलोड को शुरू से शुरू करें.

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

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

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

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

  1. एपीआई से अनुरोध करें.
  2. आपको HTTP 503 जवाब मिलता है. इसका मतलब है कि आपको अनुरोध फिर से करना चाहिए.
  3. एक सेकंड + random_number_milliseconds इंतज़ार करें और फिर से अनुरोध करें.
  4. आपको HTTP 503 जवाब मिलता है. इसका मतलब है कि आपको अनुरोध फिर से करना चाहिए.
  5. दो सेकंड + random_number_milliseconds इंतज़ार करने के बाद, अनुरोध को फिर से भेजें.
  6. आपको HTTP 503 जवाब मिलता है. इसका मतलब है कि आपको अनुरोध फिर से करना चाहिए.
  7. चार सेकंड + random_number_milliseconds इंतज़ार करें और फिर से अनुरोध करें.
  8. आपको HTTP 503 जवाब मिलता है. इसका मतलब है कि आपको अनुरोध फिर से करना चाहिए.
  9. आठ सेकंड + 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 सेकंड की देरी होती है. ज़्यादा से ज़्यादा बार फिर से कोशिश करने की सुविधा ठीक है. खास तौर पर, अगर कोई फ़ाइल अपलोड होने में ज़्यादा समय लग रहा हो. हालांकि, यह पक्का करें कि फिर से कोशिश करने के बीच का समय कम हो. जैसे, एक मिनट से कम.

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