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

Medyayı yükle

Medya öğelerinin yüklenmesi iki adımlı bir işlemdir:

Medya dosyalarınızın baytlarını yükleme uç noktasını kullanarak bir Google Sunucusuna 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 bir batchCreate çağrısı kullanın.

Bu adımlar, tek bir medya öğesi yükleme işlemini özetler. Birden fazla medya öğesi yüklüyorsanız (her türlü üretim uygulaması için muhtemelen mevcuttur) yükleme verimliliğini artırmak için 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 veya photoslibrary kapsamı gereklidir.

Medya öğeleri, photoslibrary.sharing kapsamı kullanılarak da oluşturulabilir. photoslibrary.sharing kapsamı ile öğe 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ümler listelenirken isWriteable özelliği, uygulamanızın belirli bir albüm için 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.	20 GB

1. Adım: bayt yükleme

Yükleme isteklerini kullanarak baytları Google'a 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ığı şu şekildedir:

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 yanıt işlenmemiş 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 küçüktü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 fazla bölüme bölmenize ve her defasında 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, yükleme jetonlarını kullanarak bunları 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ı bölümüne bakın.

Yeni medya öğeleri oluşturmak için bir newMediaItems listesi belirterek mediaItems.batchCreate yöntemini çağırın. Her newMediaItem, bir simpleMediaItem içinde belirtilen yükleme jetonunu ve 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 seyahatimiz" veya "Yemek 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 görüşmeye birden fazla medya öğesi ekleyerek mediaItems.batchCreate uygulamasına gelen aramaların sayısını azaltabilirsiniz. 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ığı şunlardır:

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

İstek gövdesinde 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 albüme medya öğesi 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 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ştirmeler 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 biri için sonucu döndürür. newMediaItemResults listesi durumu gösterir ve istek için 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 istek, kısmi başarı 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 bölümüne bakın.

Medya öğesi bir video ise önce öğenin işlenmesi gerekir. mediaItem, mediaMetadata içinde video dosyasının işlenme durumunu açıklayan bir status içerir. 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 bölümüne bakın.

Bu arama sırasında bir hatayla karşılaşırsanız En iyi uygulamaları izleyin ve isteğinizi tekrar deneyin. Başarıyla yapılan eklemeleri takip etmek isteyebilirsiniz. Böylece resim, bir sonraki istek sırasında albüme doğru konumda 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üklemeler için 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ı aklınızda bulundurarak yeniden deneme ve hata işlemeyle ilgili en iyi uygulamaları izleyin:
- Kotanız açığa çıktığında veya çok hızlı bir şekilde çok fazla arama yapmak zorunda kalırsanız 429 hataları oluşabilir. Önceki istek tamamlanana kadar aynı kullanıcı için batchCreate yöntemini çağırmadığınızdan emin olun.
- Yeniden denemeden önce 429 hatanın yaşanması için en az 30s gecikme gerekir. İstekleri yeniden denerken üstel geri çekilme stratejisi kullanın.
- Sunucu bir hatayla karşılaştığında 500 hataları oluşur. Yükleme işlemi, 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 numaralı telefonu aramayın.
Devam ettirilebilir yükleme akışını kullanarak ağ kesintilerinde yüklemelerinizi daha güçlü hale getirin ve kısmen tamamlanmış yüklemeleri devam ettirmenize olanak tanıyan bant genişliği kullanımını azaltın. İstemci mobil cihazlarından veya büyük boyutlu dosyalar yüklerken bu nokta önemlidir.

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

Bayt yükleme

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 başlığında her zaman doğru MIME türünü ayarlayın.

Medya öğeleri oluşturma

Tek bir kullanıcı için batchCreate paralel olarak arama yapmayın.
- Her kullanıcı için batchCreate numaralı telefonu art arda arayın (seri şeklinde).
- Birden fazla kullanıcı söz konusuysa her kullanıcı için birbiri ardına batchCreate çağrısı yapın. Yalnızca paralel olarak farklı kullanıcılar için arama yapın.
Yapmanız gereken toplam çağrı sayısını en aza indirmek için batchCreate çağrılarına 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şturulmuş 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 öğelerinin yüklenmesiyle ilgili sözde kod kullanılır. Amaç, yükleme işleminin her iki adımını (ham bayt yüklemek ve medya öğeleri oluşturmak) özetlemek ve verimli ve dayanıklı 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

Tüm kullanıcılardan medya öğelerinizin ham baytlarını yüklemek için önce bir sıra oluşturun. Kullanıcı başına döndürülen uploadToken etkinliklerini takip edin. 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ı gerekirse yeniden sıralamayı düşünebilirsiniz. Ö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şturma

1. adımda, paralel olarak birden fazla kullanıcıdan birden fazla bayt yükleyebilirsiniz. Ancak 2. adımda tek seferde her bir kullanıcı için 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.