Medyayı yükle

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

1. Medya dosyalarınızın baytlarını, yüklemeleri kullanarak bir Google sunucusuna yükleyin uç nokta. Bu, emin olun.
2. Şu işlem için yükleme jetonuyla bir batchCreate çağrısı kullanın: Kullanıcının Google Fotoğraflar hesabında bir medya öğesi oluşturabilir.

Bu adımlar, tek bir medya öğesi yükleme işlemini özetler. Birden fazla medya öğesi yüklüyorsanız (üretim uygulamaları için büyük olasılıkla) yükleme verimliliğinizi artırmak üzere yüklemeyle ilgili en iyi uygulamaları inceleyin.

Başlamadan önce

Gerekli yetkilendirme kapsamları

Bir kullanıcının kitaplığına veya albümüne medya öğeleri yüklemek için photoslibrary.appendonly kapsamı. Kapsamlar hakkında daha fazla bilgi için Yetkilendirme kapsamları.

Kabul edilen dosya türleri ve boyutları

Bu tabloda listelenen dosya türlerini yükleyebilirsiniz.

1. Adım: Bayt yükleme

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

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

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

Google Photos Library API, devam ettirilebilir yükleme başlıklı makaleyi inceleyin. Devam ettirilebilir bir yükleme, bir medya dosyasını birden fazla bölüme ayırabilir ve tek seferde bir bölüm yükleyebilirsiniz.

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

Medya dosyalarınızın baytlarını yükledikten sonra bunları medya olarak oluşturabilirsiniz öğeleri Google Fotoğraflar'daki yükleme jetonlarını kullanarak. Yükleme jetonu geçerli bir gün süreyle kullanılabilir. Medya öğeleri her zaman kullanıcının kitaplığına eklenir. Medya öğeleri yalnızca tarafından oluşturulan albüm uygulamasını indirin. Daha fazla bilgi için bkz. Yetkilendirme kapsamlarını inceleyin.

Yeni medya öğeleri oluşturmak için şu numarayı arayın: mediaItems.batchCreate (newMediaItems listesi belirterek) Her newMediaItem bir yükleme içerir simpleMediaItem içinde belirtilen jeton ve isteğe bağlı bir açıklama gösterilen resimdir.

Açıklama alanı 1.000 karakterle sınırlıdır ve yalnızca anlamlı metinlere dayanıyor. Örneğin, "Parka gezimiz" veya "Tatil 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 fazla medya öğesi ekleyerek yapmanız gereken mediaItems.batchCreate çağrı sayısını azaltın. Aynı kullanıcı için sonraki bir arama yapmadan önce her zaman önceki isteğin tamamlanmasını bekleyin.

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

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

Ayrıca, şunlar için albumId ve albumPosition belirtebilirsiniz: Medya öğelerini albümde belirli bir konuma ekleyin.

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

Albümlerin konumlandırılmasıyla ilgili daha fazla ayrıntı için bkz. Ekleme zenginleştirme araçlarını deneyin.

Öğe oluşturma yanıtı

mediaItems.batchCreate çağrısı, medya öğelerinin her biri için sonucu döndürür bir cümle ekleyebilirsiniz. newMediaItemResults listesi durumu ve , isteğin uploadToken değerini içerir. Sıfır olmayan bir durum kodu, bir hatayı gösterir.

{
  "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, şunu içeren bir mediaItem döndürülür: mediaItemId, productUrl ve mediaMetadata. 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 işlemeyi açıklayan bir status içeriyor durumunu bilebilirsiniz. Yeni yüklenen bir dosya PROCESSING durumunu döndürüyor önce, kullanılacak READY. Ayrıntılar için Medya öğelerine erişim başlıklı makaleyi inceleyin.

Bu görüşme sırasında hatayla karşılaşırsanız En iyi 'u tıklayın ve isteğinizi yeniden 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 daha fazla bilgi için Oluşturma albümleri sayfasında bulabilirsiniz.

Sonuçlar her zaman, yükleme jetonlarının çalıştırıldığı sırayla döndürülür. gönderildi.

Yüklemeler için en iyi uygulamalar

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

• Aşağıdaki noktaları göz önünde bulundurarak yeniden deneme ve hata işlemeyle ilgili en iyi uygulamaları uygulayın:
  • Kotanız aşıldığında 429 hataları oluşabilir ya da çok hızlı şekilde çok fazla arama yapmanız durumunda arama hızınız sınırlandırılmış olabilir. Şunlardan emin olun: öncekine kadar aynı kullanıcı için batchCreate yöntemini çağırmazsanız isteği tamamlandı.
  • 429 hata, yeniden denemeden önce en az 30s gecikme yapılmasını gerektirir. Bir eksponansiyel geri yükleme stratejisini belirlemelisiniz.
  • Sunucu bir hatayla karşılaştığında 500 hataları oluşur. Yükleme yaparken bunun nedeni büyük olasılıkla birden fazla yazma çağrısı (ör. batchCreate) aynı anda değiştirebilirsiniz. Ayrıntıları kontrol edin istekte bulunmanızı ve paralel olarak batchCreate çağrılarını yapmayın.
• Şu işlemler için devam ettirilebilir yükleme akışını kullanın: yüklemelerinizi ağ kesintileri durumunda daha sağlam hale getirerek bant genişliği kullanımını artırır. Bu istemci mobil cihazlarından yükleme yaparken veya büyük dosyalar olabilir.

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 oluşturma öğeler hakkında daha fazla bilgi edinin.

Bayt yükleme

• Bayt yükleme işlemi (yükleme jetonlarını almak için) paralel olarak yapılabilir.
• Her yükleme çağrısında X-Goog-Upload-Content-Type başlığında her zaman doğru MIME türünü ayarlayın.

Medya öğeleri oluşturuluyor

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

  • Her kullanıcı için batchCreate çağrısını art arda yapın ( seri) ile ilgili daha fazla bilgi edinin.
  • Birden fazla kullanıcı için her kullanıcı için batchCreate çağrılarını her zaman birbiri ardına yapın. Paralel olarak yalnızca farklı kullanıcılar için arama yapın.

• Mümkün olduğunca çok NewMediaItems ekleyin yaptığınız toplam arama sayısını en aza indirmek için batchCreate numaralı telefona yönelik her aramada hazırlıyoruz. En fazla 50 öğe ekleyebilirsiniz.

• Anlamlı bir açıklama metni belirleyin bir şablondan oluşur. Şu veriler gibi meta verileri eklemeyin: programlı etiketler veya otomatik olarak oluşturulan diğer metinler için açıklama alanına ekleyebilirsiniz.

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

Bu örnekte, birden çok öğe için medya öğelerini yükleme işlemini adım adım göstermek üzere sözde kod kullanılmaktadır. yardımcı olur. Hedef, yükleme sürecinin her iki adımını da ana hatlarıyla belirtmektir (ham dosya yükleme bayt ve medya öğeleri oluşturma) içeriyorsa ve verimli ve dayanıklı bir yükleme oluşturmaya yönelik en iyi uygulamaları ayrıntılandırma inceleyebilirsiniz.

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

Öncelikle tüm medya öğelerinizden medya öğeleriniz için ham baytları yüklemek üzere bir sıra oluşturun. yardımcı olur. 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.
• Yükleme sırasını gerektiği şekilde yeniden sıralamayı düşünebilirsiniz. Örneğin herkesin Kullanıcı başına kalan yükleme sayısına göre yüklemeleri önceliklendirmek veya diğer gerekliliklere göre değişebilir.

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.

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