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

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

การอัปโหลดไฟล์โดยแบ่งเป็นกลุ่มๆ

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

Exponential Backoff

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

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

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

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

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

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

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

คำแนะนำเกี่ยวกับไลบรารีของไคลเอ็นต์ API