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 của tệp nội dung nghe nhìn lên Máy chủ Google bằng cách sử dụ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 xác định 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), hãy xem các phương pháp hay nhất về video tải lên để 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

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 photoslibrary.appendonly hoặc phạm vi photoslibrary.

Bạn cũng có thể tạo mục nội dung đa phương tiện bằng phạm vi photoslibrary.sharing. Người nhận tạo mục có phạm vi photoslibrary.sharing, trước tiên bạn phải tạo một và đánh dấu album đó là được chia sẻ bằng shareAlbum. Sau đó, bạn có thể tạo các mục nội dung nghe nhìn được chia sẻ với người dùng trong album. Bạn không thể tạo mục trực tiếp trong thư viện của người dùng hoặc trong album mà ứng dụng của bạn chưa chia sẻ.

Khi liệt kê album, thuộc tính isWriteable cho biết liệu ứng dụng có quyền truy cập để tạo phương tiện trong một anbom cụ thể.

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 bên dưới.

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
Photos 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 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 những nội dung tải lên này mã thông báo để tạo mục nội dung đa phương tiện bằng lệnh gọi batchCreate.

Kiến trúc chuyển trạng thái đại diện (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/pngimage/gif.
X-Goog-Upload-Protocol Đặt thành raw.

Dưới đây là tiêu đề của 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 nội dung yêu cầu, hãy bao gồ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ã tải lên sẽ có trong biểu mẫu của chuỗi văn bản thô, được trả về dưới dạng nội dung phản hồi. Để tạo nội dung nghe nhìn các mục, hãy sử dụng các chuỗi văn bản này trong lệnh gọi batchCreate.

upload-token

Java

// Open the file and automatically close it after upload
try (RandomAccessFile file = new RandomAccessFile(pathToFile, "r")) {
  // Create a new upload request
  UploadMediaItemRequest uploadRequest =
      UploadMediaItemRequest.newBuilder()
              // The media type (e.g. "image/png")
              .setMimeType(mimeType)
              // The file to upload
              .setDataFile(file)
          .build();
  // Upload and capture the response
  UploadMediaItemResponse uploadResponse = photosLibraryClient.uploadMediaItem(uploadRequest);
  if (uploadResponse.getError().isPresent()) {
    // If the upload results in an error, handle it
    Error error = uploadResponse.getError().get();
  } else {
    // If the upload is successful, get the uploadToken
    String uploadToken = uploadResponse.getUploadToken().get();
    // Use this upload token to create a media item
  }
} catch (ApiException e) {
  // Handle error
} catch (IOException e) {
  // Error accessing the local file
}

PHP

try {
    // Create a new upload request by opening the file
    // and specifying the media type (e.g. "image/png")
    $uploadToken = $photosLibraryClient->upload(file_get_contents($localFilePath), null, $mimeType);
} catch (\GuzzleHttp\Exception\GuzzleException $e) {
    // Handle error
}

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

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

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

Sau khi tải số byte của tệp nội dung nghe nhìn lên, bạn có thể tạo các tệp đó dưới dạng nội dung nghe nhìn ảnh và video trong Google Photos bằng mã 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. Mục nội dung đa phương tiện chỉ có thể đã thêm vào album do ứng dụng của bạn tạo ra. Để biết thêm thông tin, hãy xem phần Phạm vi uỷ quyền.

Để 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 mediaItems.batchCreate 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 đ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:

Kiến trúc chuyển trạng thái đại diện (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 một danh sách newMediaItems.

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

Java

try {
  // Create a NewMediaItem with the following components:
  // - uploadToken obtained from the previous upload request
  // - filename that will be shown to the user in Google Photos
  // - description that will be shown to the user in Google Photos
  NewMediaItem newMediaItem = NewMediaItemFactory
          .createNewMediaItem(uploadToken, fileName, itemDescription);
  List<NewMediaItem> newItems = Arrays.asList(newMediaItem);

  BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);
  for (NewMediaItemResult itemsResponse : response.getNewMediaItemResultsList()) {
    Status status = itemsResponse.getStatus();
    if (status.getCode() == Code.OK_VALUE) {
      // The item is successfully created in the user's library
      MediaItem createdItem = itemsResponse.getMediaItem();
    } else {
      // The item could not be created. Check the status and try again
    }
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $newMediaItems = [];
    // Create a NewMediaItem with the following components:
    // - uploadToken obtained from the previous upload request
    // - filename that will be shown to the user in Google Photos
    // - description that will be shown to the user in Google Photos
    $newMediaItems[0] = PhotosLibraryResourceFactory::newMediaItemWithDescriptionAndFileName(
            $uploadToken, $itemDescription, $fileName);

    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems);
    foreach ($response->getNewMediaItemResults() as $itemResult) {
        $status = $itemResult->getStatus();
        if ($status->getCode() != Code::OK) {
            // Error while creating the item.
        }
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Bạn có thể thêm các mục nội dung nghe nhìn vào thư viện và album bằng cách chỉ định album id. Để biết thêm thông tin, hãy xem Tạo album.

Mỗi album có thể chứa tối đa 20.000 mục nội dung nghe nhìn. Yêu cầu tạo nội dung nghe nhìn các mục trong album vượt quá giới hạn này sẽ không thành công.

Kiến trúc chuyển trạng thái đại diện (REST)

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

Java

try {
  // Create new media items in a specific album
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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

Kiến trúc chuyển trạng thái đại diện (REST)

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

Java

try {
  // Create new media items in a specific album, positioned after a media item
  AlbumPosition positionInAlbum = AlbumPositionFactory.createFirstInAlbum();
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems, positionInAlbum);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems,
        ['albumId' => $albumId, 'albumPosition' => $albumPosition]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Để biết thêm chi tiết về vị trí trong album, hãy xem Thêm tính năng bổ sung.

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 .

Kiến trúc chuyển trạng thái đại diện (REST)

Nếu tất cả các mục nội dung đa phương tiện đã được tạo thành công, thì yêu cầu này 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"
      }
    }
  ]
}

Java

BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);

// The response contains a list of NewMediaItemResults
for (NewMediaItemResult result : response.getNewMediaItemResultsList()) {
  // Each result item is identified by its uploadToken
  String uploadToken = result.getUploadToken();
  Status status = result.getStatus();

  if (status.getCode() == Code.OK_VALUE) {
    // If the request is successful, a MediaItem is returned
    MediaItem mediaItem = result.getMediaItem();
    String id = mediaItem.getId();
    String productUrl = mediaItem.getProductUrl();
    // ...
  }
}

PHP

// The response from a call to batchCreateMediaItems returns a list of NewMediaItemResults
foreach ($response->getNewMediaItemResults() as $itemResult) {
    // Each result item is identified by its uploadToken
    $itemUploadToken = $itemResult->getUploadToken();
    // Verify the status of each entry to ensure that the item has been uploaded correctly
    $itemStatus = $itemResult->getStatus();
    if ($itemStatus->getCode() != Code::OK) {
        // Error when item is being created
    } else {
        // Media item is successfully created
        // Get the MediaItem object from the response
        $mediaItem = $itemResult->getMediaItem();
        // It contains details such as the Id of the item, productUrl
        $id = $mediaItem->getId();
        $productUrl = $mediaItem->getProductUrl();
        // ...
    }
}

Nếu một mục được thêm thành công, mediaItem sẽ được trả về chứa mediaItemId, productUrlmediaMetadata. Để 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 đa phương tiện là video, thì trước tiên, mục đó phải được xử lý. 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 tiên, trước khi READY để sử dụng. Để biết thông tin chi tiết, hãy xem Truy cập vào các mục nội dung nghe nhìn.

Nếu bạn gặp lỗi trong khi thực hiện lệnh gọi này, hãy làm theo Các phương pháp hay nhất rồi thử yêu cầu lại. 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 album đúng vị trí trong lần yêu cầu tiếp theo. Để biết thêm thông tin, xem 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:

  • Bạn có thể sử dụng một trong những thư viện ứng dụng được hỗ trợ của chúng tôi.
  • Hãy làm theo các phương pháp hay nhất để xử lý lỗi và thử lại. hãy lưu ý những điểm sau:
    • 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.
    • 500 lỗi 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 để làm cho quá trình tải lên mạnh mẽ 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 quá trình tải lên đã hoàn thành một cách đáng kể. Đ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 các tệp lớn 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 các mục nội dung đa phương tiện.

Đang 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) đồ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

  • Khô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 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 batchCreate lệnh gọi cho mỗi người dùng kết quả khác. Chỉ thực hiện cuộc gọi song song cho 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 của bạn tạo ra. Đừ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ô bytetạ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.

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 song song nhiều byte lên từ nhiều người dùng, nhưng ở bước 2, bạn chỉ có thể thực hiện một cuộc 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ả tệp tải lên và lệnh gọi tạo nội dung nghe nhìn hoàn tất.