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

Việc tải các mục nội dung nghe nhìn lên là một quy trình gồm 2 bước:

1. Tải các byte của tệp phương tiện lên một Máy chủ của Google bằng cách sử dụng điểm cuối tải lên. Thao tác này trả về một mã thông báo tải lên giúp xác định các byte đã tải lên.
2. Sử dụng lệnh gọi batchCreate cùng 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 mô tả 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 nghe nhìn lên (rất có thể đối với mọi ứng dụng sản xuất), hãy xem các phương pháp hay nhất để tải lên nhằm 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

Để 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, bạn cần có phạm vi photoslibrary.appendonly. Để 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 tệp và kích thước đượ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.

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

Tải các byte lên Google bằng cách sử dụng 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ã tải lên dưới 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 các mục nội dung nghe nhìn bằng lệnh gọi 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

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 phải các vấn đề về hiệu suất.

Google Photos Library API hỗ trợ tải lên có thể tiếp tục. Tính năng tải lên tiếp nối cho phép bạn chia một tệp nội dung nghe nhìn thành nhiều phần và tải từng phần lên một 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 nghe nhìn lên, bạn có thể tạo các tệp đó dưới dạng mục nghe nhìn trong Google Photos bằng cách sử dụ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ụ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 album 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 một 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à nội dung mô tả không bắt buộc sẽ xuất hiện với người dùng.

Trường nội dung mô tả chỉ được dài tối đa 1.000 ký tự và chỉ được chứa 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 tôi" hoặc "Bữa tối ngày lễ". Đừng thêm siêu dữ liệu như tên tệp, thẻ có thể lập trình hoặc văn bản khác được tạo tự động.

Để đạt hiệu suất tốt nhất, bạn nên giảm số lượng lệnh gọi đến mediaItems.batchCreate 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 rồi mới 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 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:

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"
      }
    }
   , ...
  ]
}

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.

{
  "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 về cách đặt vị trí trong album, hãy xem phần Thêm thông tin bổ sung.

Phản hồi khi tạo mục

Lệnh gọi mediaItems.batchCreate sẽ 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 có lỗi.

{
  "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 một mục được thêm thành công, thì một mediaItem sẽ được trả về, trong đó có mediaItemId, productUrl và mediaMetadata. Để biết thêm thông tin, hãy xem phần Truy cập vào các mục nội dung nghe nhìn.

Nếu là một mục nội dung nghe nhìn, thì mục đó phải được xử lý trước. mediaItem chứa một 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, sau đó mới là trạng thái READY để sử dụng. Để 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 và thử lại yêu cầu. Bạn nên theo dõi những lần thêm ảnh thành công để có thể chèn ả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 bài viết Tạo album.

Kết quả luôn được trả về theo cùng 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 cải thiện hiệu quả tổng thể của bạn 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 đã hết hoặc bạn bị giới hạn về tốc độ do thực hiện quá nhiều lệnh gọi quá nhanh. Đả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 yêu cầu độ trễ tối thiểu là 30s trước khi thử lại. Sử dụng chiến lược thời gian đợi luỹ thừa khi thử lại các yêu cầu.
  • Lỗi 500 xảy ra khi máy chủ gặp lỗi. Khi tải lên, rất có thể là do bạn thực hiện nhiều lệnh ghi (chẳng hạn như batchCreate) cho cùng một người dùng cùng một lúc. Kiểm tra thông tin chi tiết về yêu cầu của bạn và không gọi đến batchCreate song song.
• Sử dụng quy trình tải lên tiếp nối để giúp quá trình tải lên ổn định hơ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 tải lên những phần đã hoàn tất. Điều này rất quan trọng khi tải lên từ thiết bị di động của khách hà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 cho từng bước trong quy trình tải lên: tải byte lên rồi tạo các mục nội dung nghe nhìn.

Số byte tải lên

• Bạn có thể tải các byte lên song song (để truy xuất mã thông báo tải lên).
• Luôn đặt loại MIME chính xác 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

• Không thực hiện các lệnh gọi song song đến batchCreate cho một người dùng.

  • Đối với mỗi người dùng, hãy gọi đến batchCreate lần lượt (theo trình 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 cho những người dùng khác nhau song song.

• Bao gồm càng nhiều NewMediaItems càng tốt trong 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ặt hàng.

• Đặt một văn bản mô tả có ý nghĩa do người dùng của bạn tạo. Đừng thêm siêu dữ liệu như tên tệp, thẻ lập trình hoặc văn bản khác được tạo tự động vào trường nội dung 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 cách 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 các byte thô lên và tạo các mục nội dung nghe nhìn) và trình bày chi tiết các phương pháp hay nhất để xây dựng một 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 một hàng đợi để tải các byte thô cho các mục nội dung nghe nhìn của bạn lên từ tất cả người dùng. Theo dõi từng uploadToken được trả về cho mỗi người dùng. Hãy 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.
• Cân nhắ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 việc tải lên dựa trên số lượng tệp tải lên còn lại cho 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.

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 của 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.

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