Medyayı yükle

Medya öğelerini yükleme işlemi iki adımdan oluşur:

  1. uploads uç noktasını kullanarak medya dosyalarınızın baytlarını bir Google sunucusuna yükleyin. Bu işlem, yüklenen baytları tanımlayan bir yükleme jetonu döndürür.
  2. Kullanıcının Google Fotoğraflar hesabında medya öğesi oluşturmak için yükleme jetonuyla bir batchCreate çağrısı kullanın.

Bu adımlarda, tek bir medya öğesi yükleme süreci özetlenmiştir. Birden fazla medya öğesi yüklüyorsanız (büyük olasılıkla herhangi bir üretim uygulaması için) yükleme verimliliğinizi artırmak üzere yüklemelerle ilgili en iyi uygulamaları inceleyin.

Başlamadan önce

Gerekli yetkilendirme kapsamları

Kullanıcının kitaplığına veya albümüne medya öğeleri yüklemek için photoslibrary.appendonly kapsamı gerekir. Kapsamlar hakkında daha fazla bilgi için Yetkilendirme kapsamları başlıklı makaleyi inceleyin.

Kabul edilen dosya türleri ve boyutları

Bu tabloda listelenen dosya türlerini yükleyebilirsiniz.

Medya türü Kabul edilen dosya türleri Maksimum dosya boyutu
Fotoğraflar AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP, bazı RAW dosyaları. 200 MB
Videolar 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD, WMV. 20 GB

1. Adım: Bayt yükleme

Yükleme isteklerini kullanarak Google'a bayt yükleme Başarılı bir yükleme isteği, ham metin dizesi biçiminde bir yükleme jetonu döndürür. batchCreate çağrısıyla medya öğeleri oluşturmak için bu yükleme jetonlarını kullanın.

REST

Aşağıdaki alanları POST isteği başlığına ekleyin:

Üst bilgi alanları
Content-type application/octet-stream olarak ayarlayın.
X-Goog-Upload-Content-Type Önerilir. Yüklediğiniz baytların MIME türüne ayarlanır. Yaygın MIME türleri image/jpeg, image/png ve image/gif'dir.
X-Goog-Upload-Protocol raw olarak ayarlayın.

Aşağıda bir POST istek başlığı verilmiştir:

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

İstek metnine dosyanın ikili dosyasını ekleyin: 

media-binary-data

Bu POST isteği başarılı olursa yanıt gövdesi olarak ham metin dizesi biçiminde bir yükleme jetonu döndürülür. Medya öğeleri oluşturmak için batchCreate çağrısında bu metin dizelerini kullanın.

upload-token

Görseller için önerilen dosya boyutu 50 MB'tan azdır. 50 MB'tan büyük dosyalar performans sorunlarına yol açabilir.

Google Fotoğraflar Kitaplığı API'si devam ettirilebilir yüklemeleri destekler. Devam ettirilebilir yükleme, bir medya dosyasını birden fazla bölüme bölmenize ve tek seferde bir bölümü yüklemenize olanak tanır.

2. Adım: Medya öğesi oluşturma

Medya dosyalarınızın baytlarını yükledikten sonra, bunları yükleme jetonlarını kullanarak Google Fotoğraflar'da medya öğeleri olarak oluşturabilirsiniz. Yükleme jetonunun geçerlilik süresi, oluşturulduktan sonraki bir gündür. Bir medya öğesi her zaman kullanıcının kitaplığına eklenir. Medya öğeleri yalnızca uygulamanız tarafından oluşturulan albümlere eklenebilir. Daha fazla bilgi için Yetkilendirme kapsamları bölümüne bakın.

Yeni medya öğeleri oluşturmak için newMediaItems listesi belirterek mediaItems.batchCreate işlevini çağırın. Her newMediaItem, simpleMediaItem içinde belirtilen bir yükleme jetonu ve kullanıcıya gösterilen isteğe bağlı bir açıklama içerir.

Açıklama alanı 1.000 karakterle sınırlıdır ve yalnızca kullanıcılar tarafından oluşturulan anlamlı metinler içermelidir. Örneğin, "Park gezimiz" veya "Yeni yıl yemeği". Dosya adları, programatik etiketler veya otomatik olarak oluşturulmuş diğer metinler gibi meta veriler eklemeyin.

En iyi performans için tek bir çağrıya birden çok medya öğesi ekleyerek yapmanız gereken mediaItems.batchCreate çağrısı sayısını azaltın. Aynı kullanıcı için sonraki bir arama yapmadan önce her zaman önceki isteğin tamamlanmasını bekleyin.

Açıklamaları ve ilgili yükleme jetonlarını belirterek kullanıcının kitaplığında tek bir veya birden çok medya öğesi oluşturabilirsiniz:

REST

POST istek başlığı:

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

İstek metninde bir newMediaItems listesi belirtilmelidir.

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

Albümdeki belirli bir konuma medya öğeleri eklemek için albumId ve albumPosition değerlerini de belirtebilirsiniz.

REST

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

Albümlerde konumlandırmayla ilgili daha fazla bilgi için Zenginleştirme ekleme başlıklı makaleyi inceleyin.

Öğe oluşturma yanıtı

mediaItems.batchCreate çağrısı, oluşturmaya çalıştığınız her medya öğesinin sonucunu döndürür. newMediaItemResults listesi, durumu gösterir ve istek için uploadToken değerini içerir. Sıfır olmayan bir durum kodu hata olduğu anlamına gelir.

REST

Tüm medya öğeleri başarıyla oluşturulduysa istek, 200 OK HTTP durumunu döndürür. Bazı medya öğeleri oluşturulamazsa istek, kısmi başarıyı belirtmek için HTTP durumu 207 MULTI-STATUS döndürür.

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

Başarıyla eklenen bir öğe; mediaItemId, productUrl ve mediaMetadata değerlerini içeren bir mediaItem döndürülür. Daha fazla bilgi için Medya öğelerine erişme bölümüne bakın.

Medya öğesi bir video ise öncelikle bu öğenin işlenmesi gerekir. mediaItem, mediaMetadata içinde video dosyasının işleme durumunu tanımlayan bir status içerir. Yeni yüklenen bir dosya, kullanıma hazır olmadan önce önce PROCESSING durumunu döndürür. Ayrıntılar için Medya öğelerine erişim başlıklı makaleyi inceleyin.

Bu arama sırasında bir hatayla karşılaşırsanız en iyi uygulamaları uygulayıp isteğinizi tekrar deneyin. Başarılı eklemeleri takip edebilirsiniz. Böylece, resim bir sonraki istek sırasında albüme doğru konuma yerleştirilebilir. Daha fazla bilgi için Albüm oluşturma başlıklı makaleyi inceleyin.

Sonuçlar her zaman yükleme jetonlarının gönderildiği sırayla döndürülür.

Yüklemelerle ilgili en iyi uygulamalar

Aşağıdaki en iyi uygulamalar ve kaynaklar, yüklemelerle ilgili genel verimliliğinizi artırmanıza yardımcı olur:

  • Aşağıdaki noktaları göz önünde bulundurarak yeniden deneme ve hata giderme en iyi uygulamalarını izleyin:
    • 429 hataları, kotanız dolduğunda veya çok hızlı bir şekilde çok fazla çağrı yaptığınız için hız sınırına ulaştığınızda ortaya çıkabilir. Önceki istek tamamlanana kadar aynı kullanıcı için batchCreate çağrısı yapmadığınızdan emin olun.
    • 429 hata, yeniden denemeden önce en az 30s gecikme yapılmasını gerektirir. İstekleri yeniden denerken üstel geri yükleme stratejisi kullanın.
    • 500 hataları, sunucu bir hatayla karşılaştığında ortaya çıkar. Yükleme sırasında bu durum büyük olasılıkla aynı kullanıcı için aynı anda birden fazla yazma çağrısı (batchCreate gibi) yapılmasından kaynaklanır. İsteğinizin ayrıntılarını kontrol edin ve batchCreate çağrılarını paralel olarak yapmayın.
  • Ağ kesintileri durumunda yüklemelerinizi daha sağlam hale getirmek için devam ettirilebilir yükleme akışını kullanın. Bu akış, kısmen tamamlanmış yüklemeleri devam ettirmenize olanak tanıyarak bant genişliği kullanımını azaltır. Bu, istemci mobil cihazlarından veya büyük dosyaları yüklerken önemlidir.

Ayrıca, yükleme sürecinin her adımı için aşağıdaki ipuçlarını da göz önünde bulundurun: Bayt yükleme ve ardından medya öğeleri oluşturma.

Bayt yükleme

Medya öğeleri oluşturma

  • Tek bir kullanıcı için batchCreate ile paralel olarak arama yapmayın.

    • Her kullanıcı için batchCreate'e art arda (sıralı olarak) çağrı yapın.
    • Birden fazla kullanıcı için her zaman her kullanıcı için birbiri ardına batchCreate çağrısı yapın. Paralel olarak yalnızca farklı kullanıcılar için arama yapın.

  • Yapmanız gereken toplam arama sayısını en aza indirmek için batchCreate'a yaptığınız her aramaya mümkün olduğunca çok NewMediaItems ekleyin. En fazla 50 öğe ekleyebilirsiniz.

  • Kullanıcılarınız tarafından oluşturulan anlamlı bir açıklama metni ayarlayın. Açıklama alanına dosya adları, programatik etiketler veya otomatik olarak oluşturulan diğer metinler gibi meta veriler eklemeyin.

Örnek adım adım açıklamalı kılavuz

Bu örnekte, birden fazla kullanıcı için medya öğesi yükleme işleminde size yol göstermek üzere sözde kod kullanılmıştır. Amacımız, yükleme sürecinin her iki adımını da (ham baytları yükleme ve medya öğeleri oluşturma) özetlemek ve verimli ve esnek bir yükleme entegrasyonu oluşturmayla ilgili en iyi uygulamaları ayrıntılı olarak açıklamaktır.

1. adım: Ham baytları yükleyin

Öncelikle tüm kullanıcılarınızdan medya öğeleriniz için ham bayt yüklemek üzere bir sıra oluşturun. Döndürülen her uploadToken değerini kullanıcı başına takip edin. Şu önemli noktaları unutmayın:

  • Eşzamanlı yükleme iş parçacıklarının sayısı, işletim ortamınıza bağlıdır.
  • Gerekirse yükleme sırasını yeniden düzenleyebilirsiniz. Örneğin, yüklemelere kullanıcı başına kalan yükleme sayısına, kullanıcının genel ilerleme durumuna veya diğer şartlara göre öncelik verebilirsiniz.

Sözde kod

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

2. Adım: Medya öğeleri oluşturun

1. adımda, birden fazla kullanıcıdan paralel olarak birden fazla bayt yükleyebilirsiniz ancak 2. adımda her kullanıcı için aynı anda yalnızca tek bir çağrı yapabilirsiniz.

Sözde kod

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

Tüm yükleme ve medya oluşturma çağrıları tamamlanana kadar bu işleme devam edin.