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

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

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

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

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

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

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

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

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

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

यहां दिए गए उदाहरण में, 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 सर्वर की गड़बड़ी मिलती है, तो एक्स्पोनेंशियल बैकऑफ़ रणनीति का इस्तेमाल करें. ये गड़बड़ियां तब हो सकती हैं, जब सर्वर पर लोड ज़्यादा हो. एक्स्पोनेंशियल बैकऑफ़ की मदद से, अनुरोधों की संख्या ज़्यादा होने या नेटवर्क ट्रैफ़िक ज़्यादा होने पर, इस तरह की समस्याओं को कम किया जा सकता है.
  • अन्य तरह के अनुरोधों को एक्स्पोनेंशियल बैकऑफ़ से मैनेज नहीं किया जाना चाहिए. हालांकि, उनमें से कई अनुरोधों को फिर से सबमिट किया जा सकता है. इन अनुरोधों को फिर से सबमिट करते समय, अनुरोधों की संख्या को सीमित करें. उदाहरण के लिए, गड़बड़ी की रिपोर्ट करने से पहले, आपका कोड फिर से कोशिश करने की संख्या को 10 या उससे कम तक सीमित कर सकता है.
  • फिर से अपलोड किए जा सकने वाले अपलोड करते समय, 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. Wait 8 seconds + random_number_milliseconds, and retry the request.
  10. HTTP 503 जवाब मिलना. इससे पता चलता है कि आपको अनुरोध फिर से करना चाहिए.
  11. 16 सेकंड + random_number_milliseconds इंतज़ार करें और फिर से अनुरोध करें.
  12. बंद करो। किसी गड़बड़ी की शिकायत करना या उसे लॉग करना.

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

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

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

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