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çinbatchCreate
yöntemini çağırmadığınızdan emin olun. 429
hata, yeniden denenmeden önce en az30s
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 olarakbatchCreate
çağrıları yapmayın.
- 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
- 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.
- Her kullanıcı için
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 çokNewMediaItems
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.