Mengupload media

Proses upload item media terdiri dari dua langkah:

1. Upload byte file media Anda ke Server Google menggunakan endpoint upload. Tindakan ini akan menampilkan token upload yang mengidentifikasi byte yang diupload.
2. Gunakan panggilan batchCreate dengan token upload untuk membuat item media di akun Google Foto pengguna.

Langkah-langkah ini menguraikan proses upload satu item media. Jika Anda mengupload beberapa item media (kemungkinan besar untuk aplikasi produksi apa pun), tinjau praktik terbaik untuk upload guna meningkatkan efisiensi upload Anda.

Sebelum memulai

Cakupan otorisasi yang diperlukan

Mengupload item media ke koleksi atau album pengguna memerlukan cakupan photoslibrary.appendonly atau photoslibrary.

Item media juga dapat dibuat menggunakan cakupan photoslibrary.sharing. Untuk membuat item dengan cakupan photoslibrary.sharing, Anda harus terlebih dahulu membuat album dan menandainya sebagai dibagikan menggunakan shareAlbum. Kemudian, Anda dapat membuat item media yang dibagikan kepada pengguna di album. Anda tidak dapat membuat item langsung di library pengguna atau di album yang belum dibagikan oleh aplikasi Anda.

Saat mencantumkan album, properti isWriteable menunjukkan apakah aplikasi Anda memiliki akses untuk membuat media di album tertentu.

Jenis dan ukuran file yang diterima

Anda dapat mengupload jenis file yang tercantum dalam tabel di bawah.

Jenis media	Jenis file yang diterima	Ukuran file maksimum
Foto	AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP, beberapa file RAW.	200 MB
Video	3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD, WMV.	20 GB

Langkah 1: Mengupload byte

Upload byte ke Google menggunakan permintaan upload. Permintaan upload yang berhasil akan menampilkan token upload dalam bentuk string teks mentah. Gunakan token upload ini untuk membuat item media dengan panggilan batchCreate.

Catatan: Semua item media yang diupload ke Google Foto melalui API akan disimpan dalam resolusi penuh dalam kualitas asli. Jika upload melebihi 25 MB per pengguna, aplikasi harus mengingatkan pengguna bahwa upload ini akan mengurangi penyimpanan di Akun Google mereka.

REST

Sertakan kolom berikut di header permintaan POST:

Kolom header
Content-type	Tetapkan ke application/octet-stream.
X-Goog-Upload-Content-Type	Direkomendasikan. Setel ke jenis MIME byte yang Anda upload. Jenis MIME yang umum meliputi image/jpeg, image/png, dan image/gif.
X-Goog-Upload-Protocol	Tetapkan ke raw.

Berikut adalah header permintaan 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

Dalam isi permintaan, sertakan biner file:

media-binary-data

Jika permintaan POST ini berhasil, token upload yang berupa string teks mentah akan ditampilkan sebagai isi respons. Untuk membuat item media, gunakan string teks ini dalam panggilan 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
}

Ukuran file yang disarankan untuk gambar kurang dari 50 MB. File yang berukuran lebih dari 50 MB rentan terhadap masalah performa.

Google Photos Library API mendukung upload yang dapat dilanjutkan. Upload yang dapat dilanjutkan memungkinkan Anda membagi file media menjadi beberapa bagian dan mengupload satu bagian dalam satu waktu.

Langkah 2: Membuat item media

Setelah mengupload byte file media, Anda dapat membuatnya sebagai item media di Google Foto menggunakan token upload. Token upload valid selama satu hari setelah dibuat. Item media selalu ditambahkan ke library pengguna. Item media hanya dapat ditambahkan ke album yang dibuat oleh aplikasi Anda. Untuk informasi selengkapnya, lihat Cakupan otorisasi.

Untuk membuat item media baru, panggil mediaItems.batchCreate dengan menentukan daftar newMediaItems. Setiap newMediaItem berisi token upload yang ditentukan dalam simpleMediaItem, dan deskripsi opsional yang ditampilkan kepada pengguna.

Kolom deskripsi dibatasi maksimal 1.000 karakter dan hanya boleh menyertakan teks bermakna yang dibuat oleh pengguna. Misalnya, "Perjalanan kami ke taman" atau "Makan malam liburan". Jangan sertakan metadata seperti nama file, tag terprogram, atau teks lain yang dibuat secara otomatis.

Untuk performa terbaik, kurangi jumlah panggilan ke mediaItems.batchCreate yang harus Anda lakukan dengan menyertakan beberapa item media dalam satu panggilan. Selalu tunggu hingga permintaan sebelumnya selesai sebelum melakukan panggilan berikutnya untuk pengguna yang sama.

Anda dapat membuat satu atau beberapa item media di library pengguna dengan menentukan deskripsi dan token upload yang terkait:

REST

Berikut adalah header permintaan POST:

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

Isi permintaan harus menentukan daftar 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
}

Anda dapat menambahkan item media ke library dan ke album dengan menentukan album id. Untuk informasi selengkapnya, lihat Membuat album.

Setiap album dapat berisi hingga 20.000 item media. Permintaan untuk membuat item media dalam album yang akan melebihi batas ini akan gagal.

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
}

Anda juga dapat menentukan albumId dan albumPosition untuk menyisipkan item media di lokasi tertentu dalam album.

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
}

Untuk detail selengkapnya terkait penempatan posisi dalam album, lihat Menambahkan pengayaan.

Peringatan: Panggilan batchCreate membatasi jumlah item media yang dibuat dalam satu panggilan hingga 50 item media. Sebaiknya beberapa batchCreate dipanggil secara paralel untuk pengguna yang sama juga tidak direkomendasikan.

Respons pembuatan item

Panggilan mediaItems.batchCreate menampilkan hasil untuk setiap item media yang Anda coba buat. Daftar newMediaItemResults menunjukkan status dan menyertakan uploadToken untuk permintaan tersebut. Kode status bukan nol menunjukkan error.

REST

Jika semua item media berhasil dibuat, permintaan akan menampilkan status HTTP 200 OK. Jika beberapa item media tidak dapat dibuat, permintaan akan menampilkan status HTTP 207 MULTI-STATUS untuk menunjukkan keberhasilan sebagian.

{
  "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();
        // ...
    }
}

Jika item berhasil ditambahkan, mediaItem akan ditampilkan yang berisi mediaItemId, productUrl, dan mediaMetadata. Untuk mengetahui informasi selengkapnya, lihat Mengakses item media.

Jika item media berupa video, item tersebut harus diproses terlebih dahulu. mediaItem berisi status di dalam mediaMetadata yang menjelaskan status pemrosesan file video. File yang baru diupload akan menampilkan status PROCESSING terlebih dahulu, sebelum berstatus READY untuk digunakan. Untuk mengetahui detailnya, lihat Mengakses item media.

Jika Anda mengalami error selama panggilan ini, ikuti Praktik terbaik dan coba lagi permintaan Anda. Sebaiknya Anda memantau penambahan yang berhasil, sehingga gambar dapat disisipkan ke dalam album pada posisi yang tepat selama permintaan berikutnya. Untuk informasi selengkapnya, lihat Membuat album.

Hasil selalu ditampilkan dalam urutan yang sama dengan pengiriman token upload.

Catatan: Item media yang sama (didefinisikan sebagai byte yang sama yang diupload) diperlakukan sebagai objek yang sama. Artinya, id item media yang sama akan ditampilkan, meskipun dirujuk oleh uploadToken yang berbeda.

Praktik terbaik untuk upload

Praktik terbaik dan referensi berikut membantu meningkatkan efisiensi Anda secara keseluruhan dengan upload:

• Gunakan salah satu library klien yang didukung.
• Ikuti praktik terbaik percobaan ulang dan penanganan error, dengan memperhatikan hal-hal berikut:
  • Error 429 dapat terjadi saat kuota Anda telah habis atau kapasitas Anda dibatasi karena melakukan terlalu banyak panggilan terlalu cepat. Pastikan Anda tidak memanggil batchCreate untuk pengguna yang sama hingga permintaan sebelumnya selesai.
  • 429 error memerlukan penundaan minimum 30s sebelum mencoba lagi. Gunakan strategi backoff eksponensial saat mencoba kembali permintaan.
  • Error 500 terjadi saat server mengalami error. Saat mengupload, kemungkinan besar karena melakukan beberapa panggilan tulis (seperti batchCreate) untuk pengguna yang sama secara bersamaan. Periksa detail permintaan Anda dan jangan lakukan panggilan ke batchCreate secara paralel.
• Gunakan alur upload yang dapat dilanjutkan untuk membuat upload Anda lebih andal jika terjadi gangguan jaringan, sehingga mengurangi penggunaan bandwidth dengan memungkinkan Anda melanjutkan upload yang telah selesai secara parsial. Hal ini penting saat mengupload dari perangkat seluler klien, atau saat mengupload file berukuran besar.

Selain itu, pertimbangkan tips berikut untuk setiap langkah proses upload: mengupload byte, lalu membuat item media.

Mengupload byte

• Mengupload byte (untuk mengambil token upload) dapat dilakukan secara paralel.
• Selalu tetapkan jenis MIME yang benar di header X-Goog-Upload-Content-Type untuk setiap panggilan upload.

Membuat item media

• Jangan melakukan panggilan secara paralel dengan batchCreate untuk satu pengguna.

  • Untuk setiap pengguna, lakukan panggilan ke batchCreate satu per satu (dalam serial).
  • Untuk beberapa pengguna, selalu lakukan panggilan batchCreate untuk setiap pengguna satu per satu. Hanya lakukan panggilan untuk pengguna yang berbeda secara paralel.

• Sertakan sebanyak mungkin NewMediaItems dalam setiap panggilan ke batchCreate untuk meminimalkan jumlah total panggilan yang harus Anda lakukan. Anda dapat menyertakan maksimal 50 item.

• Tetapkan teks deskripsi yang bermakna yang telah dibuat oleh pengguna Anda. Jangan sertakan metadata seperti nama file, tag terprogram, atau teks lain yang dihasilkan secara otomatis dalam kolom deskripsi.

Contoh panduan

Contoh ini menggunakan kode semu untuk memandu proses upload item media untuk beberapa pengguna. Tujuannya adalah untuk menguraikan kedua langkah proses upload (mengupload byte mentah dan membuat item media) serta mendetailkan praktik terbaik untuk membangun integrasi upload yang efisien dan tangguh.

Langkah 1: Upload byte mentah

Pertama, buat antrean untuk mengupload byte mentah untuk item media Anda dari semua pengguna. Lacak setiap uploadToken yang ditampilkan per pengguna. Ingatlah poin-poin penting ini:

• Jumlah thread upload yang serentak bergantung pada lingkungan operasi Anda.
• Sebaiknya ubah urutan antrean upload sesuai kebutuhan. Misalnya, Anda dapat memprioritaskan upload berdasarkan jumlah upload yang tersisa per pengguna, progres keseluruhan pengguna, atau persyaratan lainnya.

Kode semu

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

Langkah 2: Buat item media

Pada langkah 1, Anda dapat mengupload beberapa byte dari beberapa pengguna secara paralel, tetapi pada langkah 2, Anda hanya dapat membuat satu panggilan untuk setiap pengguna pada satu waktu.

Kode semu

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

Lanjutkan proses ini hingga semua upload dan panggilan pembuatan media selesai.