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

การอัปโหลดที่ดำเนินการต่อได้

คุณสามารถอัปโหลดวิดีโอได้อย่างน่าเชื่อถือมากขึ้นโดยใช้โปรโตคอลการอัปโหลดแบบเริ่มใหม่ได้สำหรับ Google API โปรโตคอลนี้ช่วยให้คุณดำเนินการอัปโหลดต่อได้หลังจากเครือข่ายหยุดชะงักหรือการส่งข้อมูลอื่นๆ ไม่สำเร็จ ซึ่งจะช่วยประหยัดเวลาและแบนด์วิดท์ในกรณีที่เครือข่ายไม่ทำงาน

การใช้การอัปโหลดที่อัปโหลดต่อได้จะมีประโยชน์อย่างยิ่งในกรณีต่อไปนี้

คุณกำลังโอนไฟล์ขนาดใหญ่
มีแนวโน้มที่เครือข่ายจะหยุดชะงักสูง
การอัปโหลดมาจากอุปกรณ์ที่มีแบนด์วิดท์ต่ำหรือการเชื่อมต่ออินเทอร์เน็ตที่ไม่เสถียร เช่น อุปกรณ์เคลื่อนที่

คู่มือนี้จะอธิบายลำดับคำขอ 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 จะตอบกลับด้วยรหัสการตอบกลับ HTTP 201 (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 ที่ดึงข้อมูลในขั้นตอนก่อนหน้า 1 หน่วย ในตัวอย่างก่อนหน้านี้ ค่าส่วนหัว Range คือ 0-999999 ดังนั้นไบต์แรกในการอัปโหลดที่กลับมาดำเนินการต่อในภายหลังจะเป็น 1000000
- LAST_BYTE – ดัชนีตัวเลขฐาน 0 ของไบต์สุดท้ายของไฟล์ไบนารีที่คุณอัปโหลด โดยปกติแล้วจะเป็นไบต์สุดท้ายในไฟล์ ตัวอย่างเช่น หากขนาดไฟล์คือ 3000000 ไบต์ ไบต์สุดท้ายในไฟล์จะเป็นหมายเลข 2999999
- TOTAL_CONTENT_LENGTH – ขนาดไฟล์วิดีโอทั้งหมดในหน่วยไบต์ ค่านี้เหมือนกับส่วนหัว Content-Length ที่ระบุไว้ในคำขออัปโหลดต้นฉบับ
หมายเหตุ: คุณไม่สามารถอัปโหลดบล็อกของไฟล์ไบนารีที่ไม่ต่อเนื่อง หากคุณพยายามอัปโหลดบล็อกที่ไม่ต่อเนื่อง ระบบจะไม่อัปโหลดเนื้อหาไบนารีที่เหลือ

ด้วยเหตุนี้ ไบต์แรกที่อัปโหลดในการอัปโหลดที่กลับมาดำเนินการต่อต้องเป็นแบ็กต่อจากไบต์สุดท้ายที่อัปโหลดไปยัง YouTube สำเร็จแล้ว (ดูการพูดคุยเรื่องส่วนหัว Range ในขั้นตอนที่ 4.2

ดังนั้น หากไบต์สุดท้ายในส่วนหัว Range คือ 999999 ไบต์แรกในคำขออัปโหลดต่อต้องเป็นไบต์ 1000000 (ทั้ง 2 ตัวเลขใช้ดัชนีฐาน 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: อัปโหลดต่อ เพื่ออัปโหลดกลุ่มไฟล์ต่อๆ ไปจนกว่าระบบจะอัปโหลดไฟล์ทั้งไฟล์

เมื่ออัปโหลดไฟล์ทั้งไฟล์แล้ว เซิร์ฟเวอร์จะตอบกลับด้วย201โค้ดการตอบกลับ HTTP (Created) และแสดงผลส่วนที่ขอของทรัพยากรวิดีโอที่สร้างขึ้นใหม่

หากคำขอถูกขัดจังหวะหรือแอปพลิเคชันได้รับรหัสคำตอบ 5xx ให้ทำตามขั้นตอนที่อธิบายไว้ในขั้นตอนที่ 4 เพื่ออัปโหลดให้เสร็จสมบูรณ์ อย่างไรก็ตาม แทนที่จะพยายามอัปโหลดไฟล์ที่เหลือ ให้อัปโหลดข้อมูลส่วนต่างๆ ต่อจากจุดที่คุณกลับมาอัปโหลดต่อ อย่าลืมตรวจสอบสถานะการอัปโหลดเพื่อดูว่าควรอัปโหลดไฟล์ต่อจากจุดใด อย่าคิดว่าเซิร์ฟเวอร์ได้รับไบต์ทั้งหมด (หรือไม่มีเลย) ที่ส่งในคำขอก่อนหน้า

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