Play Games Services Publishing API की मदद से इमेज अपलोड करना

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

Play Games Services Publishing API की मदद से, किसी गेम के संसाधन के लिए इमेज अपलोड की जा सकती है.

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

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

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

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

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

• आसान अपलोड: uploadType=media. छोटी फ़ाइलों को तुरंत ट्रांसफ़र करने के लिए. उदाहरण के लिए, 5 एमबी या इससे कम साइज़ की फ़ाइलें.

• मल्टीपार्ट अपलोड: uploadType=multipart. छोटी फ़ाइलों और मेटाडेटा को तुरंत ट्रांसफ़र करने के लिए. यह एक ही अनुरोध में, फ़ाइल के साथ-साथ उसके बारे में बताने वाले मेटाडेटा को भी ट्रांसफ़र करता है.

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

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

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

  उदाहरण: POST /upload/games/v1configuration/images/resourceId/imageType/imageType

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

  उदाहरण: POST /games/v1configuration/images/resourceId/imageType/imageType

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

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

• अगर कनेक्शन ठीक से काम नहीं करता है, तो फ़ाइल को फिर से पूरी तरह से अपलोड किया जा सकता है.

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

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media

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

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

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

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

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

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/png
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

PNG data

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

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

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

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

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

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart

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

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

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

अनुरोध के मुख्य हिस्से को एक से ज़्यादा हिस्सों वाले/मिलते-जुलते कॉन्टेंट टाइप के तौर पर फ़ॉर्मैट किया गया है, जो आरएफ़सी2387 के मुताबिक है. इसमें ठीक दो हिस्से होते हैं. हिस्सों की पहचान, बॉर्डर स्ट्रिंग से की जाती है. साथ ही, आखिरी बॉर्डर स्ट्रिंग के बाद दो हाइफ़न होते हैं.

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

• मेटाडेटा का हिस्सा: यह पहले होना चाहिए. साथ ही, Content-Type का फ़ॉर्मैट, स्वीकार किए गए मेटाडेटा फ़ॉर्मैट में से किसी एक से मेल खाना चाहिए.

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

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

ध्यान दें: सिर्फ़ मेटाडेटा का हिस्सा बनाने या अपडेट करने के लिए, उससे जुड़ा डेटा अपलोड किए बिना, स्टैंडर्ड रिसॉर्स एंडपॉइंट पर POST या PUT अनुरोध भेजें: https://www.googleapis.com/games/v1configuration/images/resourceId/imageType/imageType

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

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

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?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

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

--foo_bar_baz
Content-Type: image/png

PNG data
--foo_bar_baz--

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

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

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

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

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

1. ऐसा सेशन शुरू करें जिसे बाद में फिर से शुरू किया जा सके. अपलोड करने के लिए उस यूआरआई का शुरुआती अनुरोध करें जिसमें मेटाडेटा शामिल हो.

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

3. मीडिया फ़ाइल को फिर से शुरू किए जा सकने वाले सेशन के यूआरआई पर भेजें.

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

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

फिर से शुरू किया जा सकने वाला सेशन शुरू करना

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

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable

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

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

• X-Upload-Content-Type. अपलोड किए गए डेटा के मीडिया MIME टाइप पर सेट करें, ताकि उसे अगले अनुरोधों में ट्रांसफ़र किया जा सके.

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

• अगर मेटाडेटा दिया जा रहा है, तो: Content-Type. मेटाडेटा के डेटा टाइप के हिसाब से सेट करें.

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

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

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

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

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?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: image/png
X-Upload-Content-Length: 2000000

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

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

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

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

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

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

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

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

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

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

फ़ाइल अपलोड करना

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

PUT session_uri

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

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

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

PUT https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/png

bytes 0-1999999

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

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

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

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

अगर डेटा को अलग-अलग हिस्सों में अपलोड किया जा रहा है, तो Content-Range हेडर भी ज़रूरी है. साथ ही, पूरी फ़ाइल अपलोड करने के लिए Content-Length हेडर भी ज़रूरी है:

• Content-Length. इसे चंक साइज़ या उससे कम पर सेट करें, जैसा कि पिछले अनुरोध के लिए हो सकता है.

• Content-Range. अपलोड की जा रही फ़ाइल में कौनसे बाइट दिखाने हैं, यह सेट करें. उदाहरण के लिए, Content-Range: bytes 0-524287/2000000 से पता चलता है कि 2,000,000 बाइट की फ़ाइल में, पहले 5,24,288 बाइट (256 x 1024 x 2) भेजे जा रहे हैं.

ध्यान दें: अपलोड पूरा करने वाले आखिरी चंक को छोड़कर, सभी चंक का साइज़ 256 केबी (256 x 1024 बाइट) का होना चाहिए. अगर डेटा को अलग-अलग हिस्सों में बांटा जाता है, तो अपलोड की प्रोसेस को बेहतर बनाने के लिए, चंक्स का साइज़ जितना हो सके उतना बड़ा रखना ज़रूरी है.

ज़्यादा जानकारी के लिए विस्तृत करें

अगर डेटा को अलग-अलग हिस्सों में अपलोड किया जा रहा है, तो पूरी फ़ाइल अपलोड करने के लिए ज़रूरी Content-Length हेडर के साथ-साथ Content-Range हेडर भी ज़रूरी है:

• Content-Length. इसे चंक साइज़ या उससे कम पर सेट करें, जैसा कि पिछले अनुरोध के लिए हो सकता है.
• Content-Range: यह सेट करें कि अपलोड की जा रही फ़ाइल के कौनसे बाइट दिखाने हैं.  उदाहरण के लिए, Content-Range: bytes 0-524287/2000000 से पता चलता है कि 2,000,000 बाइट की फ़ाइल में, पहले 5,24,288 बाइट (256 x 1024 x 2) दिए जा रहे हैं.

चंक के साइज़ से जुड़ी पाबंदी: अपलोड पूरा करने वाले आखिरी चंक को छोड़कर, सभी चंक का साइज़ 256 केबी (256 x 1024 बाइट) का होना चाहिए. अगर डेटा को अलग-अलग हिस्सों में बांटकर अपलोड किया जा रहा है, तो अपलोड की प्रोसेस को बेहतर बनाने के लिए, चंक्स का साइज़ जितना हो सके उतना बड़ा रखें.

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

पहला 5,24,288 बाइट भेजने वाला अनुरोध कुछ ऐसा दिख सकता है:

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: image/jpeg
Content-Range: bytes 0-524287/2000000

bytes 0-524288

अगर अनुरोध पूरा हो जाता है, तो सर्वर 308 Resume Incomplete के साथ-साथ Range हेडर का जवाब देता है. इस हेडर से, अब तक सेव किए गए बाइट की कुल संख्या का पता चलता है:

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

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

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

अहम जानकारी:

• रिस्पॉन्स में Range हेडर का इस्तेमाल करना न भूलें, ताकि यह तय किया जा सके कि अगला चंक कहां से शुरू करना है. यह मत मानें कि सर्वर को पिछले अनुरोध में भेजे गए सभी बाइट मिले हैं.
• हर अपलोड यूआरआई की समयसीमा तय होती है. अगर इसका इस्तेमाल नहीं किया जाता है, तो यह एक दिन या उससे कम समय में खत्म हो जाता है. इस वजह से, अपलोड यूआरआई मिलने के तुरंत बाद, फिर से शुरू किया जा सकने वाला अपलोड शुरू करना सबसे अच्छा होता है. साथ ही, रुका हुआ अपलोड फिर से शुरू करने के लिए, रुकावट आने के कुछ समय बाद ही ऐसा करना चाहिए.
• अगर अपलोड सेशन के खत्म हो चुके आईडी के साथ अनुरोध भेजा जाता है, तो सर्वर 404 Not Found स्टेटस कोड दिखाता है. अपलोड सेशन में ऐसी गड़बड़ी होने पर जिसे ठीक नहीं किया जा सकता, तो सर्वर 410 Gone स्टेटस कोड दिखाता है. ऐसे मामलों में, आपको फिर से शुरू किया जा सकने वाला नया अपलोड शुरू करना होगा, अपलोड का नया यूआरआई पाना होगा, और नए एंडपॉइंट का इस्तेमाल करके अपलोड को फिर से शुरू करना होगा.

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

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

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

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

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

2. अपलोड किए गए बाइट की संख्या देखना. स्टेटस क्वेरी से मिले रिस्पॉन्स को प्रोसेस करें. सर्वर अपने रिस्पॉन्स में Range हेडर का इस्तेमाल करके बताता है कि उसे अब तक कौनसे बाइट मिले हैं. उदाहरण के लिए, Range का 0-299999 हेडर यह दिखाता है कि फ़ाइल के पहले 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 बाइट मिल चुके हैं. फिर से शुरू किए गए अपलोड को कहां से शुरू करना है, यह तय करने के लिए रेंज हेडर की ऊपरी वैल्यू का इस्तेमाल करें.

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

   ध्यान दें: हो सकता है कि अपलोड पूरा होने पर, स्टेटस के तौर पर 201बनाया गया या 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 response मिलता है, जिससे पता चलता है कि आपको अनुरोध फिर से करना चाहिए.
9. 8 सेकंड + random_number_milliseconds इंतज़ार करें और फिर से कोशिश करें.
10. आपको HTTP 503 response मिलता है, जिससे पता चलता है कि आपको अनुरोध फिर से करना चाहिए.
11. 16 सेकंड + random_number_milliseconds इंतज़ार करें और फिर से कोशिश करें.
12. बंद करो। गड़बड़ी की शिकायत करें या उसे लॉग करें.

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

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

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

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

• .NET

• Java

• PHP

• Python

• Ruby