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