मीडिया अपलोड करें

मीडिया आइटम अपलोड करने की प्रोसेस दो चरणों में होती है:

  1. अपलोड एंडपॉइंट का इस्तेमाल करके, Google सर्वर पर अपनी मीडिया फ़ाइलों की बाइट अपलोड करें. यह अपलोड टोकन दिखाता है, जो अपलोड किए गए बाइट की पहचान करता है.
  2. अपलोड टोकन के साथ batchCreate कॉल का इस्तेमाल करें उपयोगकर्ता के Google Photos खाते में एक मीडिया आइटम बना सकता है.

यहां दिए गए तरीके से, किसी मीडिया आइटम को अपलोड करने की प्रोसेस के बारे में पता चलता है. अगर आप कई मीडिया आइटम अपलोड करना (किसी भी प्रोडक्शन ऐप्लिकेशन के लिए इसकी संभावना बहुत ज़्यादा होती है), अपलोड करने के सबसे सही तरीके देखें. इससे आपको अपने अपलोड की क्षमता.

शुरू करने से पहले

अनुमति के ज़रूरी दायरे

मीडिया आइटम को उपयोगकर्ता की लाइब्रेरी या एल्बम में अपलोड करने के लिए, 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, एमपीजी, एमटीएस, टीओडी, डब्ल्यूएमवी. 20 जीबी

पहला चरण: बाइट अपलोड करना

अपलोड के अनुरोधों का इस्तेमाल करके, 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, जिन पर फिर से शुरू किए जा सकने वाले अपलोड चुनें. फिर से शुरू किया जा सकने वाला प्लान अपलोड करने की सुविधा से, मीडिया फ़ाइल को कई सेक्शन में बांटा जा सकता है और एक सेक्शन को अपलोड किया जा सकता है सेक्शन को फिर से शुरू करें.

चरण 2: मीडिया आइटम बनाना

मीडिया फ़ाइलों के बाइट अपलोड करने के बाद, उन्हें मीडिया के तौर पर बनाया जा सकता है अपलोड टोकन का इस्तेमाल करके Google Photos में मौजूद आइटम. अपलोड टोकन मान्य है बनाए जाने के बाद एक दिन तक. मीडिया आइटम हमेशा उपयोगकर्ता के लाइब्रेरी. मीडिया आइटम सिर्फ़ ये हो सकते हैं एल्बम में जोड़ा गया आपके ऐप्लिकेशन से बनाया गया. ज़्यादा जानकारी के लिए, अनुमति के दायरे देखें.

नए मीडिया आइटम बनाने के लिए, कॉल करें mediaItems.batchCreate की सूची देकर newMediaItems. हर newMediaItem में एक अपलोड होता है टोकन, जिसे simpleMediaItem में बताया गया हो. साथ ही, जानकारी देना ज़रूरी नहीं है जो उपयोगकर्ता को दिखती है.

विवरण फ़ील्ड 1000 वर्णों तक सीमित है और इसमें केवल यह शामिल होना चाहिए उपयोगकर्ताओं का बनाया हुआ टेक्स्ट. उदाहरण के लिए, "हमारे पार्क की यात्रा" या "हॉलिडे डिनर". फ़ाइल नाम, प्रोग्रामेटिक जैसे मेटाडेटा शामिल न करें टैग या अन्य स्वचालित रूप से निर्मित टेक्स्ट का उपयोग कर सकते हैं.

सबसे अच्छी परफ़ॉर्मेंस के लिए, कॉल की संख्या को घटाकर 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 मौजूद है, जो प्रोसेसिंग के बारे में बताता है वीडियो फ़ाइल की स्थिति. अपलोड की गई नई फ़ाइल, PROCESSING का स्टेटस दिखाती है सबसे पहले, इस्तेमाल करने के लिए READY देने से पहले. जानकारी के लिए, यह देखें मीडिया आइटम ऐक्सेस करना.

अगर इस कॉल के दौरान आपको कोई गड़बड़ी मिलती है, तो सबसे सही तरीके देखें और फिर से अनुरोध करें. इमेज जोड़े जाने की जानकारी ट्रैक की जा सकती है, ताकि इमेज को शामिल किया जा सके अगले अनुरोध के दौरान सही स्थान पर एल्बम में कर सकते हैं. ज़्यादा के लिए जानकारी, देखें एल्बम बनाना.

नतीजे हमेशा उसी क्रम में दिखाए जाते हैं जिसमें अपलोड टोकन सबमिट किया गया.

वीडियो अपलोड करने के सबसे सही तरीके

आपकी परफ़ॉर्मेंस को बेहतर बनाने के लिए, यहां दिए गए सबसे सही तरीकों और संसाधनों की मदद ली जा सकती है अपलोड के साथ:

  • YouTube पर काम करने वाली किसी क्लाइंट लाइब्रेरी का इस्तेमाल करें.
  • फिर से कोशिश करने और गड़बड़ियों को ठीक करने के सबसे सही तरीके अपनाएं, इन बातों को ध्यान में रखें:
    • आपका कोटा खत्म होने के बाद 429 गड़बड़ियां हो सकती हैं या बहुत तेज़ी से बहुत ज़्यादा कॉल करने की वजह से, आपका रेवेन्यू सीमित हो गया है. पक्का करें कि आप उसी उपयोगकर्ता के लिए batchCreate को पिछले अनुरोध पूरा हो गया.
    • फिर से कोशिश करने से पहले, 429 गड़बड़ी होने पर, कम से कम 30s की देरी हो सकती है. किसी एक्स्पोनेंशियल बैकऑफ़ रणनीति तय करें.
    • 500 गड़बड़ियां तब होती हैं, जब सर्वर को कोई गड़बड़ी मिलती है. अपलोड करते समय, ऐसा अक्सर कई ईमेल लिखने के कारण होता है (जैसे batchCreate). इसकी जानकारी देखें आपका अनुरोध स्वीकार करेगा और batchCreate को साथ-साथ कॉल नहीं करेगा.
  • फिर से शुरू करने लायक अपलोड फ़्लो का इस्तेमाल करके अगर नेटवर्क में रुकावटें आती हैं, तो वीडियो को अपलोड करने की प्रोसेस को बेहतर बनाया जा सकता है. ऐसा करने से, आंशिक रूप से पूरे किए गए अपलोड को फिर से शुरू करने की सुविधा देकर बैंडविड्थ उपयोग को ट्रैक किया जा सकता है. यह क्लाइंट के मोबाइल डिवाइस से अपलोड करते समय या बड़ी फ़ाइलें अपलोड करते समय.

साथ ही, वीडियो अपलोड करने की प्रोसेस के हर चरण के लिए, यहां दी गई सलाह को ध्यान में रखें: बाइट अपलोड करना और फिर मीडिया आइटम बनाना.

बाइट अपलोड की जा रही हैं

  • बाइट अपलोड (अपलोड टोकन पाने के लिए) साथ-साथ की जा सकती है.
  • X-Goog-Upload-Content-Type हेडर में हमेशा सही MIME टाइप सेट करें हर अपलोड कॉल के लिए.

मीडिया आइटम बनाना

  • किसी एक उपयोगकर्ता के लिए batchCreate के साथ-साथ कॉल न करें.

    • हर उपयोगकर्ता के लिए, batchCreate को एक के बाद एक कॉल करें (इसमें सीरियल नंबर.
    • अगर एक से ज़्यादा उपयोगकर्ताओं को कॉल करना है, तो हर उपयोगकर्ता के लिए हमेशा batchCreate कॉल करें एक के बाद एक. साथ-साथ सिर्फ़ अलग-अलग उपयोगकर्ताओं के लिए कॉल करें.

  • ज़्यादा से ज़्यादा NewMediaItems शामिल करें हर कॉल में batchCreate पर किए गए कॉल की कुल संख्या को कम करने के लिए बहुत ही ज़रूरी है. ज़्यादा से ज़्यादा 50 आइटम शामिल किए जा सकते हैं.

  • ऐसा ब्यौरा टेक्स्ट सेट करें जो काम का हो जिसे आपके उपयोगकर्ताओं ने बनाया है. इस तरह का मेटाडेटा शामिल न करें फ़ाइल नाम, प्रोग्रामेटिक टैग या अपने-आप जनरेट होने वाले अन्य टेक्स्ट ब्यौरा.

सिलसिलेवार तरीके से दिए गए निर्देशों का उदाहरण

इस उदाहरण में एक से ज़्यादा प्रॉपर्टी के लिए मीडिया आइटम अपलोड करने के लिए pseudocode का इस्तेमाल किया गया है उपयोगकर्ता. इसका मकसद वीडियो अपलोड करने की प्रोसेस के दोनों चरणों के बारे में बताना है, जैसे कि अपलोड किए जा रहे वीडियो बाइट और मीडिया आइटम बनाना) और बेहतर और कारगर अपलोड बनाने के सबसे सही तरीकों के बारे में जानकारी दें इंटिग्रेशन.

पहला चरण: रॉ बाइट अपलोड करना

सबसे पहले अपने सभी मीडिया आइटम से अपने मीडिया आइटम की रॉ बाइट अपलोड करने के लिए एक सूची बनाएं उपयोगकर्ता. हर उपयोगकर्ता के लिए, लौटाए गए हर 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.

यह प्रोसेस तब तक जारी रखें, जब तक सभी अपलोड और मीडिया बनाने का अनुरोध पूरा नहीं हो जाता.