फिर से शुरू किए जा सकने वाले अपलोड

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

फिर से शुरू किए जा सकने वाले अपलोड का इस्तेमाल, नीचे दिए गए किसी भी मामले में, खास तौर पर मददगार होता है:

  • आप बड़ी फ़ाइलें ट्रांसफ़र कर रहे हैं.
  • नेटवर्क में रुकावट आने की संभावना बहुत ज़्यादा है.
  • अपलोड की शुरुआत ऐसे डिवाइस से हो रही है जिसकी बैंडविड्थ कम है या इंटरनेट कनेक्शन ठीक नहीं है, जैसे मोबाइल डिवाइस.

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

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

httplib2.debuglevel = 4

पहला चरण - एक फिर से शुरू करने वाला सेशन शुरू करें

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

https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=PARTS

अनुरोध के मुख्य हिस्से को video संसाधन पर सेट करें. साथ ही, एचटीटीपी अनुरोध के इन हेडर को भी सेट करें:

  • Authorization – अनुरोध के लिए अनुमति टोकन.
  • Content-Length – अनुरोध के मुख्य हिस्से में दिए गए बाइट की संख्या. ध्यान दें कि अगर डोमेन के हिस्सों को ट्रांसफ़र करने का तरीका बदला गया है, तो आपको यह हेडर देने की ज़रूरत नहीं है.
  • Content-Type – वैल्यू को application/json; charset=UTF-8 पर सेट करें.
  • X-Upload-Content-Length – बाइट की संख्या, जिन्हें बाद के अनुरोधों में अपलोड किया जाएगा. इस मान को फ़ाइल के उस आकार के अनुसार सेट करें, जिसे आप अपलोड कर रहे हैं.
  • x-upload-content-type – आपको फ़ाइल का MIME टाइप अपलोड करना है. आप किसी भी MIME टाइप (video/*) या MIME टाइप application/octet-stream वाली फ़ाइलें अपलोड कर सकते हैं.

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

post /upload/youtube/v3/videos?uploadType=resumable&part=parts http/1.1
host: www.googleapis.com
authorization: bearer auth_token
content-length: content_length
content-type: application/json; charset=utf-8
x-upload-content-length: x_upload_content_length
X-Upload-Content-Type: X_UPLOAD_CONTENT_TYPE

video resource

यहां दिए गए उदाहरण में, ऐसा POST अनुरोध दिखाया गया है जिसमें ये सभी वैल्यू, पुष्टि करने वाले टोकन के अपवाद से भरी हुई हैं. उदाहरण में दिया गया categoryId वैल्यू, वीडियो की कैटगरी से मेल खाता है. एपीआई के videoCategories.list तरीके का इस्तेमाल करके, काम करने वाली कैटगरी की सूची फिर से पाई जा सकती है.

POST /upload/youtube/v3/videos?uploadType=resumable&part=snippet,status,contentDetails HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer AUTH_TOKEN
Content-Length: 278
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Length: 3000000
X-Upload-Content-Type: video/*

{
  "snippet": {
    "title": "My video title",
    "description": "This is a description of my video",
    "tags": ["cool", "video", "more keywords"],
    "categoryId": 22
  },
  "status": {
    "privacyStatus": "public",
    "embeddable": True,
    "license": "youtube"
  }
}

दूसरा चरण - फिर से शुरू करने वाले सेशन का यूआरआई सेव करें

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

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

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&upload_id=xa298sd_f&part=snippet,status,contentDetails
Content-Length: 0

तीसरा चरण - वीडियो फ़ाइल अपलोड करें

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

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: CONTENT_LENGTH
Content-Type: CONTENT_TYPE

BINARY_FILE_DATA

अनुरोध नीचे दिए गए एचटीटीपी अनुरोध के हेडर सेट करता है:

  • Authorization – अनुरोध के लिए अनुमति टोकन.
  • Content-Length – उस फ़ाइल का साइज़ जिसे अपलोड किया जा रहा है. यह वैल्यू, पहले चरण में X-Upload-Content-Length एचटीटीपी अनुरोध के हेडर के वैल्यू के बराबर होनी चाहिए.
  • Content-Type – फ़ाइल का MIME टाइप जिसे अपलोड किया जा रहा है. यह वैल्यू, पहले चरण में X-Upload-Content-Type एचटीटीपी अनुरोध के हेडर के वैल्यू के बराबर होनी चाहिए.

चौथा चरण - अपलोड करने की प्रोसेस पूरी करना

आपका अनुरोध इनमें से किसी एक स्थिति पर ले जाएगा:

  • आपका अपलोड हो गया.

    एपीआई सर्वर, एचटीटीपी 201 (Created) रिस्पॉन्स कोड के साथ जवाब देता है. रिस्पॉन्स का मुख्य हिस्सा video संसाधन है जिसे आपने बनाया है.

  • आपका अपलोड पूरा नहीं हुआ, लेकिन उसे फिर से शुरू किया जा सकता है.

    आप इनमें से किसी भी मामले में, अपलोड को फिर से शुरू कर सकते हैं:

    • आपके ऐप्लिकेशन और एपीआई सर्वर के बीच कनेक्शन टूट जाने की वजह से, आपके अनुरोध में रुकावट आई है. इस मामले में, आपको एपीआई से जवाब नहीं मिलेगा.

    • एपीआई रिस्पॉन्स, इनमें से किसी भी 5xx रिस्पॉन्स कोड के बारे में बताता है. इनमें से किसी भी रिस्पॉन्स कोड को पाने के बाद, कोड को फिर से शुरू करते समय, एक्सपोनेंशियल बैकऑफ़ वाली रणनीति का इस्तेमाल किया जाना चाहिए.

      • 500 – Internal Server Error
      • 502 – Bad Gateway
      • 503 – Service Unavailable
      • 504 – Gateway Timeout

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

  • आपका वीडियो हमेशा के लिए अपलोड नहीं हो सका.

    अपलोड न हो पाने पर, दिए गए जवाब में गड़बड़ी का जवाब दिया जाता है, जो गड़बड़ी की वजह बताता है. अगर अपलोड पूरा नहीं हो पाता है, तो एपीआई रिस्पॉन्स में रिस्पॉन्स कोड के तौर पर 4xx या ऊपर दिए गए कोड के अलावा 5xx का कोड होगा.

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

चौथा चरण.1: अपलोड की स्थिति देखें

फिर से शुरू किए जा सकने वाले दोबारा अपलोड किए जा सकने वाले स्टेटस की जांच करने के लिए, अपलोड किए गए यूआरएल के साथ खाली पीयूटी अनुरोध भेजें. यह अनुरोध आपको दूसरे चरण में मिला था और आपने तीसरे चरण में भी इसका इस्तेमाल किया था. अपने अनुरोध में, Content-Range हेडर वैल्यू को bytes */CONTENT_LENGTH पर सेट करें. यहां CONTENT_LENGTH का साइज़ उस फ़ाइल का साइज़ है जिसे अपलोड किया जा रहा है.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 0
Content-Range: bytes */CONTENT_LENGTH

चरण 4.2: एपीआई के रिस्पॉन्स को प्रोसेस करना

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

हालांकि, अगर अपलोड में रुकावट आई थी या वह अब भी चल रहा है, तो एपीआई रिस्पॉन्स में एचटीटीपी 308 (Resume Incomplete) रिस्पॉन्स कोड होगा. रिस्पॉन्स में, Range हेडर बताता है कि फ़ाइल के कितने बाइट पहले ही अपलोड किए जा चुके हैं.

  • हेडर की वैल्यू 0 से इंडेक्स की गई है. इसी तरह, 0-999999 की हेडर वैल्यू यह दिखाती है कि फ़ाइल की पहली 1,000,000 बाइट अपलोड हो गई हैं.
  • अगर अब तक कुछ भी अपलोड नहीं किया गया है, तो एपीआई रिस्पॉन्स में Range हेडर शामिल नहीं होगा.

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

308 Resume Incomplete
Content-Length: 0
Range: bytes=0-999999

अगर एपीआई रिस्पॉन्स में Retry-After हेडर भी शामिल है, तो उस हेडर की वैल्यू का इस्तेमाल करके, यह तय करें कि अपलोड को फिर से कब शुरू करना है.

चौथा चरण: 3.अपलोड फिर से शुरू करना

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

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: REMAINING_CONTENT_LENGTH
Content-Range: bytes FIRST_BYTE-LAST_BYTE/TOTAL_CONTENT_LENGTH

PARTIAL_BINARY_FILE_DATA

आपको नीचे दिए गए एचटीटीपी अनुरोध के हेडर सेट करने होंगे:

  • Authorization – अनुरोध के लिए अनुमति टोकन.

  • Content-Length – बाइट का साइज़, जिसे अभी तक अपलोड नहीं किया गया है. अगर आप किसी फ़ाइल का बचा हुआ हिस्सा अपलोड कर रहे हैं, तो आप TOTAL_CONTENT_LENGTH मान में से FIRST_BYTE मान को घटाकर इस मान का हिसाब लगा सकते हैं. दोनों वैल्यू का इस्तेमाल, Content-Range हेडर में किया जाता है.

  • Content-Range – फ़ाइल का वह हिस्सा जिसे अपलोड किया जा रहा है. हेडर वैल्यू में तीन वैल्यू होती हैं:

    • FIRST_BYTE – बाइट नंबर का 0 पर आधारित अंकों वाला इंडेक्स, जिससे आपने अपलोड फिर से शुरू किया है. यह वैल्यू, पिछले चरण में मिले Range हेडर के दूसरे नंबर से ज़्यादा है. पिछले उदाहरण में, Range हेडर की वैल्यू 0-999999 थी. इसलिए, बाद में फिर से अपलोड किए जाने वाले डेटा की पहली बाइट 1000000 होगी.

    • LAST_BYTE – आपकी अपलोड की जा रही बाइनरी फ़ाइल के आखिरी बाइट का 0-आधारित अंकों वाला इंडेक्स. आम तौर पर, यह फ़ाइल में आखिरी बाइट होती है. उदाहरण के लिए, अगर फ़ाइल का साइज़ 3000000 बाइट है, तो फ़ाइल में आखिरी बाइट, संख्या 2999999 होगी.

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

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

    उदाहरण के लिए, फिर से शुरू किए गए अपलोड में अपलोड की गई पहली बाइट, अगली बाइट के बाद की होनी चाहिए. इस बाइट को पहले ही YouTube पर अपलोड कर दिया गया है. (चरण 4.2 में Range हेडर पर चर्चा देखें.

    इस तरह, अगर Range हेडर का आखिरी बाइट 999999 है, तो अपलोड दोबारा शुरू करने के अनुरोध में, सबसे पहले बाइट 10,00,000 होनी चाहिए. (दोनों संख्याएं 0-आधारित इंडेक्स का उपयोग करती हैं.) अगर आप अपलोड को बाइट 9999999 या उससे कम (ओवरलैपिंग बाइट) या बाइट 1000001 या उससे ऊपर (बाइट को छोड़कर) से फिर से शुरू करने की कोशिश करते हैं, तो कोई भी बाइनरी सामग्री अपलोड नहीं की जाएगी.

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

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

अलग-अलग हिस्सों में फ़ाइल अपलोड करने के निर्देश, इस गाइड में पहले बताए गए चार चरणों वाली प्रोसेस से मेल खाते हैं. हालांकि, किसी फ़ाइल को अपलोड करना शुरू करने के लिए (ऊपर दिया गया तीसरा चरण) और फिर से अपलोड शुरू करने का अनुरोध (चरण 4.3), दोनों के लिए फ़ाइल के हिस्से में फ़ाइल अपलोड करते समय, Content-Length और Content-Range हेडर की वैल्यू अलग-अलग सेट होती हैं.

  • Content-Length हेडर की वैल्यू, डेटा के उस हिस्से के बारे में बताती है जिसे अनुरोध भेजा जा रहा है. हिस्से के आकार से जुड़ी इन पाबंदियों पर ध्यान दें:

    • समूह का साइज़ 256 केबी से ज़्यादा होना चाहिए. (यह पाबंदी आखिरी हिस्से पर लागू नहीं होती, क्योंकि पूरी फ़ाइल का साइज़ 256 केबी से ज़्यादा का नहीं हो सकता.) याद रखें कि बड़े हिस्से ज़्यादा कारगर होते हैं.

    • आखिरी अनुरोध को छोड़कर, अपलोड के क्रम में हर अनुरोध के लिए डेटा समूह का साइज़ एक ही होना चाहिए. इससे आखिरी हिस्से का साइज़ पता चलता है.

  • Content-Range हेडर, फ़ाइल में मौजूद बाइट की जानकारी देता है. इस वैल्यू को सेट करते समय, चौथे चरण से 4.3 में Content-Range हेडर सेट करने के निर्देश लागू होते हैं.

    उदाहरण के लिए, bytes 0-524287/2000000 की वैल्यू यह बताती है कि अनुरोध, 2,000,000 बाइट की फ़ाइल में शुरुआती 5,24,288 बाइट (256 x 2048) भेज रहा है.

नीचे दिए गए उदाहरण में, अनुरोधों की सीरीज़ के पहले फ़ॉर्मैट का फ़ॉर्मैट दिखाया गया है जो अलग-अलग हिस्सों में 20,00,000 बाइट की फ़ाइल अपलोड करेगा:

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 524888
Content-Type: video/*
Content-Range: bytes 0-524287/2000000

{bytes 0-524287}

अगर आखिरी अनुरोध के अलावा कोई दूसरा अनुरोध पूरा होता है, तो एपीआई सर्वर 308 (Resume Incomplete) रिस्पॉन्स देता है. जवाब का फ़ॉर्मैट ठीक वैसा ही होगा जैसा ऊपर चरण 4.2: एपीआई के जवाब को प्रोसेस करना में बताया गया है.

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

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

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

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