मीडिया आइटम अपलोड करना दो चरणों वाली प्रक्रिया है:
- अपलोड एंडपॉइंट का इस्तेमाल करके, Google सर्वर पर अपनी मीडिया फ़ाइलों की बाइट अपलोड करें. इससे अपलोड टोकन दिखता है, जो अपलोड की गई बाइट की पहचान करता है.
- उपयोगकर्ता के Google Photos खाते में मीडिया आइटम बनाने के लिए, अपलोड टोकन के साथ batchCreate कॉल का इस्तेमाल करें.
इन चरणों से, एक मीडिया आइटम अपलोड करने की प्रोसेस के बारे में पता चलता है. अगर एक से ज़्यादा मीडिया आइटम अपलोड किए जा रहे हैं (किसी भी प्रोडक्शन ऐप्लिकेशन के लिए), तो अपलोड करने की क्षमता को बेहतर बनाने के लिए अपलोड करने के सबसे सही तरीके देखें.
शुरू करने से पहले
अनुमति देने के ज़रूरी दायरे
उपयोगकर्ता की लाइब्रेरी या एल्बम में मीडिया आइटम अपलोड करने के लिए,
photoslibrary.appendonly
या photoslibrary
स्कोप की ज़रूरत होती है.
photoslibrary.sharing
दायरे का इस्तेमाल करके भी मीडिया आइटम बनाए जा सकते हैं. photoslibrary.sharing
दायरे वाले आइटम बनाने के लिए, सबसे पहले आपको एक एल्बम बनाना होगा और shareAlbum
का इस्तेमाल करके उसे 'शेयर किया गया' के तौर पर मार्क करना होगा. इसके बाद, वे मीडिया आइटम बनाए जा सकते हैं
जिन्हें उपयोगकर्ता के साथ एल्बम में शेयर किया जाता है. आप सीधे उपयोगकर्ता की लाइब्रेरी में
या ऐसे एल्बम में आइटम नहीं बना सकते हैं, जिन्हें आपके ऐप्लिकेशन ने शेयर न किया हो.
एल्बम को सूची में जोड़ते समय, isWriteable
प्रॉपर्टी से यह पता चलता है कि आपके ऐप्लिकेशन के पास किसी खास एल्बम में मीडिया बनाने का ऐक्सेस है या नहीं.
स्वीकार किए जाने वाले फ़ाइल टाइप और साइज़
नीचे दी गई टेबल में दिए गए फ़ाइल टाइप अपलोड किए जा सकते हैं.
मीडिया टाइप | स्वीकार किए जाने वाले फ़ाइल टाइप | फ़ाइल का ज़्यादा से ज़्यादा साइज़ |
---|---|---|
फ़ोटो | AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP, कुछ RAW फ़ाइलें. | 200 एमबी |
वीडियो | 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD, WMV. | 20 जीबी |
चरण 1: बाइट अपलोड करना
अपलोड अनुरोध इस्तेमाल करके Google पर बाइट अपलोड करें. अपलोड के लिए अनुरोध पूरा होने पर, अपलोड टोकन को रॉ टेक्स्ट स्ट्रिंग के तौर पर दिखाया जाता है. इन अपलोड टोकन का इस्तेमाल
batchCreate
कॉल वाले मीडिया आइटम बनाने के लिए करें.
आराम
पोस्ट अनुरोध के हेडर में ये फ़ील्ड शामिल करें:
हेडर फ़ील्ड | |
---|---|
Content-type |
application/octet-stream पर सेट करें. |
X-Goog-Upload-Content-Type |
सुझाया गया. अपलोड किए जा रहे बाइट के MIME टाइप पर सेट करें.
सामान्य MIME टाइप में image/jpeg , image/png , और image/gif शामिल हैं.
|
X-Goog-Upload-Protocol |
raw पर सेट करें. |
यहां पोस्ट अनुरोध का हेडर दिया गया है:
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
अनुरोध के मुख्य हिस्से में, फ़ाइल की बाइनरी शामिल करें:
media-binary-data
अगर यह पोस्ट अनुरोध पूरा हो जाता है, तो अपलोड टोकन, रॉ टेक्स्ट स्ट्रिंग के तौर पर दिया जाता है. यह रिस्पॉन्स के मुख्य हिस्से के तौर पर दिखाया जाता है. मीडिया आइटम
बनाने के लिए, batchCreate
कॉल में इन टेक्स्ट स्ट्रिंग का इस्तेमाल करें.
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 }
इमेज के लिए सुझाया गया फ़ाइल साइज़ 50 एमबी से कम है. जिन फ़ाइलों का साइज़ 50 एमबी से ज़्यादा होता है उनमें परफ़ॉर्मेंस की समस्याएं हो सकती हैं.
Google Photos Library API, फिर से शुरू किए जा सकने वाले अपलोड के साथ काम करता है. फिर से शुरू किए जा सकने वाले अपलोड से, मीडिया फ़ाइल को कई सेक्शन में बांटा जा सकता है और एक बार में एक सेक्शन अपलोड किया जा सकता है.
दूसरा चरण: मीडिया आइटम बनाना
अपनी मीडिया फ़ाइलों की बाइट अपलोड करने के बाद, आप उन्हें अपलोड टोकन का इस्तेमाल करके Google Photos में मीडिया आइटम के तौर पर बना सकते हैं. अपलोड टोकन, बनाए जाने के एक दिन बाद तक मान्य होता है. मीडिया आइटम को उपयोगकर्ता की लाइब्रेरी में हमेशा जोड़ा जाता है. मीडिया आइटम सिर्फ़ आपके ऐप्लिकेशन से बनाए गए एल्बम में जोड़े जा सकते हैं. ज़्यादा जानकारी के लिए, अनुमति के दायरे देखें.
नए मीडिया आइटम बनाने के लिए, newMediaItems
की सूची तय करके
mediaItems.batchCreate
को कॉल करें. हर newMediaItem
में एक अपलोड टोकन होता है, जिसे simpleMediaItem
के अंदर बताया जाता है. साथ ही, इसमें एक वैकल्पिक जानकारी भी होती है, जो उपयोगकर्ता को दिखाई जाती है.
ब्यौरे वाले फ़ील्ड में 1,000 से ज़्यादा वर्ण नहीं होने चाहिए. साथ ही, इसमें सिर्फ़ वही टेक्स्ट शामिल होना चाहिए जो उपयोगकर्ताओं ने बनाया हो. उदाहरण के लिए, "हमारी पार्क की यात्रा" या "छुट्टियों में डिनर". फ़ाइल नाम, प्रोग्राम के हिसाब से अपने-आप जनरेट होने वाले टैग या अपने-आप जनरेट होने वाले दूसरे टेक्स्ट जैसा मेटाडेटा शामिल न करें.
सबसे अच्छी परफ़ॉर्मेंस के लिए, एक कॉल में कई मीडिया आइटम शामिल करके कॉल की संख्या कम करके mediaItems.batchCreate
करें. किसी उपयोगकर्ता के लिए दोबारा कॉल करने से पहले, हमेशा पिछला अनुरोध पूरा होने तक इंतज़ार करें.
किसी उपयोगकर्ता की लाइब्रेरी में, एक या एक से ज़्यादा मीडिया आइटम बनाए जा सकते हैं. इसके लिए, जानकारी और उससे जुड़े अपलोड टोकन तय करें:
आराम
यहां पोस्ट अनुरोध का हेडर दिया गया है:
POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate Content-type: application/json Authorization: Bearer oauth2-token
अनुरोध के मुख्य हिस्से में, newMediaItems
की सूची शामिल होनी चाहिए.
{ "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
में जानकारी देनी होगी. ज़्यादा जानकारी के लिए, एल्बम बनाना देखें.
हर एल्बम में 20,000 मीडिया आइटम हो सकते हैं. किसी ऐसे एल्बम में मीडिया आइटम बनाने के अनुरोध स्वीकार नहीं किए जाएंगे जो इस सीमा को पार कर जाएगा.
आराम
{ "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 }
एल्बम में किसी खास जगह पर मीडिया आइटम डालने के लिए, albumId
और albumPosition
के बारे में भी बताया जा सकता है.
आराम
{ "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 }
एल्बम में जगह तय करने के बारे में ज़्यादा जानकारी के लिए, बेहतर सुविधाएं जोड़ना देखें.
आइटम बनाने का जवाब
mediaItems.batchCreate
कॉल, हर उस मीडिया आइटम के लिए नतीजा दिखाता है
जो आपने बनाने की कोशिश की है. newMediaItemResults
की सूची, स्टेटस की जानकारी देती है और
इसमें अनुरोध के लिए uploadToken
शामिल होती है. सामान्य स्टेटस कोड किसी गड़बड़ी को दिखाता है.
आराम
अगर सभी मीडिया आइटम सही तरीके से बन गए हैं, तो अनुरोध
एचटीटीपी स्टेटस 200 OK
दिखाता है. अगर कुछ मीडिया आइटम बनाए नहीं जा सके,
तो अनुरोध, एचटीटीपी स्टेटस 207 MULTI-STATUS
दिखाता है. इससे पता चलता है कि कॉन्टेंट को 'पूरा नहीं हुआ' के तौर पर मार्क किया गया है.
{ "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(); // ... } }
अगर किसी आइटम को जोड़ दिया जाता है, तो mediaItem
दिखाया जाता है, जिसमें mediaItemId
, productUrl
, और mediaMetadata
शामिल होते हैं. ज़्यादा जानकारी के लिए, मीडिया आइटम ऐक्सेस करना देखें.
अगर मीडिया आइटम कोई वीडियो है, तो सबसे पहले उसे प्रोसेस करना ज़रूरी है. mediaItem
में mediaMetadata
के अंदर एक status
होता है, जो वीडियो फ़ाइल की प्रोसेसिंग की स्थिति के बारे में बताता है. अपलोड की गई नई फ़ाइल, इस्तेमाल के लिए READY
होने से पहले, PROCESSING
का स्टेटस दिखाती है. ज़्यादा जानकारी के लिए, मीडिया आइटम ऐक्सेस करना देखें.
अगर इस कॉल के दौरान आपको कोई गड़बड़ी मिलती है, तो सबसे सही तरीके अपनाएं और फिर से अनुरोध करें. हो सकता है कि आप जोड़े गए सफल प्रॉडक्ट का हिसाब रखना चाहें, ताकि अगले अनुरोध पर इमेज को एल्बम में सही जगह पर डाला जा सके. ज़्यादा जानकारी के लिए, एल्बम बनाना देखें.
हमेशा उसी क्रम में नतीजे दिखाए जाते हैं जिसमें अपलोड टोकन सबमिट किए गए थे.
वीडियो अपलोड करने के सबसे सही तरीके
यहां दिए गए सबसे सही तरीकों और संसाधनों से, आपको अपनी ज़रूरत के हिसाब से वीडियो अपलोड करने में मदद मिलती है.
- क्लाइंट लाइब्रेरी में से किसी एक का इस्तेमाल करें, जो उस डिवाइस के साथ काम करता हो.
- इन बातों को ध्यान में रखते हुए, फिर से कोशिश करने और गड़बड़ियों को ठीक करने के सबसे सही तरीके अपनाएं:
429
गड़बड़ियां तब हो सकती हैं, जब आपका कोटा बढ़ा दिया गया हो या बहुत ज़्यादा कॉल करने की वजह से सीमित हो. पक्का करें कि आप उस उपयोगकर्ता के लिएbatchCreate
को तब तक कॉल न करें, जब तक पिछला अनुरोध पूरा नहीं हो जाता.429
गड़बड़ी की पुष्टि करने के लिए, फिर से कोशिश करने से पहले, कम से कम30s
की देरी करनी होगी. अनुरोधों को फिर से कोशिश करते समय, एक्सपोनेन्शियल बैकऑफ़ रणनीति का इस्तेमाल करें.500
गड़बड़ियां तब होती हैं, जब सर्वर के सामने कोई गड़बड़ी आती है. अपलोड करते समय, ऐसा हो सकता है कि एक ही उपयोगकर्ता को एक ही समय में कई बार राइट कॉल (जैसे,batchCreate
) किए गए हों. अपने अनुरोध की जानकारी की जांच करें औरbatchCreate
पर एक साथ कॉल न करें.
- फिर से शुरू किए जा सकने वाले अपलोड फ़्लो का इस्तेमाल करें, ताकि नेटवर्क में रुकावट आने पर अपलोड किए गए वीडियो को बेहतर बनाया जा सके. साथ ही, बैंडविथ का इस्तेमाल कम किया जाए और पूरे किए गए अपलोड को फिर से शुरू किया जा सके. यह क्लाइंट के मोबाइल डिवाइस से अपलोड करते समय या बड़ी फ़ाइलें अपलोड करते समय ज़रूरी होता है.
अपलोड की प्रोसेस के हर चरण के लिए, यहां दी गई सलाह अपनाएं: बाइट अपलोड करना और फिर मीडिया आइटम बनाना.
बाइट अपलोड की जा रही हैं
- अपलोड टोकन वापस पाने के लिए बाइट अपलोड की जा सकती हैं.
- हर अपलोड कॉल के लिए,
X-Goog-Upload-Content-Type
हेडर में हमेशा सही MIME टाइप सेट करें.
मीडिया आइटम बनाए जा रहे हैं
किसी एक उपयोगकर्ता के लिए
batchCreate
के साथ-साथ कॉल न करें.- हर उपयोगकर्ता के लिए,
batchCreate
को एक के बाद एक कॉल करें (क्रम में). - कई उपयोगकर्ताओं के लिए, हर उपयोगकर्ता के लिए हमेशा एक के बाद
batchCreate
कॉल करें. साथ-साथ सिर्फ़ अलग-अलग उपयोगकर्ताओं के लिए कॉल करें.
- हर उपयोगकर्ता के लिए,
batchCreate
पर की जाने वाली हर कॉल में ज़्यादा से ज़्यादाNewMediaItems
शामिल करें, ताकि आपको किए जाने वाले कॉल की कुल संख्या कम हो सके. ज़्यादा से ज़्यादा 50 आइटम शामिल किए जा सकते हैं.ऐसा ब्यौरा टेक्स्ट सेट करें जिसे आपके उपयोगकर्ताओं ने बनाया हो. ब्यौरे वाले फ़ील्ड में फ़ाइल नाम, प्रोग्राम के हिसाब से अपने-आप जनरेट होने वाले टैग या अपने-आप जनरेट होने वाले दूसरे टेक्स्ट जैसा मेटाडेटा शामिल न करें.
सिलसिलेवार तरीके से दिए गए निर्देश का उदाहरण
इस उदाहरण में एक से ज़्यादा उपयोगकर्ताओं के लिए, मीडिया आइटम अपलोड करने की प्रोसेस बताने के लिए स्यूडोकोड का इस्तेमाल किया गया है. इसका मकसद अपलोड करने की प्रोसेस के दोनों चरणों (रॉ बाइट अपलोड करना और मीडिया आइटम बनाना) के बारे में बताना है. साथ ही, अपलोड करने का असरदार और बेहतर इंटिग्रेशन बनाने के लिए, सबसे सही तरीकों के बारे में बताना है.
पहला चरण: रॉ बाइट अपलोड करें
सबसे पहले अपने सभी उपयोगकर्ताओं के मीडिया आइटम के लिए रॉ बाइट अपलोड करने के लिए एक सूची बनाएं. हर उपयोगकर्ता के लिए, uploadToken
को ट्रैक करें. इन ज़रूरी बातों को याद रखें:
- एक साथ अपलोड होने वाले थ्रेड की संख्या, आपके ऑपरेटिंग सिस्टम पर निर्भर करती है.
- अपलोड की सूची का क्रम ज़रूरत के हिसाब से बदलें. उदाहरण के लिए, हर उपयोगकर्ता के बचे हुए अपलोड की संख्या, उपयोगकर्ता की प्रोग्रेस या अन्य ज़रूरतों के हिसाब से अपलोड को प्राथमिकता दी जा सकती है.
स्यूडोकोड
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
दूसरा चरण: मीडिया आइटम बनाना
पहले चरण में, एक साथ कई उपयोगकर्ताओं के एक से ज़्यादा बाइट अपलोड किए जा सकते हैं. लेकिन दूसरे चरण में, एक बार में हर उपयोगकर्ता के लिए सिर्फ़ एक कॉल किया जा सकता है.
स्यूडोकोड
// 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.
यह प्रोसेस तब तक जारी रखें, जब तक सभी अपलोड और मीडिया बनाने की प्रक्रिया पूरी नहीं हो जाती.