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

Tải các mục nội dung đa phương tiện lên là quy trình gồm hai bước:

1. Tải các byte tệp đa phương tiện của bạn lên Máy chủ Google bằng cách sử dụng tệp tải lên điểm cuối. Thao tác này sẽ trả về một mã thông báo tải lên giúp nhận dạng các byte đã tải lên.
2. Sử dụng lệnh gọi BulkCreate với mã thông báo tải lên để tạo một mục nội dung nghe nhì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 tải nhiều mục nội dung đa phương tiện lên (rất có thể là cho bất kỳ ứng dụng sản xuất nào), tham khảo các phương pháp hay nhất về video tải lên để cải thiện quy trình tải lên sự hiệu quả.

Trước khi bắt đầu

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

Việ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 yêu cầu Phạm vi photoslibrary.appendonly. Để biết thêm thông tin về phạm vi, hãy xem Phạm vi uỷ quyền.

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

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

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

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ã thông báo 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 vấn đề về hiệu suất.

API Thư viện Google Photos hỗ trợ có thể tiếp tục video tải lên. Quy trình tải lên tiếp nối giúp bạn hãy chia một tệp đa phương tiện thành nhiều phần rồi tải từng phần lên.

Bước 2: Tạo 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 là hợp lệ trong một ngày sau khi tạo. Một mục nội dung đa phương tiện luôn được thêm vào thư viện của bạn. Bạn chỉ có thể thêm các mục nội dung đa phương tiện vào album do . Để biết thêm thông tin, hãy xem Uỷ quyền phạm vi ngày.

Để tạo 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 tệp tải lên mã thông báo được chỉ định bên trong simpleMediaItem và phần mô tả không bắt buộc hiển thị cho người dùng.

Trường mô tả giới hạn trong 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ủa chúng ta đến công viên" hoặc "Bữa tối ngày lễ". Không thêm siêu dữ liệu như tên tệp, nội dung có lập trình thẻ hoặc văn bản khác được tạo tự động.

Để có hiệu suất tốt nhất, hãy giảm số lượng cuộc gọi xuống còn mediaItems.batchCreate 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 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 đa phương tiện hoặc nhiều mục nội dung đa phương tiệ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 tại 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 chi tiết về cách định vị trong album, hãy xem phần Thêm nội dung làm phong phú.

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

Lệnh gọi mediaItems.batchCreate trả về kết quả cho từng mục nội dung đa phương tiệ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 .

{
  "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 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ả quá trình 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 chuyển sang 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 nội dung nghe nhìn mục.

Nếu bạn gặp lỗi trong khi thực hiện cuộc gọi này, hãy làm theo các bước rồi thử yêu cầu lại. Bạn nên theo dõi các lượt bổ sung thành công, vì vậy, bạn có thể chèn hình ảnh vào album đúng vị trí trong lần 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 cùng thứ tự mà mã thông báo tải lên đã 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 với video tải lên:

• Làm theo hướng dẫn thử lại và xử lý lỗi theo cách hiệu quả nhất , giúp duy trì hãy lưu ý những điểm sau đây:
  • Có thể xảy ra 429 lỗi khi hạn mức của bạn đã bị vượt quá hoặc bạn bị giới hạn cước phí do thực hiện quá nhiều cuộc gọi quá nhanh. Đảm bảo bạn không gọi batchCreate cho cùng một người dùng cho đến đã 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 thuật toán thời gian đợi luỹ thừa khi thử lại yêu cầu.
  • Lỗi 500 xảy ra khi máy chủ gặp lỗi. Khi tải lên, điều này rất có thể là do bạn 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 tại cùng một thời điểm. 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 lệnh gọi đến batchCreate cùng lúc.
• Sử dụng quy trình tải lên tiếp nối để giúp quá trình tải lên của bạn trở nên mạnh mẽ hơn trong trường hợp bị gián đoạn mạng, 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 tất một phần. Chiến dịch này là 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 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 các byte lên rồi tạo nội dung nghe nhìn .

Đang tải byte lên

• Bạn có thể tải byte lên (để truy xuất mã thông báo tải lên) đồng thời.
• 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.

Đang tạo mục nội dung nghe nhìn

• Đừng thực hiện các cuộc 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 lần lượt các lệnh gọi đến batchCreate (trong sê-ri).
  • Đố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 mỗi người dùng kết quả khác. Chỉ thực hiện cuộc gọi song song cho những người dùng khác nhau.

• Cung cấp nhiều NewMediaItems nhất có thể trong mỗi cuộc gọi đến batchCreate để giảm thiểu tổng số cuộc gọi mà bạn có 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 thêm siêu dữ liệu như tên tệp, thẻ có lập trình hoặc văn bản được tạo tự động khác trong 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 bạn tải các mục nội dung đa phương tiện lên cho nhiều người dùng. Mục tiêu là phác thảo cả hai bước của quá trình tải lên (tải lên dữ liệu thô byte 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ải lên hiệu quả và linh hoạt tích hợp.

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

Trước tiên, tạo hàng đợi để tải lên các byte thô cho các mục nội dung đa phương tiện của bạn từ tất cả người dùng. Theo dõi mỗi 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 hoạt động của bạn môi trường.
• 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ượ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.

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.

// 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ả tệp tải lên và lệnh gọi tạo nội dung nghe nhìn hoàn tất.