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

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 ที่จะใช้ในการส่งคำขออัปโหลดแบบง่ายมีดังนี้

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

ตัวอย่างต่อไปนี้แสดงการใช้คำขออัปโหลดแบบง่ายสำหรับ 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 เพิ่มเติม ดังนี้

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

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

หมายเหตุ: หากต้องการสร้างหรืออัปเดตเฉพาะส่วนข้อมูลเมตาโดยไม่ต้องอัปโหลดข้อมูลที่เชื่อมโยง ให้ส่งคําขอ 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 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
}

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

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

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

  1. เริ่มเซสชันที่กลับมาทำงานต่อได้ ส่งคำขอเริ่มต้นไปยัง URI การอัปโหลดที่มีข้อมูลเมตา (หากมี)
  2. บันทึก URI ของเซสชันที่กลับมาทำงานต่อได้ บันทึก URI ของเซสชันที่แสดงผลในการตอบกลับของคําขอแรก ซึ่งคุณจะใช้กับคําขอที่เหลือในเซสชันนี้
  3. อัปโหลดไฟล์ ส่งไฟล์สื่อไปยัง 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. ตั้งค่าเป็นจํานวนไบต์ที่ระบุในส่วนเนื้อหาของคําขอเริ่มต้นนี้ ไม่จําเป็นหากใช้การเข้ารหัสการโอนแบบแบ่งกลุ่ม

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

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

ตัวอย่างต่อไปนี้แสดงวิธีเริ่มเซสชันที่กลับมาทำงานต่อได้สำหรับ 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 เซสชันเพื่อให้ใช้กับคำขอต่อๆ ไปได้

ขั้นตอนที่ 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 บางคลาส และยังช่วยให้คุณทำสิ่งต่างๆ ได้ เช่น ระบุตัวบ่งชี้ความคืบหน้าการอัปโหลดสำหรับเบราว์เซอร์เดิมที่ไม่รองรับความคืบหน้าการอัปโหลดโดยค่าเริ่มต้น

อัปโหลดต่อ

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

  1. สถานะคำขอ ค้นหาสถานะปัจจุบันของการอัปโหลดโดยส่งคำขอ PUT แบบว่างไปยัง URI การอัปโหลด สําหรับคําขอนี้ ส่วนหัว HTTP ควรมีส่วนหัว Content-Range ที่ระบุว่าไม่ทราบตําแหน่งปัจจุบันในไฟล์  เช่น ตั้งค่า Content-Range เป็น */2000000 หากความยาวไฟล์ทั้งหมดคือ 2,000,000 หากไม่ทราบขนาดเต็มของไฟล์ ให้ตั้งค่า Content-Range เป็น */*

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

  2. รับจำนวนไบต์ที่อัปโหลด ประมวลผลการตอบกลับจากการค้นหาสถานะ เซิร์ฟเวอร์ใช้ส่วนหัว Range ในการตอบกลับเพื่อระบุไบต์ที่ได้รับจนถึงตอนนี้  เช่น ส่วนหัว Range ของ 0-299999 บ่งบอกว่าได้รับไบต์แรกของไฟล์ 300,000 ไบต์แล้ว
  3. อัปโหลดข้อมูลที่เหลือ สุดท้าย เมื่อคุณทราบตําแหน่งที่จะส่งคําขอต่อแล้ว ให้ส่งข้อมูลที่เหลือหรือข้อมูลส่วนที่เป็นปัจจุบัน โปรดทราบว่าคุณต้องถือว่าข้อมูลที่เหลือเป็นกลุ่มแยกต่างหากไม่ว่าในกรณีใดก็ตาม คุณจึงต้องส่งส่วนหัว 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 แต่คุณยังคงลองส่งคำขอเหล่านั้นได้ เมื่อลองส่งคำขอเหล่านี้อีกครั้ง ให้จำกัดจำนวนครั้งที่จะลองใหม่ เช่น โค้ดอาจจำกัดการลองใหม่ไม่เกิน 10 ครั้งก่อนที่จะรายงานข้อผิดพลาด
  • จัดการข้อผิดพลาด 404 Not Found และ 410 Gone เมื่อทำการอัปโหลดแบบเริ่มใหม่ได้โดยการเริ่มการอัปโหลดทั้งหมดอีกครั้งตั้งแต่ต้น

Exponential Backoff

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

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

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

  1. ส่งคําขอไปยัง API
  2. ได้รับคําตอบ HTTP 503 ซึ่งหมายความว่าคุณควรลองส่งคําขออีกครั้ง
  3. รอ 1 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
  4. ได้รับคําตอบ HTTP 503 ซึ่งหมายความว่าคุณควรลองส่งคําขออีกครั้ง
  5. รอ 2 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
  6. ได้รับคําตอบ HTTP 503 ซึ่งหมายความว่าคุณควรลองส่งคําขออีกครั้ง
  7. รอ 4 วินาที + random_number_milliseconds แล้วลองส่งคําขออีกครั้ง
  8. ได้รับคําตอบ HTTP 503 ซึ่งหมายความว่าคุณควรลองส่งคําขออีกครั้ง
  9. รอ 8 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
  10. ได้รับคําตอบ HTTP 503 ซึ่งหมายความว่าคุณควรลองส่งคําขออีกครั้ง
  11. รอ 16 วินาที + random_number_milliseconds แล้วลองส่งคําขออีกครั้ง
  12. หยุด รายงานหรือบันทึกข้อผิดพลาด

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

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

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

คู่มือไลบรารีของไคลเอ็นต์ API