Upload media

Mengupload item media adalah proses dua langkah:

1. Upload byte file media Anda ke Server Google menggunakan file upload endpoint. Proses ini mengembalikan 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 item media tunggal. Jika Anda mengupload beberapa item media (kemungkinan besar untuk aplikasi produksi), tinjau praktik terbaik untuk upload guna meningkatkan kualitas upload Anda tim dan efisiensi.

Sebelum memulai

Cakupan otorisasi yang diperlukan

Mengupload item media ke galeri foto atau album pengguna memerlukan photoslibrary.appendonly cakupan. Untuk informasi selengkapnya tentang cakupan, lihat Cakupan otorisasi.

Jenis dan ukuran file yang diterima

Anda dapat mengupload jenis file yang tercantum dalam tabel ini.

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

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

Catatan: Semua item media yang diupload ke Google Foto melalui API akan disimpan dalam resolusi penuh pada asli berkualitas. Jika upload Anda melebihi 25 MB per pengguna, aplikasi Anda 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. Tetapkan ke jenis MIME byte yang Anda upload. Jenis MIME 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 ada dalam bentuk dari string teks mentah, dikembalikan sebagai isi respons. Untuk membuat media item, gunakan string teks ini dalam panggilan batchCreate.

upload-token

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

Google Photos Library API mendukung upload yang dapat dilanjutkan. Upload yang dapat dilanjutkan memungkinkan Anda bagi file media menjadi beberapa bagian dan upload 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. Item media hanya dapat ditambahkan ke album yang dibuat oleh . Untuk informasi selengkapnya, lihat Otorisasi cakupan.

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

Bidang deskripsi dibatasi hingga 1.000 karakter dan hanya boleh berisi teks yang bermakna yang dibuat oleh pengguna. Misalnya, "Perjalanan kami ke taman" atau "Makan malam liburan". Jangan sertakan metadata seperti nama file, permintaan terprogram {i>tag<i}, atau teks lainnya yang dibuat secara otomatis.

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

Anda dapat membuat satu item media atau beberapa item media di galeri foto pengguna dengan menentukan deskripsi dan token upload yang sesuai:

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

Anda juga dapat menentukan albumId dan albumPosition untuk sisipkan 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"
  }
}

Untuk detail selengkapnya tentang pemosisian di album, lihat Menambahkan pengayaan.

Peringatan: Panggilan batchCreate membatasi jumlah item media yang dibuat di satu panggilan ke 50 item media. Juga tidak disarankan untuk menggunakan batchCreate dipanggil secara paralel untuk pengguna yang sama.

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. Kode status bukan nol mengindikasikan {i>error<i}.

REST

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

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

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

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

Jika Anda mengalami error selama panggilan ini, ikuti petunjuk Terbaik praktik terbaik, lalu coba lagi permintaan Anda. Anda mungkin ingin melacak penambahan yang berhasil, sehingga gambar dapat dimasukkan ke dalam album di posisi yang benar saat permintaan berikutnya. Untuk selengkapnya informasi tambahan, lihat Membuat album.

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

Catatan: Item media yang sama (didefinisikan sebagai byte yang sama yang diupload) diperlakukan sebagai objek yang sama. Ini berarti bahwa item media yang sama id ditampilkan, meskipun jika dirujuk oleh uploadToken lain.

Praktik terbaik untuk upload

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

• Ikuti praktik terbaik percobaan ulang dan penanganan error, dengan mengingat poin berikut:
  • Error 429 dapat terjadi jika kuota Anda habis atau Anda dikenai pembatasan kapasitas karena melakukan terlalu banyak panggilan terlalu cepat. Pastikan Anda tidak memanggil batchCreate untuk pengguna yang sama hingga telah selesai.
  • Error 429 memerlukan penundaan minimum 30s sebelum mencoba lagi. Gunakan backoff eksponensial saat mencoba ulang permintaan.
  • Error 500 terjadi saat server mengalami error. Saat mengupload, kemungkinan besar karena Anda melakukan beberapa panggilan tulis (seperti batchCreate) untuk pengguna yang sama secara bersamaan. Periksa detail permintaan Anda dan tidak melakukan panggilan ke batchCreate secara paralel.
• Gunakan alur upload yang dapat dilanjutkan untuk membuat upload Anda lebih handal jika terjadi gangguan jaringan, sehingga penggunaan bandwidth dengan memungkinkan Anda melanjutkan upload yang selesai sebagian. Ini adalah hal yang penting saat mengupload dari perangkat seluler klien, atau saat 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 dalam X-Goog-Upload-Content-Type header 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 (di serial).
  • Untuk beberapa pengguna, selalu lakukan panggilan batchCreate untuk setiap pengguna satu demi satu. Hanya lakukan panggilan untuk pengguna yang berbeda secara paralel.

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

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

Contoh panduan

Contoh ini menggunakan pseudocode untuk memandu proses upload item media bagi beberapa pengguna. Tujuannya adalah untuk menguraikan kedua langkah proses upload (mengupload file byte dan membuat item media) serta menjelaskan praktik terbaik untuk membuat proses upload yang efisien dan tangguh integrasi.

Langkah 1: Upload byte mentah

Pertama-tama buat antrean untuk mengunggah byte mentah untuk item media Anda dari semua pelanggan. Lacak setiap uploadToken yang ditampilkan per pengguna. Ingatlah poin-poin penting berikut:

• Jumlah rangkaian pesan upload yang serentak bergantung pada operasi Anda lingkungan fleksibel App Engine.
• Pertimbangkan untuk mengurutkan ulang antrean upload sesuai kebutuhan. Misalnya, Anda dapat memprioritaskan upload berdasarkan jumlah upload yang tersisa per pengguna, kemajuan pengguna secara keseluruhan, 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 dengan langkah 2, Anda hanya dapat melakukan 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.