Medyayı yükle

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

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

  1. Yükleme uç noktasını kullanarak medya dosyalarınızın baytlarını bir Google Sunucusu'na yükleyin. 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 bir batchCreate çağrısı kullanın.

Bu adımlar, tek bir medya öğesinin yüklenme işlemini özetler. Birden çok medya öğesi yüklüyorsanız (büyük olasılıkla herhangi bir üretim uygulaması için geçerlidir), yükleme verimliliğinizi iyileştirmek için yüklemelerle ilgili en iyi uygulamaları inceleyin.

Başlamadan önce

Gerekli yetkilendirme kapsamları

Medya kitaplığının, kullanıcının kitaplığına veya albümüne yüklenmesi photoslibrary.appendonly veya photoslibrary kapsamını gerektirir.

Medya öğeleri, photoslibrary.sharing kapsamı kullanılarak da oluşturulabilir. photoslibrary.sharing kapsamındaki öğeleri oluşturmak için önce bir albüm oluşturmanız ve bunu shareAlbum kullanılarak paylaşılan olarak işaretlemeniz gerekir. Ardından, albümde kullanıcıyla paylaşılan medya öğeleri oluşturabilirsiniz. Doğrudan kullanıcının kitaplığında veya uygulamanızın paylaşmadığı albümlerde öğe oluşturamazsınız.

Albümleri listelerken isWriteable özelliği, uygulamanızın belirli bir albümde medya oluşturma erişimi olup olmadığını gösterir.

Kabul edilen dosya türleri ve boyutları

Aşağıdaki tabloda listelenen dosya türlerini yükleyebilirsiniz.

Medya türü Kabul edilen dosya türleri Maksimum dosya boyutu
Fotoğraflar 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. 10 GB

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. batchCreate çağrısıyla medya öğeleri oluşturmak için bu yükleme jetonlarını kullanın.

REST

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

Başlık alanları
Content-type application/octet-stream olarak ayarlayın.
X-Goog-Upload-Content-Type Önerilen. Yüklediğiniz baytların MIME türüne ayarlayın. Yaygın MIME türleri arasında image/jpeg, image/png ve image/gif bulunur.
X-Goog-Upload-Protocol raw olarak ayarlayın.

POST isteği başlığı aşağıdaki gibidir:

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

İsteğin gövdesine ikili dosyayı 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

Java

// Open the file and automatically close it after upload
try (RandomAccessFile file = new RandomAccessFile(pathToFile, "r")) {
  // Create a new upload request
  UploadMediaItemRequest uploadRequest =
      UploadMediaItemRequest.newBuilder()
              // The media type (e.g. "image/png")
              .setMimeType(mimeType)
              // The file to upload
              .setDataFile(file)
          .build();
  // Upload and capture the response
  UploadMediaItemResponse uploadResponse = photosLibraryClient.uploadMediaItem(uploadRequest);
  if (uploadResponse.getError().isPresent()) {
    // If the upload results in an error, handle it
    Error error = uploadResponse.getError().get();
  } else {
    // If the upload is successful, get the uploadToken
    String uploadToken = uploadResponse.getUploadToken().get();
    // Use this upload token to create a media item
  }
} catch (ApiException e) {
  // Handle error
} catch (IOException e) {
  // Error accessing the local file
}

PHP

try {
    // Create a new upload request by opening the file
    // and specifying the media type (e.g. "image/png")
    $uploadToken = $photosLibraryClient->upload(file_get_contents($localFilePath), null, $mimeType);
} catch (\GuzzleHttp\Exception\GuzzleException $e) {
    // Handle error
}

Resimler için önerilen dosya boyutu 50 MB'tan azdır. 50 MB'ın üzerindeki dosyalar performans sorunlarına açıktır.

Google Photos Library API devam ettirilebilir yüklemeleri destekler. Devam ettirilebilir yükleme, bir medya dosyasını birden çok bölüme bölmenize ve aynı anda 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 jetonu, oluşturulduktan sonraki bir gün boyunca geçerlidir. Kullanıcının kitaplığına her zaman bir medya öğesi eklenir. Medya öğeleri yalnızca uygulamanız tarafından oluşturulan albümlere eklenebilir. Daha fazla bilgi için Yetkilendirme kapsamları konusuna bakın.

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

Açıklama alanı 1.000 karakterle sınırlıdır ve yalnızca kullanıcılar tarafından oluşturulan anlamlı metinleri içermelidir. Örneğin, "park gezisi" veya "Tatil yemeği". Dosya adları, programatik etiketler veya otomatik olarak oluşturulan diğer metinler gibi meta verileri eklemeyin.

En iyi performans için tek bir aramaya 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 bir sonraki çağrı yapmadan önce her zaman önceki istek tamamlanana kadar bekleyin.

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

REST

POST isteği başlığı aşağıdaki gibidir:

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

İstek gövdesinde bir newMediaItems listesi belirtilmelidir.

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

Java

try {
  // Create a NewMediaItem with the following components:
  // - uploadToken obtained from the previous upload request
  // - filename that will be shown to the user in Google Photos
  // - description that will be shown to the user in Google Photos
  NewMediaItem newMediaItem = NewMediaItemFactory
          .createNewMediaItem(uploadToken, fileName, itemDescription);
  List<NewMediaItem> newItems = Arrays.asList(newMediaItem);

  BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);
  for (NewMediaItemResult itemsResponse : response.getNewMediaItemResultsList()) {
    Status status = itemsResponse.getStatus();
    if (status.getCode() == Code.OK_VALUE) {
      // The item is successfully created in the user's library
      MediaItem createdItem = itemsResponse.getMediaItem();
    } else {
      // The item could not be created. Check the status and try again
    }
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $newMediaItems = [];
    // Create a NewMediaItem with the following components:
    // - uploadToken obtained from the previous upload request
    // - filename that will be shown to the user in Google Photos
    // - description that will be shown to the user in Google Photos
    $newMediaItems[0] = PhotosLibraryResourceFactory::newMediaItemWithDescriptionAndFileName(
            $uploadToken, $itemDescription, $fileName);

    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems);
    foreach ($response->getNewMediaItemResults() as $itemResult) {
        $status = $itemResult->getStatus();
        if ($status->getCode() != Code::OK) {
            // Error while creating the item.
        }
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}


id albümünü belirterek kitaplığa ve bir albüme medya öğeleri ekleyebilirsiniz. Daha fazla bilgi için Albüm oluşturma bölümüne bakın.

Her albüm en fazla 20.000 medya öğesi içerebilir. Bir albümde bu sınırı aşan medya öğeleri oluşturma istekleri başarısız olur.

REST

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

Java

try {
  // Create new media items in a specific album
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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

REST

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

Java

try {
  // Create new media items in a specific album, positioned after a media item
  AlbumPosition positionInAlbum = AlbumPositionFactory.createFirstInAlbum();
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems, positionInAlbum);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems,
        ['albumId' => $albumId, 'albumPosition' => $albumPosition]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Albümlerde konumlandırma hakkında daha fazla bilgi için Zenginleştirme ekleme başlıklı makaleye bakın.

Öğe oluşturma yanıtı

mediaItems.batchCreate çağrısı, oluşturmaya çalıştığınız medya öğelerinin her birinin sonucunu döndürür. newMediaItemResults listesi, durumu belirtir ve istekle ilgili uploadToken öğesini içerir. Sıfır olmayan durum kodu, bir hata olduğunu gösterir.

REST

Tüm medya öğeleri başarıyla oluşturulduysa istek 200 OK HTTP durumunu döndürür. Bazı medya öğeleri oluşturulamazsa isteğin başarılı olduğunu belirtmek için HTTP durumu 207 MULTI-STATUS durumu döndürülü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"
      }
    }
  ]
}

Java

BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);

// The response contains a list of NewMediaItemResults
for (NewMediaItemResult result : response.getNewMediaItemResultsList()) {
  // Each result item is identified by its uploadToken
  String uploadToken = result.getUploadToken();
  Status status = result.getStatus();

  if (status.getCode() == Code.OK_VALUE) {
    // If the request is successful, a MediaItem is returned
    MediaItem mediaItem = result.getMediaItem();
    String id = mediaItem.getId();
    String productUrl = mediaItem.getProductUrl();
    // ...
  }
}

PHP

// The response from a call to batchCreateMediaItems returns a list of NewMediaItemResults
foreach ($response->getNewMediaItemResults() as $itemResult) {
    // Each result item is identified by its uploadToken
    $itemUploadToken = $itemResult->getUploadToken();
    // Verify the status of each entry to ensure that the item has been uploaded correctly
    $itemStatus = $itemResult->getStatus();
    if ($itemStatus->getCode() != Code::OK) {
        // Error when item is being created
    } else {
        // Media item is successfully created
        // Get the MediaItem object from the response
        $mediaItem = $itemResult->getMediaItem();
        // It contains details such as the Id of the item, productUrl
        $id = $mediaItem->getId();
        $productUrl = $mediaItem->getProductUrl();
        // ...
    }
}

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

Medya öğesi bir videoysa, önce işlenmesi gerekir. mediaItem, mediaMetadata dosyasının içinde video dosyasının işlenme durumunu açıklayan bir status içerir. Yeni yüklenen bir dosya, kullanım için READY olmadan önce PROCESSING durumunu döndürür. Ayrıntılar için Medya öğelerine erişme konusuna bakın.

Bu görüşme sırasında bir hatayla karşılaşırsanız En iyi uygulamaları izleyin ve isteğinizi yeniden deneyin. Başarılı eklemeleri takip etmek isteyebilirsiniz. Böylece resim, bir sonraki istek sırasında albüme doğru konuma eklenebilir. Daha fazla bilgi için Albüm oluşturma bölümüne bakın.

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üklemelerde genel verimliliğinizi artırmanıza yardımcı olur:

  • Desteklenen istemci kitaplıklarımızdan birini kullanın.
  • Aşağıdaki noktaları göz önünde bulundurarak yeniden deneme ve hata işleme en iyi uygulamalarını izleyin:
    • Kotanız açığa çıktığında veya çok hızlı bir şekilde çok fazla arama yapmanız durumunda fiyat sınırınız olduğunda 429 hataları oluşabilir. Önceki istek tamamlanana kadar batchCreate için aynı kullanıcıyı aramadığınızdan emin olun.
    • Yeniden deneme için 429 hatanın en az 30s gecikme süresi olması gerekir. İstekleri yeniden denerken üstel geri çekilme stratejisi kullanın.
    • Sunucu bir hatayla karşılaştığında 500 hatası oluşur. Yükleme sırasında bunun nedeni büyük olasılıkla aynı kullanıcı için aynı anda birden fazla yazma çağrısı (batchCreate gibi) yapmaktır. İsteğinizin ayrıntılarını kontrol edin ve paralel olarak batchCreate numaralı telefonu aramayın.
  • Devam ettirilebilir yükleme akışını kullanarak ağ kesintilerinde yüklemelerinizi daha güçlü hale getirin ve kısmen tamamlanan yüklemeleri devam ettirerek bant genişliği kullanımını azaltın. Bu, istemci mobil cihazlardan veya büyük dosyalar yüklerken önemlidir.

Ayrıca, yükleme işleminin her adımı için şu ipuçlarını 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 paralel olarak arama yapmayın.

    • Her kullanıcı için batchCreate adresine birbiri ardına arama yapın (seri olarak).
    • Birden fazla kullanıcı söz konusuysa 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 çağrı sayısını en aza indirmek için batchCreate numarasına yapılan her aramaya mümkün olduğunca NewMediaItems ekleyin. En fazla 50 öğe ekleyebilirsiniz.

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

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

Bu örnekte, birden çok kullanıcı için medya öğesi yükleme adımlarında sözde kod kullanılmıştır. Hedef, yükleme işleminin her iki adımını da (ham bayt yükleme ve medya öğeleri oluşturmak) özetlemek ve verimli ve uyumlu bir yükleme entegrasyonu oluşturmak için en iyi uygulamaları ayrıntılarıyla açıklamaktır.

1. Adım: İşlenmemiş baytları yükleyin

Önce, 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 kullanıcı başına uploadToken izlenir. Aşağıdaki önemli noktaları unutmayın:

  • Eş zamanlı yükleme ileti dizilerinin sayısı, işletim ortamınıza bağlıdır.
  • Yükleme sırasını gerektiği gibi yeniden sıralayabilirsiniz. Örneğin, kullanıcı başına kalan yükleme sayısına, kullanıcının genel ilerleme durumuna veya diğer şartlara göre yüklemelerin önceliğini belirleyebilirsiniz.

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, paralel olarak birden çok kullanıcıdan birden fazla bayt yükleyebilirsiniz ancak 2. adımda her kullanıcı için aynı anda yalnızca 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üklemeler ve medya oluşturma çağrıları tamamlanana kadar bu işleme devam edin.