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

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

फ़ाइल अपलोड करने के विकल्प

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

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

मौजूदा उदाहरण के लिए, ईमेल मैसेज की पूरी 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 हेडर का इस्तेमाल करता है, ताकि यह तय किया जा सके कि उसे अब तक कौनसी बाइट मिली हैं. उदाहरण के लिए, 0-299999 का Range हेडर बताता है कि फ़ाइल की शुरुआती 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. 1 सेकंड + random_number_मिलीसेकंड तक इंतज़ार करें और फिर से कोशिश करें.
  4. HTTP 503 जवाब पाएं. इससे पता चलता है कि आपको फिर से अनुरोध करने की कोशिश करनी चाहिए.
  5. दो सेकंड + random_number_मिलीसेकंड तक इंतज़ार करें और फिर से कोशिश करें.
  6. HTTP 503 जवाब पाएं. इससे पता चलता है कि आपको फिर से अनुरोध करने की कोशिश करनी चाहिए.
  7. 4 सेकंड रैंडम नंबर_मिलीसेकंड तक इंतज़ार करें और फिर से कोशिश करें.
  8. HTTP 503 जवाब पाएं. इससे पता चलता है कि आपको फिर से अनुरोध करने की कोशिश करनी चाहिए.
  9. आठ सेकंड से ज़्यादा समय तक किसी भी समय इंतज़ार करें और फिर से कोशिश करें.
  10. HTTP 503 जवाब पाएं. इससे पता चलता है कि आपको फिर से अनुरोध करने की कोशिश करनी चाहिए.
  11. 16 सेकंड + यादृच्छिक_number_मिलीसेकंड तक इंतज़ार करें और फिर से अनुरोध करें.
  12. वीडियो बंद करने के लिए. किसी गड़बड़ी की रिपोर्ट करें या उसे लॉग करें.

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

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

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

API क्लाइंट लाइब्रेरी गाइड