Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

อัปโหลดไฟล์แนบ

Gmail API ช่วยให้คุณอัปโหลดข้อมูลไฟล์เมื่อ สร้าง หรือ อัปเดต ฉบับร่าง หรือเมื่อ แทรก หรือ ส่ง ข้อความ

ตัวเลือกการอัปโหลด

Gmail API ช่วยให้คุณอัปโหลดข้อมูลไบนารีหรือสื่อบางประเภทได้ ลักษณะเฉพาะของข้อมูลที่คุณอัปโหลดได้จะระบุไว้ในหน้าอ้างอิงของเมธอดที่รองรับการอัปโหลดสื่อ ดังนี้

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

คุณสามารถส่งคำขออัปโหลดได้ด้วยวิธีใดวิธีหนึ่งต่อไปนี้ ระบุเมธอดที่คุณใช้ด้วยพารามิเตอร์คำขอ uploadType

การอัปโหลดแบบง่าย: uploadType=media เหมาะสำหรับการโอนไฟล์ขนาดเล็กอย่างรวดเร็ว เช่น ไฟล์ขนาดไม่เกิน 5 MB
การอัปโหลดแบบหลายส่วน: uploadType=multipart เหมาะสำหรับการโอนไฟล์ขนาดเล็กและข้อมูลเมตาอย่างรวดเร็ว โดยจะโอนไฟล์พร้อมกับข้อมูลเมตาที่อธิบายไฟล์นั้นทั้งหมดในคำขอเดียว
การอัปโหลดที่ดำเนินการต่อได้: uploadType=resumable เหมาะสำหรับการโอนที่เชื่อถือได้ โดยเฉพาะอย่างยิ่งกับไฟล์ขนาดใหญ่ เมธอดนี้จะใช้คำขอเริ่มต้นเซสชัน ซึ่งอาจรวมข้อมูลเมตาหรือไม่ก็ได้ เป็นกลยุทธ์ที่ดีสำหรับแอปพลิเคชันส่วนใหญ่ เนื่องจากใช้ได้กับไฟล์ขนาดเล็กด้วย โดยมีค่าใช้จ่ายเป็นคำขอ HTTP เพิ่มเติม 1 รายการต่อการอัปโหลด

เมื่ออัปโหลดสื่อ คุณจะต้องใช้ URI พิเศษ โดยเมธอดที่รองรับการอัปโหลดสื่อจะมีปลายทาง URI 2 รายการ ดังนี้

URI /upload สำหรับสื่อ รูปแบบของปลายทางการอัปโหลดคือ URI ของทรัพยากรมาตรฐานที่มีคำนำหน้า "/upload" ใช้ URI นี้เมื่อ โอนข้อมูลสื่อเอง
ตัวอย่าง: POST /upload/gmail/v1/users/userId/messages/send
URI ของทรัพยากรมาตรฐานสำหรับข้อมูลเมตา หากทรัพยากรมี ช่องข้อมูล ระบบจะใช้ช่องเหล่านั้นเพื่อจัดเก็บข้อมูลเมตาที่อธิบายไฟล์ที่อัปโหลด คุณสามารถใช้ URI นี้เมื่อสร้างหรืออัปเดตค่าข้อมูลเมตา
ตัวอย่าง: POST /gmail/v1/users/userId/messages/send

การอัปโหลดแบบง่าย

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

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

หากต้องการใช้การอัปโหลดแบบง่าย ให้ส่งคำขอ POST หรือ PUT ไปยัง URI /upload ของเมธอด แล้วเพิ่มพารามิเตอร์การค้นหา uploadType=media เช่น

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=media

ส่วนหัว HTTP ที่ใช้เมื่อส่งคำขออัปโหลดแบบง่าย ได้แก่

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

ตัวอย่าง: การอัปโหลดแบบง่าย

ตัวอย่างต่อไปนี้แสดงการใช้คำขออัปโหลดแบบง่ายสำหรับ Gmail API

POST /upload/gmail/v1/users/userId/messages/send?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: message/rfc822
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

Email Message data

หากคำขอสำเร็จ เซิร์ฟเวอร์จะแสดงรหัสสถานะ HTTP 200 OK พร้อมกับข้อมูลเมตา ดังนี้

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

การอัปโหลดแบบหลายส่วน

หากคุณมีข้อมูลเมตาที่ต้องการส่งพร้อมกับข้อมูลที่จะอัปโหลด คุณสามารถส่งคำขอ multipart/related รายการเดียวได้ ตัวเลือกนี้เหมาะสำหรับกรณีที่ข้อมูลที่คุณส่งมีขนาดเล็กพอที่จะอัปโหลดซ้ำทั้งหมดได้หากการเชื่อมต่อล้มเหลว

หากต้องการใช้การอัปโหลดแบบหลายส่วน ให้ส่งคำขอ POST หรือ PUT ไปยัง URI /upload ของเมธอด แล้วเพิ่มพารามิเตอร์การค้นหา uploadType=multipart เช่น

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=multipart

ส่วนหัว HTTP ระดับบนสุดที่ใช้เมื่อส่งคำขออัปโหลดแบบหลายส่วน ได้แก่

Content-Type ตั้งค่าเป็น multipart/related และใส่สตริงขอบเขตที่คุณใช้เพื่อระบุส่วนต่างๆ ของคำขอ
Content-Length ตั้งค่าเป็นจำนวนไบต์ทั้งหมดในเนื้อหาของคำขอ ส่วนสื่อของคำขอต้องมีขนาดไม่เกินขนาดไฟล์สูงสุดที่ระบุไว้สำหรับเมธอดนี้

เนื้อหาของคำขอจะจัดรูปแบบเป็นประเภทเนื้อหา multipart/related [RFC2387] และมี 2 ส่วนพอดี ระบบจะระบุส่วนต่างๆ ด้วยสตริงขอบเขต และสตริงขอบเขตสุดท้ายจะตามด้วยยัติภังค์ 2 ตัว

คำขอแบบหลายส่วนแต่ละส่วนต้องมีส่วนหัว Content-Type เพิ่มเติม ดังนี้

ส่วนข้อมูลเมตา: ต้องมาก่อน และ Content-Type ต้องตรงกับรูปแบบข้อมูลเมตาที่ยอมรับรูปแบบใดรูปแบบหนึ่ง
ส่วนสื่อ: ต้องมาเป็นส่วนที่ 2 และ Content-Type ต้องตรงกับประเภท MIME ของสื่อที่เมธอดยอมรับประเภทใดประเภทหนึ่ง

ดูรายการประเภท MIME ของสื่อที่ยอมรับและขีดจำกัดขนาดสำหรับไฟล์ที่อัปโหลดของแต่ละเมธอดได้ในการอ้างอิง API

หมายเหตุ: หากต้องการสร้างหรืออัปเดตเฉพาะส่วนข้อมูลเมตา เท่านั้น โดยไม่อัปโหลดข้อมูลที่เชื่อมโยง ให้ส่งคำขอ POST หรือ PUT ไปยังปลายทางทรัพยากรมาตรฐาน: https://www.googleapis.com/gmail/v1/users/userId/messages/send

ตัวอย่าง: การอัปโหลดแบบหลายส่วน

ตัวอย่างด้านล่างนี้แสดงคำขออัปโหลดแบบหลายส่วนสำหรับ Gmail API

POST /upload/gmail/v1/users/userId/messages/send?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

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

--foo_bar_baz
Content-Type: message/rfc822

Email Message data
--foo_bar_baz--

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

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

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

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

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

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

หมายเหตุ: URI การอัปโหลดจะหมดอายุหลังจากผ่านไป 1 สัปดาห์

ขั้นตอนที่ 1: เริ่มเซสชันที่ดำเนินการต่อได้

หากต้องการเริ่มการอัปโหลดที่ดำเนินการต่อได้ ให้ส่งคำขอ POST หรือ PUT ไปยัง URI /upload ของเมธอด แล้วเพิ่มพารามิเตอร์การค้นหา uploadType=resumable เช่น

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable

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

ใช้ส่วนหัว HTTP ต่อไปนี้กับคำขอเริ่มต้น

X-Upload-Content-Type ตั้งค่าเป็นประเภท MIME ของสื่อของข้อมูลที่จะอัปโหลดซึ่งจะโอนในคำขอที่ตามมา
X-Upload-Content-Length ตั้งค่าเป็นจำนวนไบต์ของข้อมูลที่จะอัปโหลดซึ่งจะโอนในคำขอที่ตามมา หากไม่ทราบความยาวในขณะที่ส่งคำขอนี้ คุณสามารถละเว้นส่วนหัวนี้ได้
หากระบุข้อมูลเมตา ให้ใช้ Content-Type ตั้งค่าตามประเภทข้อมูลของข้อมูลเมตา
Content-Length ตั้งค่าเป็นจำนวนไบต์ที่ระบุไว้ในเนื้อหาของคำขอเริ่มต้นนี้ ไม่จำเป็นหากคุณใช้การเข้ารหัสการโอนแบบแบ่งส่วน

ตัวอย่าง: คำขอเริ่มต้นเซสชันที่ดำเนินการต่อได้

ตัวอย่างต่อไปนี้แสดงวิธีเริ่มเซสชันที่ดำเนินการต่อได้สำหรับ Gmail API

POST /upload/gmail/v1/users/userId/messages/send?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: message/rfc822
X-Upload-Content-Length: 2000000

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

หมายเหตุ: สำหรับคำขออัปเดตที่ดำเนินการต่อได้เริ่มต้นโดยไม่มีข้อมูลเมตา ให้เว้นเนื้อหาของคำขอให้ว่างเปล่า และตั้งค่าส่วนหัว Content-Length เป็น 0

ส่วนถัดไปจะอธิบายวิธีจัดการการตอบกลับ

ขั้นตอนที่ 2: บันทึก URI ของเซสชันที่ดำเนินการต่อได้

หากคำขอเริ่มต้นเซสชันสำเร็จ เซิร์ฟเวอร์ API จะตอบกลับด้วยรหัสสถานะ HTTP 200 OK นอกจากนี้ ยังมีส่วนหัว Location ที่ระบุ URI ของเซสชันที่ดำเนินการต่อได้ ส่วนหัว Location ที่แสดงในตัวอย่างด้านล่างมีส่วนพารามิเตอร์การค้นหา upload_id ซึ่งให้รหัสการอัปโหลดที่ไม่ซ้ำกันเพื่อใช้สำหรับเซสชันนี้

ตัวอย่าง: การตอบกลับคำขอเริ่มต้นเซสชันที่ดำเนินการต่อได้

นี่คือการตอบกลับคำขอในขั้นตอนที่ 1

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

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

คัดลอกและบันทึก URI ของเซสชันเพื่อให้คุณใช้ URI นี้สำหรับคำขอที่ตามมาได้

ขั้นตอนที่ 3: อัปโหลดไฟล์

หากต้องการอัปโหลดไฟล์ ให้ส่งคำขอ PUT ไปยัง URI การอัปโหลดที่คุณได้รับในขั้นตอนก่อนหน้า รูปแบบของคำขออัปโหลดมีดังนี้

PUT session_uri

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

ตัวอย่าง: คำขออัปโหลดไฟล์ที่ดำเนินการต่อได้

นี่คือคำขอที่ดำเนินการต่อได้เพื่ออัปโหลดไฟล์ข้อความอีเมลทั้งหมด 2,000,000 ไบต์สำหรับตัวอย่างปัจจุบัน

PUT https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: message/rfc822

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 แสดงว่าคุณกำลังระบุไบต์แรก 524,288 ไบต์ (256 x 1024 x 2) ในไฟล์ 2,000,000 ไบต์

ข้อจำกัดด้านขนาดส่วน: ส่วนทั้งหมดต้องมีขนาดเป็นทวีคูณของ 256 KB (256 x 1024 ไบต์) ยกเว้นส่วนสุดท้ายที่ทำให้การอัปโหลดเสร็จสมบูรณ์ หากใช้การแบ่งส่วน คุณควรเก็บขนาดส่วนให้ใหญ่ที่สุดเท่าที่จะเป็นไปได้เพื่อให้การอัปโหลดมีประสิทธิภาพ

ตัวอย่าง: คำขออัปโหลดไฟล์ที่แบ่งส่วนและดำเนินการต่อได้

คำขอที่ส่งไบต์แรก 524,288 ไบต์อาจมีลักษณะดังนี้

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: message/rfc822
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 ของส่วนใดส่วนหนึ่งถูกขัดจังหวะ หรือหากคุณได้รับการตอบกลับ HTTP 503 Service Unavailable หรือการตอบกลับ 5xx อื่นๆ จากเซิร์ฟเวอร์ ให้ทำตามขั้นตอนที่ระบุไว้ในหัวข้อ ดำเนินการอัปโหลดที่ถูกขัดจังหวะต่อ แต่ให้ดำเนินการอัปโหลดส่วนต่างๆ ต่อจากจุดนั้นแทนที่จะอัปโหลดไฟล์ที่เหลือ

หมายเหตุสำคัญ:

อย่าลืมใช้ส่วนหัว Range ในการตอบกลับเพื่อกำหนดจุดเริ่มต้นของส่วนถัดไป อย่าคิดว่าเซิร์ฟเวอร์ได้รับไบต์ทั้งหมดที่ส่งในคำขอก่อนหน้า
URI การอัปโหลดแต่ละรายการมีอายุการใช้งานที่จำกัดและจะหมดอายุในที่สุด (ภายใน 1 วันหรือประมาณนั้น หากไม่ได้ใช้) ด้วยเหตุนี้ คุณจึงควรเริ่มการอัปโหลดที่ดำเนินการต่อได้ทันทีที่ได้รับ URI การอัปโหลด และดำเนินการอัปโหลดที่ถูกขัดจังหวะต่อหลังจากเกิดการขัดจังหวะไม่นาน
หากคุณส่งคำขอที่มีรหัสเซสชันการอัปโหลดที่หมดอายุ เซิร์ฟเวอร์จะแสดงรหัสสถานะ 404 Not Found เมื่อเกิดข้อผิดพลาดที่ไม่สามารถกู้คืนได้ในเซสชันการอัปโหลด เซิร์ฟเวอร์จะแสดงรหัสสถานะ 410 Gone ในกรณีเหล่านี้ คุณต้องเริ่มการอัปโหลดที่ดำเนินการต่อได้ใหม่ รับ URI การอัปโหลดใหม่ และเริ่มการอัปโหลดตั้งแต่ต้นโดยใช้ปลายทางใหม่

เมื่อการอัปโหลดไฟล์ทั้งหมดเสร็จสมบูรณ์ เซิร์ฟเวอร์จะตอบกลับด้วย HTTP 201 Created พร้อมกับข้อมูลเมตาที่เชื่อมโยงกับทรัพยากรนี้ หากคำขอนี้เป็นการอัปเดตเอนทิตีที่มีอยู่แทนที่จะสร้างเอนทิตีใหม่ โค้ดตอบกลับ HTTP สำหรับการอัปโหลดที่เสร็จสมบูรณ์จะเป็น 200 OK

ดำเนินการอัปโหลดที่ถูกขัดจังหวะต่อ

หากคำขออัปโหลดสิ้นสุดลงก่อนที่จะได้รับการตอบกลับ หรือหากคุณได้รับการตอบกลับ HTTP 503 Service Unavailable จากเซิร์ฟเวอร์ คุณจะต้องดำเนินการอัปโหลดที่ถูกขัดจังหวะต่อ โดยทำดังนี้

สถานะคำขอ ค้นหาสถานะปัจจุบันของการอัปโหลดโดยส่งคำขอ PUT ที่ว่างเปล่าไปยัง URI การอัปโหลด สำหรับคำขอนี้ ส่วนหัว HTTP ควรมีส่วนหัว Content-Range ที่ระบุว่าไม่ทราบตำแหน่งปัจจุบันในไฟล์ เช่น ตั้งค่า Content-Range เป็น */2000000 หากความยาวไฟล์ทั้งหมดคือ 2,000,000 หากไม่ทราบขนาดเต็มของไฟล์ ให้ตั้งค่า Content-Range เป็น */*
หมายเหตุ: คุณสามารถขอสถานะระหว่างส่วนต่างๆ ได้ ไม่ใช่เฉพาะในกรณีที่การอัปโหลดถูกขัดจังหวะ วิธีนี้มีประโยชน์ เช่น หากคุณต้องการแสดงการบ่งชี้ความคืบหน้าในการอัปโหลดสำหรับเบราว์เซอร์เดิม
รับจำนวนไบต์ที่อัปโหลด ประมวลผลการตอบกลับจากการค้นหาสถานะ เซิร์ฟเวอร์ใช้ส่วนหัว Range ในการตอบกลับเพื่อระบุไบต์ที่ได้รับจนถึงตอนนี้ เช่น ส่วนหัว Range ที่มีค่า 0-299999 แสดงว่าได้รับไบต์แรก 300,000 ไบต์ของไฟล์แล้ว
อัปโหลดข้อมูลที่เหลือ สุดท้ายนี้ เมื่อทราบจุดที่จะดำเนินการคำขอต่อแล้ว ให้ส่งข้อมูลที่เหลือหรือส่วนปัจจุบัน โปรดทราบว่าคุณต้องถือว่าข้อมูลที่เหลือเป็นส่วนแยกต่างหากในทั้ง 2 กรณี ดังนั้นคุณจึงต้องส่งส่วนหัว Content-Range เมื่อดำเนินการอัปโหลดต่อ

ตัวอย่าง: การดำเนินการอัปโหลดที่ถูกขัดจังหวะต่อ

1) ขอสถานะการอัปโหลด

คำขอต่อไปนี้ใช้ส่วนหัว Content-Range เพื่อระบุว่าไม่ทราบตำแหน่งปัจจุบันในไฟล์ 2,000,000 ไบต์

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2) แยกจำนวนไบต์ที่อัปโหลดไปแล้วจากการตอบกลับ

การตอบกลับของเซิร์ฟเวอร์ใช้ส่วนหัว Range เพื่อระบุว่าได้รับไบต์แรก 43 ไบต์ของไฟล์แล้ว ใช้ค่าบนของส่วนหัว Range เพื่อกำหนดจุดเริ่มต้นของการอัปโหลดต่อ

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

หมายเหตุ: การตอบกลับสถานะอาจเป็น 201 Created หรือ 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
ใช้กลยุทธ์ Exponential Backoff หากเซิร์ฟเวอร์แสดงข้อผิดพลาด 5xx เมื่อดำเนินการต่อหรือลองส่งคำขออัปโหลดซ้ำ ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นหากเซิร์ฟเวอร์ทำงานหนักเกินไป Exponential Backoff สามารถช่วยบรรเทาปัญหาเหล่านี้ได้ในช่วงที่มีคำขอจำนวนมากหรือการจราจรของข้อมูลในเครือข่ายหนาแน่น
คำขอประเภทอื่นๆ ไม่ควรจัดการด้วย Exponential Backoff แต่คุณยังคงลองส่งคำขอเหล่านั้นซ้ำได้ เมื่อลองส่งคำขอเหล่านี้ซ้ำ ให้จำกัดจำนวนครั้งที่ลองส่ง เช่น โค้ดของคุณอาจจำกัดการลองส่งซ้ำไว้ที่ 10 ครั้งหรือน้อยกว่านั้นก่อนที่จะรายงานข้อผิดพลาด
จัดการข้อผิดพลาด 404 Not Found และ 410 Gone เมื่อทำการอัปโหลดที่ดำเนินการต่อได้โดยเริ่มการอัปโหลดทั้งหมดใหม่ตั้งแต่ต้น

Exponential Backoff

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

Exponential Backoff จะเพิ่มประสิทธิภาพการใช้แบนด์วิดท์ ลดจำนวนคำขอที่จำเป็นเพื่อให้ได้รับการตอบกลับที่สำเร็จ และเพิ่มอัตราการส่งข้อมูลของคำขอในสภาพแวดล้อมที่ทำงานพร้อมกันให้ได้มากที่สุด หากใช้อย่างเหมาะสม

ขั้นตอนในการใช้ Exponential Backoff แบบง่ายมีดังนี้

ส่งคำขอไปยัง API
รับการตอบกลับ HTTP 503 ซึ่งบ่งชี้ว่าคุณควรลองส่งคำขออีกครั้ง
รอ 1 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
รับการตอบกลับ HTTP 503 ซึ่งบ่งชี้ว่าคุณควรลองส่งคำขออีกครั้ง
รอ 2 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
รับการตอบกลับ HTTP 503 ซึ่งบ่งชี้ว่าคุณควรลองส่งคำขออีกครั้ง
รอ 4 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
รับการตอบกลับ HTTP 503 ซึ่งบ่งชี้ว่าคุณควรลองส่งคำขออีกครั้ง
รอ 8 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
รับการตอบกลับ HTTP 503 ซึ่งบ่งชี้ว่าคุณควรลองส่งคำขออีกครั้ง
รอ 16 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
หยุด รายงานหรือบันทึกข้อผิดพลาด

ในขั้นตอนข้างต้น random_number_milliseconds คือจำนวนมิลลิวินาทีแบบสุ่มซึ่งมีค่าไม่เกิน 1, 000 การหน่วงเวลาแบบสุ่มเล็กน้อยจะช่วยกระจายภาระงานอย่างสม่ำเสมอมากขึ้นและหลีกเลี่ยงความเป็นไปได้ที่เซิร์ฟเวอร์จะทำงานหนักเกินไป คุณต้องกำหนดค่า random_number_milliseconds ใหม่หลังจากการรอแต่ละครั้ง

หมายเหตุ: เวลาที่รอจะเป็น (2 ^ n) + random_number_milliseconds เสมอ โดย n เป็นจำนวนเต็มที่เพิ่มขึ้นเรื่อยๆ ซึ่งกำหนดไว้เป็น 0 ในตอนแรก จำนวนเต็ม n จะเพิ่มขึ้น 1 สำหรับการทำซ้ำแต่ละครั้ง (คำขอแต่ละรายการ)

อัลกอริทึมจะตั้งค่าให้สิ้นสุดเมื่อ n เป็น 5 ขีดจำกัดนี้จะป้องกันไม่ให้ไคลเอ็นต์ลองส่งคำขอซ้ำอย่างไม่สิ้นสุด และทำให้เกิดความล่าช้ารวมประมาณ 32 วินาทีก่อนที่จะถือว่าคำขอเป็น "ข้อผิดพลาดที่ไม่สามารถกู้คืนได้" คุณสามารถกำหนดจำนวนการลองส่งซ้ำสูงสุดให้มากขึ้นได้ โดยเฉพาะอย่างยิ่งหากมีการอัปโหลดที่ใช้เวลานาน แต่โปรดกำหนดขีดจำกัดความล่าช้าในการลองส่งซ้ำไว้ที่ค่าที่สมเหตุสมผล เช่น ไม่เกิน 1 นาที