آپلود رسانه

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

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

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

قبل از اینکه شروع کنی

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

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

انواع و اندازه‌های فایل مورد قبول

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

مرحله 1: آپلود بایت‌ها

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

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

upload-token

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

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

مرحله ۲: ایجاد یک آیتم رسانه‌ای

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

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

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

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

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

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer oauth2-token

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

{
  "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 آن است. برای اطلاعات بیشتر، به Access media items مراجعه کنید.

اگر آیتم رسانه‌ای یک ویدیو باشد، ابتدا باید پردازش شود. mediaItem حاوی status در داخل mediaMetadata خود است که وضعیت پردازش فایل ویدیویی را توصیف می‌کند. یک فایل تازه آپلود شده ابتدا وضعیت PROCESSING را برمی‌گرداند، قبل از اینکه READY استفاده شود. برای جزئیات بیشتر، به Access media items مراجعه کنید.

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

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

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

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

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

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

آپلود بایت‌ها

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

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

• برای یک کاربر، فراخوانی‌های موازی با batchCreate انجام ندهید.

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

• تا حد امکان NewMediaItems در هر فراخوانی batchCreate قرار دهید تا تعداد کل فراخوانی‌هایی که باید انجام دهید به حداقل برسد. حداکثر می‌توانید ۵۰ آیتم را قرار دهید.

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

مثال پیاده روی

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

مرحله 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

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

در مرحله ۱، می‌توانید چندین بایت را از چندین کاربر به صورت موازی آپلود کنید، اما در مرحله ۲، فقط می‌توانید برای هر کاربر در یک زمان یک فراخوانی انجام دهید.

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

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