بارگذاری رسانه

بارگذاری فایل‌های رسانه‌ای فرایندی دو مرحله‌ای است:

  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. ۲۰۰ مگابایت
ویدیوها ‫3GP،‏ 3G2،‏ ASF،‏ AVI،‏ DIVX،‏ M2T،‏ M2TS،‏ M4V،‏ MKV،‏ MMV،‏ MOD،‏ MOV،‏ MP4،‏ MPG،‏ MTS،‏ TOD،‏ WMV. ۲۰ گیگابایت

مرحله ۱: بارگذاری بایت‌ها

بایت‌ها را بااستفاده از درخواست‌های بارگذاری در 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
}

اندازه فایل پیشنهادی برای تصاویر کمتر از ۵۰ مگابایت است. فایل‌های بزرگ‌تر از ۵۰ مگابایت مستعد مشکلات عملکرد هستند.

Google Photos Library API از بارگذاری‌های ازسرگرفتنی پشتیبانی می‌کند. بارگذاری ازسرگرفتنی به شما امکان می‌دهد فایل رسانه‌ای را به چند بخش تقسیم کنید و هر بار یک بخش را بارگذاری کنید.

مرحله ۲: ایجاد فایل رسانه‌ای

پس‌از بارگذاری بایت‌های فایل‌های رسانه‌ای، می‌توانید آن‌ها را به‌عنوان فایل‌های رسانه‌ای در Google Photos بااستفاده از کدهای بارگذاری ایجاد کنید. یک نشانه بارگذاری برای یک روز پس از ایجاد معتبر است. فایل رسانه‌ای همیشه به کتابخانه کاربر اضافه می‌شود. فایل‌های رسانه‌ای فقط می‌توانند به آلبوم‌هایی اضافه شوند که توسط برنامه شما ایجاد شده‌اند. برای اطلاعات بیشتر، گستره‌های مجوز را ببینید.

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

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

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

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

استراحت

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

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

نتایج همیشه به همان ترتیبی که توکن‌های بارگذاری ارسال شده‌اند برگردانده می‌شوند.

روال‌های مطلوب برای بارگذاری‌ها

روال‌های مطلوب و منابع زیر به بهبود کارایی کلی شما در بارگذاری‌ها کمک می‌کند:

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

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

درحال بارگذاری بایت‌ها

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

درحال ایجاد فایل‌های رسانه‌ای

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

    • برای هر کاربر، یکی پس‌از دیگری با batchCreate تماس بگیرید (به‌صورت سریالی).
    • برای چند کاربر، همیشه تماس‌های batchCreate را برای هر کاربر یکی پس‌از دیگری برقرار کنید. فقط برای کاربران مختلف به‌طور موازی تماس برقرار کنید.
  • در هر تماس با batchCreate، تا حد امکان NewMediaItems را اضافه کنید تا تعداد کل تماس‌هایی را که باید برقرار کنید به حداقل برسانید. حداکثر می‌توانید ۵۰ مورد اضافه کنید.

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

راهنمای گام‌به‌گام نمونه

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

مرحله ۱: بارگذاری بایت‌های خام

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

این فرایند را تا زمانی که همه بارگذاری‌ها و تماس‌های ایجاد رسانه تکمیل شوند ادامه دهید.