อัปโหลดสื่อ

การอัปโหลดรายการสื่อเป็นกระบวนการ 2 ขั้นตอน ดังนี้

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

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

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

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

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

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

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

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

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

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

upload-token

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

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

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

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

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

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

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

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

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

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

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

{
  "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 แสดงว่ามี ข้อผิดพลาด

{
  "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 ทีละรายการ (แบบอนุกรม)
  • สำหรับผู้ใช้หลายราย ให้เรียกใช้ batchCreate สำหรับผู้ใช้แต่ละรายทีละคนเสมอ เรียกใช้สำหรับผู้ใช้ที่แตกต่างกันแบบขนานเท่านั้น

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

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

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

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

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

ก่อนอื่น ให้สร้างคิวเพื่ออัปโหลดไบต์ดิบสำหรับรายการสื่อจากผู้ใช้ทั้งหมด ติดตาม 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.

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