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

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. ส่วนสื่อ: ต้องมาเป็นอันดับ 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. อัปโหลดข้อมูลที่เหลือ สุดท้าย เมื่อทราบแล้วว่าจะส่งคำขอต่อจากจุดใด ให้ส่งข้อมูลที่เหลือหรือกลุ่มข้อมูลปัจจุบัน โปรดทราบว่าคุณต้องจัดการข้อมูลที่เหลือเป็นกลุ่มแยกต่างหากในทั้ง 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 แบบง่ายมีดังนี้

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

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

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

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