Medyayı yükle

Medya öğeleri yüklemek iki adımlı bir işlemdir:

  1. uploads endpoint'ini 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 bir medya öğesi oluşturmak için yükleme jetonuyla batchCreate çağrısı kullanın.

Bu adımlarda, tek bir medya öğesini yükleme süreci açıklanmaktadır. Birden fazla medya öğesi yüklüyorsanız (üretim uygulamalarında bu durum çok yaygındır) yükleme verimliliğinizi artırmak için yüklemelerle ilgili en iyi uygulamaları inceleyin.

Başlamadan önce

Gerekli yetkilendirme kapsamları

Medya öğelerini kullanıcının kitaplığına veya albümüne 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: Baytları yükleme

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

REST

POST isteği üstbilgisine aşağıdaki alanları 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 arasında image/jpeg, image/png ve image/gif bulunur.
X-Goog-Upload-Protocol raw olarak ayarlayın.

Aşağıda bir POST isteği 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 gövdesine 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 neden olabilir.

Google Photos Library API, devam ettirilebilir yüklemeleri destekler. Devam ettirilebilir yükleme, medya dosyasını birden fazla bölüme ayırmanıza ve her bölümü ayrı ayrı yüklemenize olanak tanır.

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

Medya dosyalarınızın baytlarını yükledikten sonra, yükleme jetonlarını kullanarak bunları Google Fotoğraflar'da medya öğeleri olarak oluşturabilirsiniz. Yükleme jetonları, oluşturulduktan sonraki bir gün boyunca geçerlidir. Medya öğeleri 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ı başlıklı makaleyi inceleyin.

Yeni medya öğeleri oluşturmak için mediaItems.batchCreate işlevini çağırın. newMediaItems listesini belirtin. 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, "Parka yaptığımız gezi" veya "Yılbaşı yemeği". Dosya adları, programatik etiketler veya otomatik olarak oluşturulan diğer metinler gibi meta verileri eklemeyin.

En iyi performansı elde etmek için tek bir çağrıya birden fazla medya öğesi ekleyerek yapmanız gereken mediaItems.batchCreate çağrılarının sayısını azaltın. Aynı kullanıcı için sonraki bir çağrıyı 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 medya öğesi veya birden fazla medya öğesi oluşturabilirsiniz:

REST

POST isteği başlığı:

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

İstek metninde newMediaItems listesi belirtilmelidir.

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

Ayrıca, albümde 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ümlerdeki konumlandırma hakkında 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 içerir. Sıfır olmayan bir durum kodu, hata olduğunu gösterir.

REST

Tüm medya öğeleri başarıyla oluşturulduysa istek, HTTP durumu 200 OK döndürür. Bazı medya öğeleri oluşturulamıyorsa 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"
      }
    }
  ]
}

Bir öğe başarıyla eklenirse mediaItem, productUrl ve mediaMetadata değerlerini içeren bir mediaItem döndürülür.mediaItemId Daha fazla bilgi için Medya öğelerine erişme başlıklı makaleyi inceleyin.

Medya öğesi bir videosa önce işlenmesi gerekir. mediaItem içinde, video dosyasının işleme durumunu açıklayan bir status bulunur.mediaMetadata Yeni yüklenen bir dosya, kullanılmak üzere READY olmadan önce PROCESSING durumunu döndürür. Ayrıntılar için Medya öğelerine erişme başlıklı makaleyi inceleyin.

Bu görüşme sırasında bir hatayla karşılaşırsanız En iyi uygulamalar bölümündeki adımları uygulayın ve isteğinizi tekrar deneyin. Bir sonraki istekte görüntünün albüme doğru konumda eklenebilmesi için başarılı eklemeleri takip etmek isteyebilirsiniz. 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 işleme ile ilgili en iyi uygulamaları uygulayın:
    • 429 hataları, kotanız tükendiğinde veya çok fazla çağrı yaptığınız için hız sınırına tabi tutulduğunuzda ortaya çıkabilir. Önceki istek tamamlanana kadar aynı kullanıcı için batchCreate işlevini çağırmadığınızdan emin olun.
    • 429 hataları için yeniden denemeden önce en az 30s süre beklenmesi gerekir. İstekleri yeniden denerken eksponansiyel geri yükleme stratejisi kullanın.
    • 500 hataları, sunucuda bir hata oluştuğunda meydana gelir. Yükleme sırasında bu durumun yaşanmasının en olası nedeni, aynı kullanıcı için aynı anda birden fazla yazma çağrısı (ör. batchCreate) yapılmasıdır. İsteğinizin ayrıntılarını kontrol edin ve batchCreate için paralel olarak arama yapmayın.
  • Yüklemelerinizi ağ kesintilerine karşı daha dayanıklı hale getirmek için devam ettirilebilir yükleme akışını kullanın. Bu akış, kısmen tamamlanmış yüklemelere devam etmenize olanak tanıyarak bant genişliği kullanımını azaltır. Bu, istemci mobil cihazlarından yükleme yaparken veya büyük dosyalar yüklerken önemlidir.

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

Yüklenen baytlar

Medya öğeleri oluşturma

  • Tek bir kullanıcı için batchCreate'ya paralel aramalar yapmayın.

    • Her kullanıcı için batchCreate'ya art arda (sırayla) çağrı yapın.
    • Birden çok kullanıcı için her kullanıcıya yönelik batchCreate çağrılarını her zaman sırayla yapın. Yalnızca farklı kullanıcılar için paralel olarak arama yapın.

  • Yapmanız gereken toplam çağrı sayısını en aza indirmek için batchCreate ile her çağrıya mümkün olduğunca çok sayıda 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 öğelerini yükleme sürecini açıklamak amacıyla sözde kod kullanılmıştır. Amaç, yükleme sürecinin her iki adımını (işlenmemiş baytları yükleme ve medya öğeleri oluşturma) özetlemek ve verimli ve esnek bir yükleme entegrasyonu oluşturmaya yönelik 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 gelen medya öğelerinizin ham baytlarını yüklemek için bir sıra oluşturun. Her kullanıcı için döndürülen uploadToken sayısını izleyin. Ş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 birden fazla baytı paralel olarak yükleyebilirsiniz ancak 2. adımda her kullanıcı için tek seferde 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.