अटैचमेंट अपलोड करें

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

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

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

फ़ाइल अपलोड करने के लिए, पिछले चरण में मिले अपलोड यूआरआई पर 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 के कुछ क्लास के अनुरोधों के लिए ऐसा होता है. इससे, पुराने ब्राउज़र के लिए अपलोड की प्रोग्रेस दिखाने जैसी चीज़ें भी की जा सकती हैं. इन ब्राउज़र में, डिफ़ॉल्ट रूप से अपलोड की प्रोग्रेस दिखाने की सुविधा नहीं होती.

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

अगर जवाब मिलने से पहले, अपलोड का अनुरोध खत्म हो जाता है या आपको सर्वर से HTTP 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 सेकंड का कुल डिले होता है. बार-बार अनुरोध करने की ज़्यादा से ज़्यादा संख्या तय की जा सकती है. खास तौर पर, अगर कोई लंबा अपलोड चल रहा है. हालांकि, यह पक्का करें कि बार-बार अनुरोध करने के बीच का डिले, एक मिनट से कम हो.

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