Upload media

Mengupload item media adalah proses dua langkah:

1. Upload byte file media Anda ke Server Google menggunakan endpoint uploads. 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 mengupload satu item media. Jika Anda mengupload beberapa item media (sangat mungkin 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 galeri foto atau album pengguna memerlukan cakupan photoslibrary.appendonly. Untuk mengetahui informasi selengkapnya tentang cakupan, lihat Cakupan otorisasi.

Jenis dan ukuran file yang diterima

Anda dapat mengupload jenis file yang tercantum dalam tabel ini.

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.

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

Ukuran file yang disarankan untuk gambar adalah kurang dari 50 MB. File yang lebih besar dari 50 MB cenderung menyebabkan 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. Masa berlaku token upload adalah satu hari setelah dibuat. Item media selalu ditambahkan ke koleksi pengguna. Item media hanya dapat ditambahkan ke album yang dibuat oleh aplikasi Anda. Untuk mengetahui informasi selengkapnya, lihat Cakupan otorisasi.

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

Kolom deskripsi dibatasi hingga 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 yang dibuat secara otomatis lainnya.

Untuk mendapatkan 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 item media atau beberapa item media di galeri foto pengguna dengan menentukan deskripsi dan token upload yang sesuai:

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

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

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

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

Respons pembuatan item

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

{
  "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 mediaItemId, productUrl, dan mediaMetadata. Untuk mengetahui informasi selengkapnya, lihat Mengakses item media.

Jika item media adalah video, video 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 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. Anda mungkin ingin melacak penambahan yang berhasil, sehingga gambar dapat disisipkan ke dalam album pada posisi yang benar selama permintaan berikutnya. Untuk mengetahui informasi selengkapnya, lihat Membuat album.

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

Praktik terbaik untuk upload

Praktik terbaik dan referensi berikut membantu meningkatkan efisiensi keseluruhan Anda saat mengupload:

• Ikuti praktik terbaik penanganan error dan percobaan ulang, dengan memperhatikan poin-poin berikut:
  • Error 429 dapat terjadi jika kuota Anda telah habis atau Anda dibatasi kecepatan karena melakukan terlalu banyak panggilan terlalu cepat. Pastikan Anda tidak memanggil batchCreate untuk pengguna yang sama hingga permintaan sebelumnya selesai.
  • Error 429 memerlukan penundaan 30s minimum sebelum mencoba lagi. Gunakan strategi backoff eksponensial saat mencoba lagi permintaan.
  • Error 500 terjadi saat server mengalami error. Saat mengupload, kemungkinan besar hal ini terjadi karena melakukan beberapa panggilan tulis (seperti batchCreate) untuk pengguna yang sama pada waktu yang sama. Periksa detail permintaan Anda dan jangan membuat 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 karena Anda dapat melanjutkan upload yang belum selesai sebagian. Hal ini penting saat mengupload dari perangkat seluler klien, atau saat mengupload file 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 ke batchCreate untuk satu pengguna.

  • Untuk setiap pengguna, lakukan panggilan ke batchCreate satu demi satu (secara berurutan).
  • 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 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 yang dibuat secara otomatis lainnya di kolom deskripsi.

Contoh panduan

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

Langkah 1: Upload byte mentah

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

• Jumlah thread upload serentak bergantung pada lingkungan operasi Anda.
• Pertimbangkan untuk menyusun ulang antrean upload sesuai kebutuhan. Misalnya, Anda dapat membuat prioritas upload berdasarkan jumlah upload yang tersisa per pengguna, progres keseluruhan pengguna, atau persyaratan lainnya.

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 melakukan satu panggilan untuk setiap pengguna dalam satu waktu.

// 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 panggilan pembuatan media dan upload selesai.