Tải lên phương tiện

Quy trình tải mục nội dung nghe nhìn lên gồm 2 bước:

  1. Tải các byte của tệp phương tiện lên Máy chủ của Google bằng điểm cuối tải lên. Thao tác này sẽ trả về một mã thông báo tải lên giúp xác định số byte đã tải lên.
  2. Sử dụng lệnh gọi batchCreate với mã thông báo tải lên để tạo một mục nội dung đa phương tiện trong tài khoản Google Photos của người dùng.

Các bước này trình bày quy trình tải một mục nội dung đa phương tiện lên. Nếu bạn đang tải nhiều mục nội dung đa phương tiện lên (rất có thể là đối với mọi ứng dụng phát hành công khai), hãy xem các phương pháp tải lên hay nhất để cải thiện hiệu quả tải lên.

Trước khi bắt đầu

Phạm vi uỷ quyền bắt buộc

Bạn cần có phạm vi photoslibrary.appendonly để tải các mục nội dung nghe nhìn lên thư viện hoặc album của người dùng. Để biết thêm thông tin về phạm vi, hãy xem phần Phạm vi uỷ quyền.

Các loại và kích thước tệp được chấp nhận

Bạn có thể tải các loại tệp được liệt kê trong bảng này lên.

Loại nội dung nghe nhìn Các loại tệp được chấp nhận Kích thước tệp tối đa
Ảnh AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP, một số tệp RAW. 200 MB
Video 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD, WMV. 20 GB

Bước 1: Tải lên byte

Tải byte lên Google bằng các yêu cầu tải lên. Yêu cầu tải lên thành công sẽ trả về một mã thông báo tải lên ở dạng chuỗi văn bản thô. Sử dụng các mã thông báo tải lên này để tạo mục nội dung nghe nhìn bằng lệnh gọi batchCreate.

REST

Bao gồm các trường sau trong tiêu đề của yêu cầu POST:

Trường tiêu đề
Content-type Đặt thành application/octet-stream.
X-Goog-Upload-Content-Type Được đề xuất. Đặt thành loại MIME của các byte bạn đang tải lên. Các loại MIME phổ biến bao gồm image/jpeg, image/png và image/gif.
X-Goog-Upload-Protocol Đặt thành raw.

Sau đây là tiêu đề yêu cầu 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

Trong phần nội dung yêu cầu, hãy thêm tệp nhị phân của tệp: 

media-binary-data

Nếu yêu cầu POST này thành công, thì mã thông báo tải lên ở dạng chuỗi văn bản thô sẽ được trả về dưới dạng nội dung phản hồi. Để tạo các mục nội dung đa phương tiện, hãy sử dụng các chuỗi văn bản này trong lệnh gọi batchCreate.

upload-token

Kích thước tệp đề xuất cho hình ảnh là dưới 50 MB. Các tệp lớn hơn 50 MB dễ gặp vấn đề về hiệu suất.

API Thư viện Google Photos hỗ trợ tính năng tiếp tục tải lên. Tính năng tải lên tiếp nối cho phép bạn chia một tệp phương tiện thành nhiều phần và tải từng phần lên.

Bước 2: Tạo một mục nội dung nghe nhìn

Sau khi tải các byte của tệp phương tiện lên, bạn có thể tạo các tệp đó dưới dạng mục nội dung nghe nhìn trong Google Photos bằng mã thông báo tải lên. Mã thông báo tải lên có hiệu lực trong một ngày sau khi được tạo. Một mục nội dung nghe nhìn luôn được thêm vào thư viện của người dùng. Bạn chỉ có thể thêm các mục nội dung nghe nhìn vào các đĩa nhạc do ứng dụng của bạn tạo. Để biết thêm thông tin, hãy xem phần Phạm vi uỷ quyền.

Để tạo các mục nội dung nghe nhìn mới, hãy gọi mediaItems.batchCreate bằng cách chỉ định danh sách newMediaItems. Mỗi newMediaItem chứa một mã thông báo tải lên được chỉ định bên trong simpleMediaItem và một nội dung mô tả không bắt buộc sẽ hiển thị cho người dùng.

Trường nội dung mô tả chỉ được chứa tối đa 1.000 ký tự và chỉ nên bao gồm văn bản có ý nghĩa do người dùng tạo. Ví dụ: "Chuyến đi công viên của chúng ta" hoặc "Bữa tối ngày lễ". Đừng đưa siêu dữ liệu như tên tệp, thẻ lập trình hoặc văn bản được tạo tự động khác vào.

Để đạt được hiệu suất tốt nhất, hãy giảm số lượng lệnh gọi đến mediaItems.batchCreate mà bạn phải thực hiện bằng cách đưa nhiều mục nội dung nghe nhìn vào một lệnh gọi. Luôn đợi cho đến khi yêu cầu trước đó hoàn tất trước khi thực hiện lệnh gọi tiếp theo cho cùng một người dùng.

Bạn có thể tạo một mục nội dung nghe nhìn hoặc nhiều mục nội dung nghe nhìn trong thư viện của người dùng bằng cách chỉ định nội dung mô tả và mã thông báo tải lên tương ứng:

REST

Dưới đây là tiêu đề của yêu cầu POST:

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

Nội dung yêu cầu phải chỉ định danh sách newMediaItems.

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

Bạn cũng có thể chỉ định albumId và albumPosition để chèn các mục nội dung nghe nhìn vào một vị trí cụ thể trong album.

REST

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

Để biết thêm thông tin chi tiết về vị trí trong album, hãy xem phần Thêm tính năng đa dạng thức.

Phản hồi về việc tạo mặt hàng

Lệnh gọi mediaItems.batchCreate trả về kết quả cho từng mục nội dung nghe nhìn mà bạn đã cố gắng tạo. Danh sách newMediaItemResults cho biết trạng thái và bao gồm uploadToken cho yêu cầu. Mã trạng thái khác 0 cho biết lỗi.

REST

Nếu tất cả các mục nội dung nghe nhìn đã được tạo thành công, thì yêu cầu sẽ trả về trạng thái HTTP 200 OK. Nếu không thể tạo một số mục nội dung đa phương tiện, yêu cầu sẽ trả về trạng thái HTTP 207 MULTI-STATUS để cho biết đã thành công một phần.

{
  "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"
      }
    }
  ]
}

Nếu thêm một mục thành công, hệ thống sẽ trả về một mediaItem chứa mediaItemId, productUrl và mediaMetadata. Để biết thêm thông tin, hãy xem bài viết Truy cập vào các mục nội dung nghe nhìn.

Nếu mục nội dung nghe nhìn là video, thì trước tiên bạn phải xử lý video đó. mediaItem chứa status bên trong mediaMetadata mô tả trạng thái xử lý của tệp video. Tệp mới tải lên sẽ trả về trạng thái PROCESSING trước tiên, trước khi sử dụng là READY. Để biết thông tin chi tiết, hãy xem phần Truy cập vào các mục nội dung nghe nhìn.

Nếu bạn gặp lỗi trong lệnh gọi này, hãy làm theo Các phương pháp hay nhất rồi thử lại yêu cầu của mình. Bạn nên theo dõi các lần thêm thành công để có thể chèn hình ảnh vào đúng vị trí trong album trong yêu cầu tiếp theo. Để biết thêm thông tin, hãy xem phần Tạo album.

Kết quả luôn được trả về theo thứ tự mà mã thông báo tải lên được gửi.

Các phương pháp hay nhất để tải lên

Các phương pháp hay nhất và tài nguyên sau đây giúp bạn nâng cao hiệu quả tổng thể khi tải lên:

  • Hãy làm theo các phương pháp hay nhất về việc thử lại và xử lý lỗi, đồng thời lưu ý những điểm sau:
    • Lỗi 429 có thể xảy ra khi hạn mức của bạn đã bị vượt quá hoặc bạn bị giới hạn tốc độ do thực hiện quá nhiều lệnh gọi quá nhanh. Hãy đảm bảo rằng bạn không gọi batchCreate cho cùng một người dùng cho đến khi yêu cầu trước đó hoàn tất.
    • 429 lỗi cần độ trễ tối thiểu là 30s trước khi thử lại. Sử dụng chiến lược thuật toán thời gian đợi luỹ thừa khi thử lại các yêu cầu.
    • 500 lỗi xảy ra khi máy chủ gặp lỗi. Khi tải lên, điều này có thể là do thực hiện nhiều lệnh gọi ghi (chẳng hạn như batchCreate) cho cùng một người dùng cùng một lúc. Hãy kiểm tra thông tin chi tiết về yêu cầu của bạn và không thực hiện song song các lệnh gọi đến batchCreate.
  • Sử dụng quy trình tải lên có thể tiếp tục để tăng hiệu quả tải lên trong trường hợp mạng bị gián đoạn, giảm mức sử dụng băng thông bằng cách cho phép bạn tiếp tục quá trình tải lên hoàn thành một cách nhất định. Điều này rất quan trọng khi tải lên từ thiết bị di động của ứng dụng hoặc khi tải lên các tệp lớn.

Ngoài ra, hãy cân nhắc các mẹo sau đây cho từng bước trong quy trình tải lên: tải lên byte rồi tạo mục nội dung nghe nhìn.

Tải byte lên

  • Bạn có thể tải các byte lên (để truy xuất mã thông báo tải lên) song song.
  • Luôn đặt đúng loại MIME trong tiêu đề X-Goog-Upload-Content-Type cho mỗi lệnh gọi tải lên.

Tạo mục nội dung nghe nhìn

  • Đừng thực hiện các lệnh gọi song song với batchCreate cho một người dùng.

    • Đối với mỗi người dùng, hãy thực hiện các lệnh gọi đến batchCreate lần lượt (theo thứ tự).
    • Đối với nhiều người dùng, hãy luôn thực hiện các lệnh gọi batchCreate cho từng người dùng lần lượt. Chỉ thực hiện các lệnh gọi song song cho nhiều người dùng.

  • Đưa nhiều NewMediaItems nhất có thể vào mỗi lệnh gọi đến batchCreate để giảm thiểu tổng số lệnh gọi mà bạn phải thực hiện. Bạn có thể thêm tối đa 50 mục.

  • Đặt văn bản mô tả có ý nghĩa do người dùng tạo. Đừng đưa siêu dữ liệu như tên tệp, thẻ lập trình hoặc văn bản được tạo tự động khác vào trường mô tả.

Ví dụ về hướng dẫn từng bước

Ví dụ này sử dụng mã giả để hướng dẫn từng bước tải các mục nội dung nghe nhìn lên cho nhiều người dùng. Mục tiêu là trình bày cả hai bước của quy trình tải lên (tải byte thô lên và tạo mục nội dung đa phương tiện) và trình bày chi tiết các phương pháp hay nhất để xây dựng quy trình tích hợp tải lên hiệu quả và linh hoạt.

Bước 1: Tải byte thô lên

Trước tiên, hãy tạo hàng đợi để tải các byte thô lên cho các mục nội dung đa phương tiện từ tất cả người dùng của bạn. Theo dõi mỗi uploadToken được trả về cho mỗi người dùng. Hãy ghi nhớ những điểm chính sau:

  • Số lượng luồng tải lên đồng thời phụ thuộc vào môi trường hoạt động của bạn.
  • Hãy cân nhắc việc sắp xếp lại hàng đợi tải lên nếu cần. Ví dụ: bạn có thể ưu tiên tải lên dựa trên số lượng lượt tải lên còn lại của mỗi người dùng, tiến trình tổng thể của người dùng hoặc các yêu cầu khác.

Mã giả

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

Bước 2: Tạo mục nội dung nghe nhìn

Ở bước 1, bạn có thể tải nhiều byte từ nhiều người dùng lên song song, nhưng ở bước 2, bạn chỉ có thể thực hiện một lệnh gọi cho mỗi người dùng tại một thời điểm.

Mã giả

// 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.

Tiếp tục quá trình này cho đến khi tất cả các lệnh gọi tải lên và tạo nội dung nghe nhìn hoàn tất.