คุณสามารถอัปโหลดวิดีโอได้อย่างน่าเชื่อถือมากขึ้นโดยใช้โปรโตคอลการอัปโหลดที่กลับมาทํางานอีกครั้งสําหรับ Google APIs โปรโตคอลนี้ช่วยให้คุณดําเนินการอัปโหลดต่อได้หลังเครือข่ายขัดข้องหรือการรับส่งข้อมูลอื่นๆ ไม่ช่วยประหยัดเวลาและแบนด์วิดท์ในกรณีที่เครือข่ายล้มเหลว
การใช้การอัปโหลดที่กลับมาทํางานอีกครั้งจะเป็นประโยชน์อย่างยิ่งในกรณีต่อไปนี้
- คุณกําลังโอนไฟล์ขนาดใหญ่
- การหยุดชะงักของเครือข่ายจะสูง
- การอัปโหลดจะมาจากอุปกรณ์ที่มีแบนด์วิดท์ต่ําหรือการเชื่อมต่ออินเทอร์เน็ตที่ไม่เสถียร เช่น อุปกรณ์เคลื่อนที่
คู่มือนี้อธิบายลําดับคําขอ HTTP ที่แอปพลิเคชันทําเพื่ออัปโหลดวิดีโอโดยใช้กระบวนการอัปโหลดต่อ คู่มือนี้มีไว้สําหรับนักพัฒนาซอฟต์แวร์ที่ใช้ไลบรารีของไคลเอ็นต์ Google API ไม่ได้เป็นหลัก ซึ่งบางส่วนจะให้การสนับสนุนในตัวสําหรับการอัปโหลดที่กลับมาทํางานอีกครั้งได้ คําแนะนําจาก YouTube Data API - การอัปโหลดวิดีโอ จะอธิบายวิธีใช้ไลบรารีของไคลเอ็นต์ Google API สําหรับ Python เพื่ออัปโหลดวิดีโอโดยใช้กระบวนการอัปโหลดต่อ
หมายเหตุ: คุณยังดูชุดคําขอที่สร้างขึ้นสําหรับการอัปโหลดต่อหรือการดําเนินการ API อื่นๆ ได้โดยใช้ไลบรารีของไคลเอ็นต์ Google API ที่เปิดใช้การบันทึก HTTPS แล้ว ตัวอย่างเช่น หากต้องการเปิดใช้การติดตาม HTTP สําหรับ Python ให้ใช้ไลบรารี httplib2
httplib2.debuglevel = 4
ขั้นตอนที่ 1 - เริ่มเซสชันกลับมาทํางานอีกครั้ง
หากต้องการเริ่มอัปโหลดวิดีโอที่กลับมาทํางานอีกครั้ง ให้ส่งคําขอ POST ไปยัง URL ต่อไปนี้ ใน URL ให้กําหนดค่าพารามิเตอร์ part
เป็นค่าที่เหมาะกับคําขอของคุณ โปรดทราบว่าค่าพารามิเตอร์จะระบุส่วนที่มีพร็อพเพอร์ตี้ที่คุณตั้งค่า และจะระบุส่วนที่คุณต้องการให้การตอบกลับ API รวมด้วย ค่าพารามิเตอร์ใน URL ของคําขอต้องเข้ารหัส URL
https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=PARTS
ตั้งเนื้อหาของคําขอเป็นทรัพยากร video
โดยตั้งค่าส่วนหัวของคําขอ HTTP ต่อไปนี้ด้วย
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
ตัวอย่างต่อไปนี้แสดงวิธีเริ่มเซสชันที่กลับมาทํางานอีกครั้งสําหรับการอัปโหลดวิดีโอ คําขอคําขอ (และจะเรียก) พร็อพเพอร์ตี้ในส่วน snippet
และ status
ของทรัพยากร video
และจะเรียกพร็อพเพอร์ตี้ในส่วน 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
ของ API
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" } }
ขั้นตอนที่ 2 - บันทึก URI เซสชันที่กลับมาทํางานอีกครั้ง
หากดําเนินการสําเร็จ เซิร์ฟเวอร์ API จะตอบกลับด้วยรหัสสถานะ HTTP 200
(OK
) และการตอบกลับจะมีส่วนหัว HTTP ของ Location
ที่ระบุ URI สําหรับเซสชันที่กลับมาทํางานอีกครั้ง ซึ่งเป็น URI ที่คุณจะใช้เพื่ออัปโหลดไฟล์วิดีโอ
ตัวอย่างด้านล่างแสดงการตอบกลับ API ของคําขอในขั้นตอนที่ 1
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
ขั้นตอนที่ 3 - อัปโหลดไฟล์วิดีโอ
หลังจากดึง URI ของเซสชันจากการตอบกลับ API แล้ว คุณจะต้องอัปโหลดเนื้อหาไฟล์วิดีโอจริงไปยังตําแหน่งนั้น เนื้อหาของคําขอคือเนื้อหาไฟล์ไบนารีของวิดีโอที่คุณกําลังอัปโหลด ตัวอย่างด้านล่างแสดงรูปแบบคําขอ
PUT UPLOAD_URL HTTP/1.1 Authorization: Bearer AUTH_TOKEN Content-Length: CONTENT_LENGTH Content-Type: CONTENT_TYPE BINARY_FILE_DATA
คําขอตั้งค่าส่วนหัวของคําขอ HTTP ต่อไปนี้
Authorization
– โทเค็นการให้สิทธิ์สําหรับคําขอContent-Length
– ขนาดของไฟล์ที่คุณกําลังอัปโหลด ค่านี้ควรเหมือนกับค่าของส่วนหัวคําขอ HTTPX-Upload-Content-Length
ในขั้นตอนที่ 1Content-Type
– ประเภท MIME ของไฟล์ที่คุณกําลังอัปโหลด ค่านี้ควรเหมือนกับค่าของส่วนหัวคําขอ HTTPX-Upload-Content-Type
ในขั้นตอนที่ 1
ขั้นตอนที่ 4 - ทําตามขั้นตอนการอัปโหลดให้เสร็จสมบูรณ์
คําขอของคุณอาจนําไปสู่สถานการณ์ใดกรณีหนึ่งต่อไปนี้
-
การอัปโหลดสําเร็จแล้ว
เซิร์ฟเวอร์ API ตอบสนองด้วยโค้ดตอบกลับ
201
ของ HTTP (Created
) ส่วนเนื้อหาของการตอบกลับคือทรัพยากรvideo
ที่คุณสร้าง -
การอัปโหลดไม่สําเร็จแต่กลับมาทํางานอีกครั้ง
คุณควรอัปโหลดต่อได้ในกรณีต่อไปนี้
-
คําขอของคุณหยุดชะงักเนื่องจากการเชื่อมต่อระหว่างแอปพลิเคชันกับเซิร์ฟเวอร์ API หายไป ในกรณีนี้คุณจะไม่ได้รับการตอบกลับ API
-
การตอบกลับ API ระบุโค้ดตอบกลับ
5xx
รายการใดต่อไปนี้ โค้ดของคุณควรใช้กลยุทธ์ Exponential Backoff เมื่อกลับมาอัปโหลดอีกครั้งหลังจากได้รับโค้ดตอบกลับเหล่านี้500
-Internal Server Error
502
-Bad Gateway
503
-Service Unavailable
504
-Gateway Timeout
หากต้องการอัปโหลดต่อ ให้ทําตามวิธีตรวจสอบสถานะการอัปโหลดและกลับมาอัปโหลดต่อด้านล่าง โปรดทราบว่า URI เซสชันที่กลับมาทํางานอีกครั้งแต่ละรายการมีอายุการใช้งานที่แน่นอนและหมดอายุในที่สุด ด้วยเหตุนี้ เราขอแนะนําให้เริ่มการอัปโหลดที่กลับมาทํางานอีกครั้งทันทีที่ได้ URI ของเซสชันและกลับมาอัปโหลดที่กลับมาทํางานอีกครั้งในไม่ช้าหลังจากที่การหยุดชะงักเกิดขึ้น
-
-
การอัปโหลดล้มเหลวอย่างถาวร
สําหรับการอัปโหลดที่ล้มเหลว การตอบกลับจะมีการตอบกลับแสดงข้อผิดพลาด ซึ่งจะช่วยอธิบายสาเหตุของความล้มเหลว สําหรับการอัปโหลดที่ล้มเหลวอย่างถาวร การตอบกลับของ API จะมีโค้ดตอบกลับ
4xx
หรือโค้ดตอบกลับ5xx
ที่ไม่ใช่โค้ดที่ระบุไว้ข้างต้นหากคุณส่งคําขอด้วย URI ของเซสชันที่หมดอายุ เซิร์ฟเวอร์จะส่งโค้ดตอบกลับ HTTP ของ
404
(Not Found
) ในกรณีนี้ คุณจะต้องเริ่มการอัปโหลดใหม่ที่กลับมาทํางานอีกครั้ง รับ URI เซสชันใหม่ และเริ่มอัปโหลดตั้งแต่ต้นโดยใช้ URI ใหม่
ขั้นตอนที่ 4.1: ตรวจสอบสถานะของการอัปโหลด
หากต้องการตรวจสอบสถานะของการอัปโหลดที่กลับมาทํางานอีกครั้งได้ ให้ส่งคําขอ PUT เปล่าไปยัง URL การอัปโหลดที่ดึงไว้ในขั้นตอนที่ 2 และใช้ในขั้นตอนที่ 3 ด้วย ตั้งค่าส่วนหัว 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: ประมวลผลการตอบกลับ API
หากการอัปโหลดเสร็จสมบูรณ์ ไม่ว่าจะอัปโหลดสําเร็จหรือไม่ก็ตาม API จะตอบกลับคําขอเดียวกับที่ส่งเมื่อการอัปโหลดเสร็จสมบูรณ์
อย่างไรก็ตาม หากการอัปโหลดขัดข้องหรือกําลังดําเนินการ การตอบกลับ API จะมีโค้ดตอบกลับ HTTP 308
(Resume Incomplete
) ในการตอบกลับ ส่วนหัว Range
ระบุจํานวนไบต์ของไฟล์ที่อัปโหลดสําเร็จ
- ค่าส่วนหัวได้รับการจัดทําดัชนีจาก
0
ดังนั้น ค่าส่วนหัว0-999999
บ่งบอกว่าได้อัปโหลด1,000,000
ไบต์แรกของไฟล์แล้ว - หากยังไม่ได้อัปโหลด การตอบกลับของ API จะไม่รวมส่วนหัว
Range
ตัวอย่างการตอบกลับด้านล่างแสดงรูปแบบการตอบกลับ API สําหรับการอัปโหลดที่กลับมาทํางานอีกครั้งได้
308 Resume Incomplete Content-Length: 0 Range: bytes=0-999999
หากการตอบกลับ API มีส่วนหัว Retry-After
ด้วย ให้ใช้ค่าของส่วนหัวดังกล่าวเพื่อให้ทราบว่าควรอัปโหลดต่อเมื่อใด
ขั้นตอนที่ 4.3: อัปโหลดต่อ
หากต้องการอัปโหลดต่อ ให้ส่งคําขอ PUT
ไปยัง URL การอัปโหลดที่บันทึกในขั้นตอนที่ 2 อีกครั้ง ตั้งค่าเนื้อหาของคําขอเป็นโค้ดไบนารีสําหรับไฟล์วิดีโอที่ยังไม่ได้อัปโหลด
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
คุณต้องตั้งค่าส่วนหัวของคําขอ HTTP ต่อไปนี้
-
Authorization
– โทเค็นการให้สิทธิ์สําหรับคําขอ -
Content-Length
– ขนาดของเนื้อหาที่ยังไม่ได้รับการอัปโหลดในหน่วยไบต์ หากอัปโหลดไฟล์ที่เหลือ คุณคํานวณค่านี้ได้โดยลบค่าFIRST_BYTE
ออกจากค่าTOTAL_CONTENT_LENGTH
ระบบจะใช้ทั้ง 2 ค่าในส่วนหัวContent-Range
-
Content-Range
– ส่วนของไฟล์ที่คุณกําลังอัปโหลด ค่าส่วนหัวประกอบด้วย 3 ค่า ได้แก่-
FIRST_BYTE
– ดัชนีตัวเลข 0 รายการของจํานวนไบต์ที่คุณกําลังอัปโหลดต่อ ค่านี้สูงกว่าตัวเลขที่ 2 ในส่วนหัวRange
ที่ดึงมาในขั้นตอนก่อนหน้า ในตัวอย่างก่อนหน้านี้ ค่าส่วนหัวRange
คือ0-999999
ดังนั้นไบต์แรกในการอัปโหลดต่อที่ตามมาคือ1000000
-
LAST_BYTE
– ดัชนีตัวเลข 0 รายการของไบต์สุดท้ายของไฟล์ไบนารีที่คุณกําลังอัปโหลด โดยปกติแล้วจะเป็นไบต์สุดท้ายในไฟล์ เช่น หากขนาดไฟล์คือ3000000
ไบต์ ไบต์สุดท้ายในไฟล์จะเป็นตัวเลข2999999
-
TOTAL_CONTENT_LENGTH
– ขนาดรวมของไฟล์วิดีโอในหน่วยไบต์ ค่านี้เหมือนกับส่วนหัวContent-Length
ที่ระบุในคําขออัปโหลดต้นฉบับ
หมายเหตุ: คุณจะอัปโหลดการบล็อกไฟล์ไบนารีที่ต่อเนื่องไม่ได้ หากพยายามอัปโหลดการบล็อกแบบไม่ต่อเนื่อง ระบบจะไม่อัปโหลดเนื้อหาไบนารีที่เหลือ
ด้วยเหตุนี้ ไบต์แรกที่อัปโหลดในการอัปโหลดต่อจะเป็นไบต์ถัดไปหลังจากที่ไบต์สุดท้ายอัปโหลดไปยัง YouTube เรียบร้อยแล้ว (ดูการสนทนาของส่วนหัวRange
ในขั้นตอนที่ 4.2
ดังนั้น หากไบต์สุดท้ายในส่วนหัวRange
คือ999999
ไบต์แรกในคําขอให้อัปโหลดต่อต้องเป็น 1000000 (หมายเลขทั้งสองใช้ดัชนีตาม 0) หากคุณพยายามอัปโหลดต่อจากไบต์ 999999 หรือต่ํากว่า (ไบต์ทับซ้อนกัน) หรือไบต์ 1000001 ขึ้นไป (ข้ามไบต์) ระบบจะไม่อัปโหลดเนื้อหาไบนารี -
อัปโหลดไฟล์เป็นส่วนๆ
แทนที่จะพยายามอัปโหลดไฟล์ทั้งหมดและกลับมาอัปโหลดอีกครั้งในกรณีที่เครือข่ายขัดข้อง แอปพลิเคชันของคุณอาจแบ่งไฟล์ออกเป็นส่วนๆ และส่งคําขอแบบเป็นจํานวนมากเพื่ออัปโหลดกลุ่มตามลําดับ แนวทางนี้ไม่จําเป็นและเราไม่แนะนําให้ใช้จริงเนื่องจากต้องขอเพิ่มเติมซึ่งมีผลกระทบต่อประสิทธิภาพ แต่อาจเป็นประโยชน์หากคุณพยายามแสดงสัญญาณบอกสถานะความคืบหน้าในเครือข่ายที่ไม่เสถียรมาก
วิธีการอัปโหลดไฟล์เป็นส่วนๆ นั้นเหมือนกับกระบวนการ 4 ขั้นตอนที่อธิบายไว้ก่อนหน้านี้ในคู่มือนี้ แต่คําขอเริ่มอัปโหลดไฟล์ (ขั้นตอนที่ 3 ด้านบน) และเพื่อทําการอัปโหลดต่อ (ขั้นตอนที่ 4.3 ด้านบน) ให้กําหนดค่าส่วนหัว Content-Length
และ Content-Range
ต่างกันเมื่อมีการอัปโหลดไฟล์เป็นกลุ่ม
-
ค่าส่วนหัว
Content-Length
ระบุขนาดของกลุ่มที่คําขอส่ง โปรดทราบข้อจํากัดต่อไปนี้เกี่ยวกับขนาดกลุ่ม-
ขนาดกลุ่มต้องคูณ 256 KB (ข้อจํากัดนี้ไม่มีผลกับส่วนสุดท้ายเนื่องจากขนาดของไฟล์ทั้งหมดต้องไม่เกิน 256 KB) โปรดทราบว่ากลุ่มขนาดใหญ่จะมีประสิทธิภาพมากกว่า
-
ขนาดกลุ่มต้องเท่ากันสําหรับแต่ละคําขอตามลําดับการอัปโหลด โดยมีข้อยกเว้นสําหรับคําขอสุดท้ายซึ่งจะระบุขนาดของกลุ่มสุดท้าย
-
-
ส่วนหัว
Content-Range
ระบุไบต์ในไฟล์ที่คําขออัปโหลด วิธีการตั้งค่าส่วนหัวContent-Range
ในขั้นตอนที่ 4.3 จะใช้ได้เมื่อตั้งค่าค่านี้เช่น ค่า
bytes 0-524287/2000000
แสดงให้เห็นว่าคําขอส่งขนาด 524,288 ไบต์แรก (256 x 2048) ในไฟล์ขนาด 2,000,000 ไบต์
ตัวอย่างด้านล่างแสดงรูปแบบชุดแรกของคําขอที่จะอัปโหลดไฟล์ขนาด 2,000,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}
หากคําขออื่นที่ไม่ใช่คําขอสุดท้ายสําเร็จ เซิร์ฟเวอร์ API จะตอบกลับด้วยการตอบกลับ 308
(Resume Incomplete
) รูปแบบการตอบสนองจะเหมือนกับที่อธิบายไว้ในขั้นตอนที่ 4.2: ประมวลผลการตอบกลับ API ด้านบน
ใช้ค่าด้านบนที่ส่งคืนในส่วนหัว Range
ของการตอบกลับ API เพื่อกําหนดตําแหน่งที่จะเริ่มกลุ่มถัดไป ส่งคําขอ PUT
ต่อไปตามที่อธิบายไว้ในขั้นตอนที่ 4.3: อัปโหลดต่อเพื่ออัปโหลดไฟล์กลุ่มต่อจนกว่าจะอัปโหลดครบทั้งไฟล์แล้ว
เมื่ออัปโหลดไฟล์ทั้งหมดแล้ว เซิร์ฟเวอร์จะตอบสนองด้วยโค้ดตอบกลับ HTTP (Created
) ของ 201
และแสดงผลส่วนที่ขอของทรัพยากรวิดีโอใหม่ที่สร้างขึ้น
หากคําขอขัดข้องหรือแอปพลิเคชันได้รับโค้ดตอบกลับ 5xx
ให้ทําตามขั้นตอนที่อธิบายไว้ในขั้นตอนที่ 4 เพื่ออัปโหลดไฟล์ให้เสร็จสมบูรณ์ แต่แทนที่จะพยายามอัปโหลดไฟล์ที่เหลือ เพียงอัปโหลดทีละส่วนจากจุดที่คุณกําลังอัปโหลดต่อ อย่าลืมตรวจสอบสถานะของการอัปโหลดเพื่อดูว่าจะอัปโหลดไฟล์ต่อได้จากที่ใด อย่าเดาว่าเซิร์ฟเวอร์ได้รับไบต์ทั้งหมด (หรือไม่ได้รับเลย) ที่ส่งในคําขอก่อนหน้า
หมายเหตุ: คุณยังขอสถานะการอัปโหลดที่ใช้งานอยู่ระหว่างกลุ่มที่อัปโหลดได้ด้วย (การอัปโหลดไม่จําเป็นต้องถูกขัดจังหวะก่อนที่จะเรียกสถานะได้)