Bu sayfa, Cloud Translation API ile çevrilmiştir.

Medyayı yükle

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

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

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

Başlamadan önce

Gerekli yetkilendirme kapsamları

Medya öğelerini bir kullanıcının kitaplığına veya albümüne yüklemek için photoslibrary.appendonly veya photoslibrary kapsamı gerekir.

Medya öğeleri, photoslibrary.sharing kapsamı kullanılarak da oluşturulabilir. photoslibrary.sharing kapsamında öğeler oluşturmak için önce bir albüm oluşturmanız ve shareAlbum kullanılarak paylaşıldı olarak işaretlemeniz gerekir. Daha sonra, 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şturmak için erişim iznine sahip olup olmadığını belirtir.

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	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ü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 üstbilgisine 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.

Aşağıda POST isteği başlığını görebilirsiniz:

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 kodunu ekleyin:

media-binary-data

Bu POST isteği başarılı olursa yanıt gövdesi olarak ham metin dizesi biçimindeki 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'tan büyük 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 ayırmanıza 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ı Google Fotoğraflar'da yükleme jetonları kullanarak medya öğeleri olarak oluşturabilirsiniz. Yükleme jetonu, oluşturulduktan sonra bir gün için 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ı bölümüne bakın.

Yeni medya öğeleri oluşturmak için bir newMediaItems listesi belirterek mediaItems.batchCreate çağrısı yapı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ı metinleri içermelidir. Ö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 bir çağrıya birden çok medya öğesi ekleyerek, yapmanız gereken mediaItems.batchCreate çağrı sayısını azaltın. Aynı kullanıcı için tekrar bir çağrı yapmadan önce her zaman önceki istek tamamlanana kadar bekleyin.

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

REST

POST isteği başlığını burada bulabilirsiniz:

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

İsteğin 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 adlı albümü belirterek kitaplığa ve albüme medya öğeleri ekleyebilirsiniz. Daha fazla bilgi için Albüm oluşturma konusuna bakın.

Her albüm en fazla 20.000 medya öğesi içerebilir. Bir albümde bu sınırı aşacak 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
}

Medya öğelerini albümde belirli bir konuma 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"
  }
}

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ırmayla ilgili daha fazla bilgi için Zenginleştirme ekleme bölümüne bakın.

Öğe oluşturma yanıtı

mediaItems.batchCreate çağrısı, oluşturmaya çalıştığınız medya öğelerinin her biri için sonucu döndürür. newMediaItemResults listesi durumu gösterir ve istek için uploadToken özelliğini içerir. Sıfır olmayan bir durum kodu bir hata olduğunu belirtir.

REST

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

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 içinde video dosyasının işlenme durumunu açıklayan bir status içerir. Yeni yüklenmiş bir dosya kullanım için READY olmadan önce PROCESSING durumunu döndürür. Ayrıntılar için Medya öğelerine erişme bölümüne bakın.

Bu görüşme sırasında bir hatayla karşılaşırsanız En iyi uygulamaları takip edin 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 edinmek için Albüm oluşturma başlıklı makaleye göz atın.

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

Yüklemeler için en iyi uygulamalar

Aşağıdaki en iyi uygulamalar ve kaynaklar, yüklemelerle ilgili 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 giderme en iyi uygulamalarını izleyin:
- Kotanız aşındığında veya çok hızlı bir şekilde çok fazla çağrı yaptığınız için hızınız sınırlandırıldığında 429 hataları oluşabilir. Önceki istek tamamlanana kadar aynı kullanıcı için batchCreate yöntemini çağırmadığınızdan emin olun.
- 429 hata, yeniden denenmeden önce en az 30s gecikme gerektirir. İstekleri yeniden denerken eksponansiyel geri yükleme stratejisi kullanın.
- Sunucu bir hatayla karşılaştığında 500 hataları oluşur. Yükleme işlemi sırasında bu durum büyük olasılıkla aynı kullanıcı için aynı anda birden çok yazma çağrısı (batchCreate gibi) yapılmasından kaynaklanır. İsteğinizin ayrıntılarını kontrol edin ve paralel olarak batchCreate çağrıları yapmayın.
Yüklemelerinizi ağ kesintilerinde daha sağlam hale getirmek için devam ettirilebilir yükleme akışını kullanın. Böylece, kısmi olarak tamamladığınız yüklemeleri devam ettirerek bant genişliği kullanımını azaltabilirsiniz. Bu, istemci mobil cihazlarından yüklerken 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 daha sonra medya öğeleri oluşturma.

Bayt yükleniyor

Bayt yükleme (yükleme jetonlarını almak için) paralel olarak yapılabilir.
Her yükleme çağrısı için X-Goog-Upload-Content-Type üstbilgisinde daima doğru MIME türünü ayarlayın.

Medya öğeleri oluşturma

Tek bir kullanıcı için batchCreate çağrısına paralel olarak çağrı yapmayın.
- Her kullanıcı için batchCreate öğesine art arda çağrı yapın (seri modunda).
- Birden çok kullanıcı söz konusu olduğunda, her bir kullanıcı için daima birbiri ardına batchCreate çağrıları yapın. Yalnızca farklı kullanıcılar için paralel olarak çağrı yapın.
Yapmanız gereken toplam çağrı sayısını en aza indirmek için batchCreate öğesine yapılan her çağrıya 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 oluşturun. Açıklama alanına dosya adları, programatik etiketler veya otomatik olarak oluşturulmuş diğer metinler gibi meta veriler eklemeyin.

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

Bu örnekte, birden çok kullanıcı için medya öğelerinin yüklenmesinde adım adım yol göstermek üzere sözde kod kullanılmaktadır. Amaç, yükleme işleminin her iki adımını (ham bayt yükleme ve medya öğeleri oluşturma) özetleyip verimli ve esnek bir yükleme entegrasyonu oluşturmak için en iyi uygulamaları ayrıntılı şekilde açıklamaktadır.

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

Öncelikle, tüm kullanıcılarınızın medya öğeleriniz için ham baytlarını yüklemek üzere bir sıra oluşturun. Döndürülen her bir kullanıcı için uploadToken izleme. Şu önemli noktaları unutmayın:

Eş zamanlı yükleme iş parçacıklarının sayısı çalışma ortamınıza bağlıdır.
Yükleme sırasını gerektiği şekilde yeniden sıralayabilirsiniz. Örneğin, yüklemelerin önceliğini kullanıcı başına kalan yükleme sayısına, kullanıcının genel ilerleme durumuna veya diğer gereksinimlere göre önceliklendirebilirsiniz.

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şturma

1. adımda, paralel olarak birden fazla 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.