อัปโหลดสื่อ

การอัปโหลดรายการสื่อมี 2 ขั้นตอนดังนี้

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

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

ก่อนเริ่มต้น

ขอบเขตการให้สิทธิ์ที่จําเป็น

การอัปโหลดรายการสื่อไปยังคลังหรืออัลบั้มของผู้ใช้จำเป็นต้องใช้ photoslibrary.appendonly ขอบเขต ดูข้อมูลเพิ่มเติมเกี่ยวกับขอบเขตได้ที่ ขอบเขตการให้สิทธิ์

ประเภทและขนาดไฟล์ที่ยอมรับ

คุณสามารถอัปโหลดไฟล์ประเภทที่แสดงในตารางนี้ได้

ประเภทสื่อ ประเภทไฟล์ที่ยอมรับ ขนาดไฟล์สูงสุด
Photos AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP, ไฟล์ RAW บางประเภท 200 MB
วิดีโอ 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4 MPG, MTS, TOD, WMV 20 GB

ขั้นตอนที่ 1: การอัปโหลดไบต์

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

REST

ใส่ช่องต่อไปนี้ในส่วนหัวของคำขอ POST

ช่องส่วนหัว
Content-type ตั้งค่าเป็น application/octet-stream
X-Goog-Upload-Content-Type แนะนำ ตั้งค่าเป็นประเภท MIME ของไบต์ที่คุณกำลังอัปโหลด ประเภท MIME ทั่วไป ได้แก่ image/jpeg image/png และ image/gif
X-Goog-Upload-Protocol ตั้งค่าเป็น raw

ต่อไปนี้คือส่วนหัวของคำขอ POST

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-type: application/octet-stream
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: raw

ในเนื้อหาคำขอ ให้ใส่ไบนารีของไฟล์ดังนี้ 

media-binary-data

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

upload-token

ขนาดไฟล์ที่แนะนำสำหรับรูปภาพคือน้อยกว่า 50 MB ไฟล์มีขนาดใหญ่กว่า 50 MB ก็มีแนวโน้มที่จะเกิดปัญหาด้านประสิทธิภาพ

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

ขั้นตอนที่ 2: การสร้างรายการสื่อ

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

หากต้องการสร้างรายการสื่อใหม่ ให้เรียกใช้ mediaItems.batchCreate โดยระบุรายการ newMediaItems newMediaItem แต่ละรายการมีการอัปโหลด โทเค็นที่ระบุภายใน simpleMediaItem และคำอธิบายที่ไม่บังคับ ที่จะแสดงต่อผู้ใช้

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

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

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

REST

ต่อไปนี้คือส่วนหัวของคำขอ POST

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer oauth2-token

เนื้อหาของคำขอควรระบุรายการ newMediaItems

{
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

คุณยังระบุ albumId และ albumPosition ให้ แทรกรายการสื่อในตำแหน่งที่เจาะจงในอัลบั้ม

REST

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
    , ...
  ],
  "albumPosition": {
    "position": "after-media-item",
    "relativeMediaItemId": "media-item-id"
  }
}

สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับตำแหน่งในอัลบั้ม โปรดดูที่ เพิ่ม คุณค่าเพิ่มเติม

การตอบกลับการสร้างสินค้า

การเรียก mediaItems.batchCreate จะแสดงผลลัพธ์สำหรับรายการสื่อแต่ละรายการ ที่คุณพยายามสร้าง รายการของ newMediaItemResults จะระบุสถานะและ มี uploadToken สำหรับคำขอ รหัสสถานะที่ไม่เท่ากับ 0 บ่งบอกถึงข้อผิดพลาด

REST

หากสร้างรายการสื่อทั้งหมดสำเร็จแล้ว คำขอจะแสดงผล สถานะ HTTP: 200 OK หากสร้างรายการสื่อบางรายการไม่ได้ คำขอจะแสดงสถานะ HTTP 207 MULTI-STATUS เพื่อระบุ สำเร็จบางส่วน

{
  "newMediaItemResults": [
    {
      "uploadToken": "upload-token",
      "status": {
        "message": "Success"
      },
      "mediaItem": {
        "id": "media-item-id",
        "description": "item-description",
        "productUrl": "https://photos.google.com/photo/photo-path",
        "mimeType": "mime-type",
        "mediaMetadata": {
          "width": "media-width-in-px",
          "height": "media-height-in-px",
          "creationTime": "creation-time",
          "photo": {}
        },
        "filename": "filename"
      }
    },
    {
      "uploadToken": "upload-token",
      "status": {
        "code": 13,
        "message": "Internal error"
      }
    }
  ]
}

หากเพิ่มรายการสำเร็จแล้ว ระบบจะแสดงผล mediaItem ที่มี mediaItemId, productUrl และ mediaMetadata ดูข้อมูลเพิ่มเติมได้ที่เข้าถึงรายการสื่อ

หากรายการสื่อเป็นวิดีโอ จะต้องประมวลผลก่อน mediaItem มี status ภายใน mediaMetadata ซึ่งอธิบายสถานะการประมวลผลของไฟล์วิดีโอ ไฟล์ที่อัปโหลดใหม่จะแสดงสถานะ PROCESSING ก่อนที่จะREADY โปรดดูรายละเอียดที่หัวข้อเข้าถึงสื่อ รายการ

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

ระบบจะแสดงผลลัพธ์ตามลำดับเดียวกับที่ส่งโทเค็นการอัปโหลด

แนวทางปฏิบัติแนะนำสำหรับการอัปโหลด

แนวทางปฏิบัติแนะนำและแหล่งข้อมูลต่อไปนี้จะช่วยปรับปรุงประสิทธิภาพโดยรวม ที่มีการอัปโหลด:

  • ดำเนินการตามการจัดการข้อผิดพลาดซ้ำและที่ดีที่สุด แนวทางปฏิบัติ โปรดคํานึงถึงประเด็นต่อไปนี้
    • ข้อผิดพลาด 429 รายการอาจเกิดขึ้นเมื่อโควต้าของคุณหมด หรือคุณถูกจำกัดอัตราการโทรเนื่องจากโทรเร็วเกินไป ตรวจสอบว่า คุณไม่ได้โทรหา batchCreate สำหรับผู้ใช้รายเดียวกัน จนกว่า คำขอเสร็จสมบูรณ์แล้ว
    • ข้อผิดพลาด 429 จะต้องรออย่างน้อย 30s วินาทีก่อนลองอีกครั้ง ใช้ Exponential Backoff เมื่อส่งคำขออีกครั้ง
    • ข้อผิดพลาด 500 เกิดขึ้นเมื่อเซิร์ฟเวอร์พบข้อผิดพลาด เมื่ออัปโหลด กรณีนี้น่าจะเป็นเพราะการเรียกเขียนหลายครั้ง (เช่น batchCreate) ให้กับผู้ใช้รายเดียวกันได้ในเวลาเดียวกัน ตรวจสอบรายละเอียดของ คำขอของคุณและอย่าโทรหา batchCreate พร้อมกัน
  • ใช้ขั้นตอนการอัปโหลดที่ดำเนินการต่อได้เพื่อ ทำให้การอัปโหลดของคุณมีประสิทธิภาพมากขึ้นในกรณีที่เครือข่ายหยุดชะงัก การใช้แบนด์วิดท์โดยให้คุณดำเนินการต่อสำหรับการอัปโหลดที่ไม่สมบูรณ์ ช่วงเวลานี้ เป็นสิ่งสำคัญเมื่ออัปโหลดจากอุปกรณ์เคลื่อนที่ของไคลเอ็นต์หรือเมื่ออัปโหลด ไฟล์ขนาดใหญ่

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

การอัปโหลดไบต์

  • การอัปโหลดไบต์ (เพื่อเรียกโทเค็นการอัปโหลด) สามารถทำได้พร้อมกัน
  • ตั้งค่าประเภท MIME ที่ถูกต้องใน X-Goog-Upload-Content-Type เสมอ ส่วนหัวสำหรับ การอัปโหลดแต่ละครั้ง

การสร้างรายการสื่อ

  • อย่าโทรออกพร้อมกันกับ batchCreate สำหรับผู้ใช้รายเดียว

    • สำหรับผู้ใช้แต่ละราย ให้โทรหา batchCreate ทีละรายการ (ใน (Serial) )
    • สำหรับผู้ใช้หลายคน ให้โทร batchCreate ครั้งสำหรับผู้ใช้แต่ละราย ต่อกัน เรียกผู้ใช้ที่แตกต่างกันพร้อมกันเท่านั้น

  • ให้NewMediaItemsมากที่สุดเท่าที่จะทำได้ ในการโทรแต่ละครั้งไปยัง batchCreate เพื่อลดจำนวนการโทรทั้งหมดที่คุณมี ในแบบที่จะทำ คุณเพิ่มได้สูงสุด 50 รายการ

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

ตัวอย่างคำแนะนำแบบทีละขั้น

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

ขั้นตอนที่ 1: อัปโหลดไบต์ดิบ

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

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

ซูโดโค้ด

CREATE uploadQueue FROM users, filesToUpload
// Upload media bytes in parallel.
START multiple THREADS
  WHILE uploadQueue is not empty
    POP uploadQueue
    UPLOAD file for user
    GET uploadToken
    CHECK and HANDLE errors
    STORE uploadToken for user in uploadTokensQueue
  END

ขั้นตอนที่ 2: สร้างรายการสื่อ

ในขั้นตอนที่ 1 คุณสามารถอัปโหลดไบต์หลายไบต์จากผู้ใช้หลายคนพร้อมกันได้ แต่ ขั้นตอนที่ 2 คุณจะโทรออกได้เพียงครั้งละ 1 สายเท่านั้น

ซูโดโค้ด

// For each user, create media items once 50 upload tokens have been
// saved, or no more uploads are left per user.
WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user
  // Calls can be made in parallel for different users,
  // but only make a single call per user at a time.
  START new thread for (this) user if there is no thread yet
    POP 50 uploadTokens from uploadTokensQueue for user
    CALL mediaItems.batchCreate with uploadTokens
    WAIT UNTIL batchCreate call has completed
    CHECK and HANDLE errors (retry as needed)
  DONE.

ทำตามกระบวนการนี้จนกว่าการเรียกให้อัปโหลดและสร้างสื่อทั้งหมดจะเสร็จสมบูรณ์