آپلود رسانه

آپلود آیتم های رسانه یک فرآیند دو مرحله ای است:

  1. بایت های فایل های رسانه ای خود را با استفاده از نقطه پایانی آپلودها در یک سرور Google آپلود کنید. این یک نشانه آپلود را برمی گرداند که بایت های آپلود شده را شناسایی می کند.
  2. برای ایجاد یک آیتم رسانه در حساب 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 استفاده کنید.

استراحت

فیلدهای زیر را در هدر درخواست POST قرار دهید:

فیلدهای سرصفحه
Content-type روی application/octet-stream تنظیم کنید.
X-Goog-Upload-Content-Type توصیه می شود. نوع MIME بایت هایی را که آپلود می کنید تنظیم کنید. انواع متداول MIME عبارتند از: image/jpeg ، image/png و image/gif .
X-Goog-Upload-Protocol روی raw تنظیم کنید.

در اینجا یک عنوان درخواست POST وجود دارد:

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

اگر این درخواست POST موفقیت آمیز باشد، یک نشانه آپلود که به شکل یک رشته متن خام است، به عنوان بدنه پاسخ برگردانده می شود. برای ایجاد آیتم های رسانه، از این رشته های متنی در فراخوانی batchCreate استفاده کنید.

upload-token

جاوا 

// 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 با استفاده از نشانه های آپلود ایجاد کنید. رمز آپلود یک روز پس از ایجاد معتبر است. یک آیتم رسانه همیشه به کتابخانه کاربر اضافه می شود. موارد رسانه را فقط می توان به آلبوم های ایجاد شده توسط برنامه شما اضافه کرد . برای اطلاعات بیشتر، به محدوده مجوز مراجعه کنید.

برای ایجاد آیتم های رسانه ای جدید، با مشخص کردن لیستی از newMediaItems ، mediaItems.batchCreate را فراخوانی کنید. هر newMediaItem حاوی یک نشانه آپلود است که در داخل یک simpleMediaItem مشخص شده است، و یک توضیح اختیاری است که به کاربر نشان داده می شود.

فیلد توضیحات به 1000 کاراکتر محدود شده است و فقط باید شامل متن معنادار ایجاد شده توسط کاربران باشد. به عنوان مثال، " سفر ما به پارک " یا " شام تعطیلات ". ابرداده‌هایی مانند نام فایل، برچسب‌های برنامه‌ای یا سایر متن‌هایی که به‌طور خودکار تولید می‌شوند را درج نکنید.

برای بهترین عملکرد، تعداد تماس‌هایی را که باید با قرار دادن چندین مورد رسانه در یک تماس برقرار کنید، با mediaItems.batchCreate کاهش دهید. قبل از برقراری تماس بعدی برای همان کاربر، همیشه منتظر بمانید تا درخواست قبلی تکمیل شود.

می‌توانید با تعیین توضیحات و نشانه‌های آپلود مربوطه، یک آیتم رسانه واحد یا چندین مورد رسانه در کتابخانه کاربر ایجاد کنید:

استراحت

در اینجا هدر درخواست POST آمده است:

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"
      }
    }
   , ...
  ]
}

جاوا 

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 آلبوم، آیتم های رسانه ای را به کتابخانه و آلبوم اضافه کنید. برای اطلاعات بیشتر، به ایجاد آلبوم مراجعه کنید.

هر آلبوم می تواند حداکثر 20000 آیتم رسانه ای داشته باشد. درخواست‌ها برای ایجاد موارد رسانه‌ای در آلبومی که از این حد فراتر می‌رود، ناموفق خواهند بود.

استراحت 

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

جاوا 

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"
  }
}

جاوا 

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 برای درخواست است. کد وضعیت غیر صفر نشان دهنده یک خطا است.

استراحت

اگر همه موارد رسانه با موفقیت ایجاد شده باشند، درخواست وضعیت HTTP 200 OK را برمی‌گرداند. اگر برخی از موارد رسانه را نمی توان ایجاد کرد، درخواست وضعیت HTTP 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"
      }
    }
  ]
}

جاوا 

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 حاوی status در داخل mediaMetadata خود است که وضعیت پردازش فایل ویدیویی را توصیف می کند. یک فایل تازه آپلود شده، قبل از READY برای استفاده، ابتدا وضعیت PROCESSING را برمی‌گرداند. برای جزئیات، به دسترسی به موارد رسانه مراجعه کنید.

اگر در طول این تماس با خطایی مواجه شدید، بهترین شیوه ها را دنبال کنید و درخواست خود را دوباره امتحان کنید. ممکن است بخواهید موارد اضافه شده موفق را پیگیری کنید، بنابراین در درخواست بعدی می توان تصویر را در موقعیت صحیح در آلبوم قرار داد. برای اطلاعات بیشتر، به ایجاد آلبوم مراجعه کنید.

نتایج همیشه به همان ترتیبی که توکن‌های آپلود ارسال شده بودند، بازگردانده می‌شوند.

بهترین روش ها برای آپلود

بهترین شیوه ها و منابع زیر به بهبود کارایی کلی شما در آپلودها کمک می کند:

  • از یکی از کتابخانه های مشتری پشتیبانی شده ما استفاده کنید.
  • با رعایت نکات زیر، بهترین شیوه‌های مدیریت خطا و تلاش مجدد را دنبال کنید:
    • خطای 429 ممکن است زمانی رخ دهد که سهمیه شما تمام شده باشد یا نرخ تماس شما برای برقراری تماس های خیلی سریع محدود شده باشد. اطمینان حاصل کنید که تا زمانی که درخواست قبلی تکمیل نشده است، برای همان کاربر با batchCreate تماس نگیرید.
    • 429 خطا به حداقل 30s تاخیر قبل از تلاش مجدد نیاز دارند. هنگام تلاش مجدد درخواست ها از یک استراتژی عقب نشینی نمایی استفاده کنید.
    • 500 خطا زمانی رخ می دهد که سرور با خطا مواجه شود. هنگام آپلود، این به احتمال زیاد به دلیل برقراری تماس های نوشتن چندگانه (مانند batchCreate ) برای یک کاربر به طور همزمان است. جزئیات درخواست خود را بررسی کنید و به صورت موازی با batchCreate تماس نگیرید.
  • از جریان آپلود قابل ازسرگیری استفاده کنید تا بارگذاری‌های خود را در مواقع قطع شبکه قوی‌تر کنید و با این امکان که به شما امکان می‌دهد آپلودهای نیمه تمام شده را از سر بگیرید، استفاده از پهنای باند را کاهش دهید. این هنگام آپلود از دستگاه های تلفن همراه مشتری یا هنگام آپلود فایل های بزرگ مهم است.

همچنین، نکات زیر را برای هر مرحله از فرآیند آپلود در نظر بگیرید: آپلود بایت ها و سپس ایجاد آیتم های رسانه .

در حال آپلود بایت ها

  • آپلود بایت ها (برای بازیابی نشانه های آپلود) می تواند به صورت موازی انجام شود.
  • همیشه نوع MIME صحیح را در هدر X-Goog-Upload-Content-Type برای هر تماس آپلود تنظیم کنید.

ایجاد آیتم های رسانه ای

  • برای یک کاربر به صورت موازی با batchCreate تماس برقرار نکنید.

    • برای هر کاربر، یکی پس از دیگری (به صورت سریال) با batchCreate تماس بگیرید.
    • برای چندین کاربر، همیشه تماس های batchCreate برای هر کاربر یکی پس از دیگری برقرار کنید. فقط برای کاربران مختلف به صورت موازی تماس برقرار کنید.

  • تا جایی که ممکن است NewMediaItems در هر تماس با batchCreate قرار دهید تا تعداد کل تماس هایی که باید انجام دهید به حداقل برسد. حداکثر می توانید 50 مورد را وارد کنید.

  • یک متن توصیف معنادار که توسط کاربران شما ایجاد شده است تنظیم کنید. ابرداده‌هایی مانند نام فایل‌ها، برچسب‌های برنامه‌نویسی یا سایر متن‌هایی که به‌طور خودکار تولید می‌شوند را در قسمت توضیحات وارد نکنید.

نمونه راهنما

این مثال از کد کاذب برای عبور از آیتم های رسانه ای بارگذاری شده برای چندین کاربر استفاده می کند. هدف این است که هر دو مرحله از فرآیند آپلود ( آپلود بایت های خام و ایجاد آیتم های رسانه ای ) و جزئیات بهترین شیوه ها برای ایجاد یک ادغام آپلود کارآمد و انعطاف پذیر را ترسیم کند.

مرحله 1: بایت های خام را بارگذاری کنید

ابتدا یک صف برای آپلود بایت های خام برای آیتم های رسانه ای خود از همه کاربران خود ایجاد کنید. ردیابی هر 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

مرحله 2: موارد رسانه ای ایجاد کنید

در مرحله 1، می توانید چندین بایت را از چندین کاربر به صورت موازی آپلود کنید، اما در مرحله 2 می توانید تنها یک تماس برای هر کاربر در یک زمان برقرار کنید.

شبه کد 

// 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.

این روند را تا زمانی که تمام آپلودها و تماس های ایجاد رسانه تکمیل شود ادامه دهید.