آپلود رسانه

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

  1. بایت های فایل های رسانه ای خود را با استفاده از نقطه پایانی آپلودها در یک سرور Google آپلود کنید. این یک نشانه آپلود را برمی گرداند که بایت های آپلود شده را شناسایی می کند.
  2. برای ایجاد یک آیتم رسانه در حساب Google Photos کاربر، از یک تماس batchCreate با نشانه آپلود استفاده کنید.

این مراحل روند آپلود یک آیتم رسانه ای را تشریح می کند. اگر چندین آیتم رسانه ای را آپلود می کنید (به احتمال زیاد برای هر برنامه تولیدی)، بهترین شیوه ها را برای آپلودها مرور کنید تا کارایی آپلود خود را بهبود ببخشید.

قبل از شروع

محدوده مجوز مورد نیاز

آپلود آیتم‌های رسانه در کتابخانه یا آلبوم کاربر به محدوده photoslibrary.appendonly نیاز دارد. برای اطلاعات بیشتر در مورد دامنه ها، به محدوده مجوز مراجعه کنید.

انواع و اندازه فایل های پذیرفته شده

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

نوع رسانه انواع فایل پذیرفته شده حداکثر اندازه فایل
عکس ها 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

حجم فایل پیشنهادی برای تصاویر کمتر از 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"
      }
    }
   , ...
  ]
}

همچنین می توانید albumId و albumPosition را برای درج موارد رسانه در یک مکان خاص در آلبوم مشخص کنید.

استراحت 

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

برای جزئیات بیشتر در مورد موقعیت‌یابی در آلبوم‌ها، به افزودن غنی‌سازی‌ها مراجعه کنید.

پاسخ ایجاد آیتم

فراخوان 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"
      }
    }
  ]
}

اگر یک مورد با موفقیت اضافه شود، یک 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.

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