Medya öğelerinin yüklenmesi iki adımlı bir işlemdir:
- yükleme uç noktasını kullanarak medya dosyalarınızın baytlarını bir Google sunucusuna yükleyin. Bu, yüklenen baytları tanımlayan bir yükleme jetonu döndürür.
- Ş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. Şu durumda: birden fazla medya öğesi yüklemek (büyük olasılıkla herhangi bir üretim uygulaması için), Daha iyi hale getirmek için yüklemelerle ilgili en iyi uygulamaları en iyi uygulamaları paylaşacağız.
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
veya photoslibrary
kapsamı.
Medya öğeleri, photoslibrary.sharing
kapsamı kullanılarak da oluşturulabilir. Alıcı:
photoslibrary.sharing
kapsamıyla öğeler oluşturmak için öncelikle bir
albümü shareAlbum
kullanarak paylaşıldı olarak işaretleyin. Ardından medya öğeleri oluşturabilirsiniz.
albümdeki kullanıcıyla paylaşılan verilerdir. Doğrudan şu sayfada öğe oluşturamazsınız:
kullanıcının kitaplığında veya uygulamanızın paylaşmadığı albümlerde yer alabilir.
Albümleri listelerken isWriteable
özelliği, albümdeki
uygulamasının belirli bir albümde medya oluşturma erişimi vardır.
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. Bu yüklemeleri kullan
batchCreate
çağrısı ile medya öğeleri oluşturmak için jetonlar.
REST
Aşağıdaki alanları POST isteği başlığına ekleyin:
Başlık alanları | |
---|---|
Content-type |
application/octet-stream olarak ayarlayın. |
X-Goog-Upload-Content-Type |
Önerilir. Yüklemekte olduğunuz baytların MIME türüne ayarlayın.
Yaygın MIME türleri arasında image/jpeg ,
image/png ve image/gif .
|
X-Goog-Upload-Protocol |
raw olarak ayarlayın. |
Aşağıda bir POST isteği başlığı verilmiştir:
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
dizesi, yanıt gövdesi olarak döndürülür. Medya oluşturmak için
öğeleri için bu metin dizelerini batchCreate
çağrısında 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 yatkındır.
Google Photos Library API, devam ettirilebilir yüklemeler. Devam ettirilebilir Yükleme, bir medya dosyasını birden fazla bölüme ayırıp tek bir bölüm yüklemenizi sağlar. bölümüne ekleyin.
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. Bir medya öğesi her zaman kullanıcının kitaplığını açar. Medya öğeleri yalnızca albümlere eklendi otomatik olarak oluşturulur. Daha fazla bilgi için Yetkilendirme kapsamları bölümüne bakın.
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 adı, programatik gibi meta veriler eklemeyin etiketleri veya otomatik olarak oluşturulan diğer metinleri kullanabilirsiniz.
En iyi performans için çağrı sayısını mediaItems.batchCreate
olacak şekilde azaltın
tek bir çağrıya birden çok medya öğesi ekleyerek bunu yapmanız gerekir. Her zaman bekleyin
önceki istek tamamlanana kadar
aynı kullanıcı.
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:
REST
POST isteği başlığı şöyledir:
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 }
Medya öğelerini
id
adlı albüm. Daha fazla bilgi için bkz.
Albüm oluşturun.
Her albüm en fazla 20.000 medya öğesi içerebilir. Medya oluşturma istekleri bir albümde bu sınırı aşacak öğeler başarısız olacak.
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 şunlar için albumId
ve albumPosition
belirtebilirsiniz:
Medya öğelerini albümde belirli bir konuma ekleyin.
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ümlerin konumlandırılmasıyla ilgili daha ayrıntılı bilgi için bkz. Zenginleştirme ekleyin.
Öğ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
hatası.
REST
Tüm medya öğeleri başarıyla oluşturulduysa istek,
200 OK
HTTP durumu. Medya öğeleri oluşturulamıyorsa
istek,207 MULTI-STATUS
ne kadar iyi olduğunu
belirlemenize yardımcı olur.
{ "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, şunu içeren bir mediaItem
döndürülür:
mediaItemId
, productUrl
ve mediaMetadata
. Daha fazla bilgi için bkz.
Medya öğelerine erişim.
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 bkz.
Medya öğelerine erişim.
Bu görüşme sırasında hatayla karşılaşırsanız şu adımları uygulayın: En iyi uygulamalar'ı tıklayın ve isteğinizi tekrar deneyin. Resmin eklenebilmesi için başarılı eklemeleri takip etmek isteyebilirsiniz istek sırasında doğru konuma yerleştirebilirsiniz. Daha fazla bkz. Albüm oluşturun.
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:
- Desteklenen istemci kitaplıklarımızdan birini kullanın.
- Yeniden deneme ve hata giderme en iyi uygulamalarını izleyin,
şu noktaları göz önünde bulundurun:
- 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çinbatchCreate
yöntemini çağırmazsanız isteği tamamlandı. 429
hata, yeniden denemeden önce en az30s
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 olarakbatchCreate
çağrılarını yapmayın.
- Kotanız aşıldığında
- Ş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. İstemci mobil cihazlarından yükleme yaparken bu önemlidir. dikkat edin.
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 öğeleri oluşturma.
Bayt yükleme
- Bayt yükleme işlemi (yükleme jetonlarını almak için) paralel olarak yapılabilir.
X-Goog-Upload-Content-Type
üstbilgisinde her zaman doğru MIME türünü ayarlayın yüklemenizi sağlar.
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 her zaman
batchCreate
araması yapın görürsünüz. Paralel olarak yalnızca farklı kullanıcılar için arama yapın.
- Her kullanıcı için
Mümkün olduğunca çok
NewMediaItems
ekleyin yaptığınız toplam arama sayısını en aza indirmek içinbatchCreate
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. Amaç, 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: İşlenmemiş 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 ileti dizilerinin sayısı işletim sisteminize bağlıdır bahsedeceğim.
- 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.
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. Adım 2 adımında, her bir kullanıcı için tek seferde yalnızca bir arama 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ükleme ve medya oluşturma çağrıları tamamlanana kadar bu işleme devam edin.