หน้านี้ได้รับการแปลโดย Cloud Translation API

การอัปโหลดที่กลับมาทํางานอีกครั้งได้

คุณสามารถอัปโหลดวิดีโอได้อย่างน่าเชื่อถือมากขึ้นโดยใช้โปรโตคอลการอัปโหลดที่กลับมาทํางานอีกครั้งสําหรับ 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 – ขนาดของไฟล์ที่คุณกําลังอัปโหลด ค่านี้ควรเหมือนกับค่าของส่วนหัวคําขอ HTTP X-Upload-Content-Length ในขั้นตอนที่ 1
Content-Type – ประเภท MIME ของไฟล์ที่คุณกําลังอัปโหลด ค่านี้ควรเหมือนกับค่าของส่วนหัวคําขอ HTTP X-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 เพื่ออัปโหลดไฟล์ให้เสร็จสมบูรณ์ แต่แทนที่จะพยายามอัปโหลดไฟล์ที่เหลือ เพียงอัปโหลดทีละส่วนจากจุดที่คุณกําลังอัปโหลดต่อ อย่าลืมตรวจสอบสถานะของการอัปโหลดเพื่อดูว่าจะอัปโหลดไฟล์ต่อได้จากที่ใด อย่าเดาว่าเซิร์ฟเวอร์ได้รับไบต์ทั้งหมด (หรือไม่ได้รับเลย) ที่ส่งในคําขอก่อนหน้า

หมายเหตุ: คุณยังขอสถานะการอัปโหลดที่ใช้งานอยู่ระหว่างกลุ่มที่อัปโหลดได้ด้วย (การอัปโหลดไม่จําเป็นต้องถูกขัดจังหวะก่อนที่จะเรียกสถานะได้)