تصاویر را با Play Games Services Publishing API آپلود کنید

Play Games Services Publishing API به شما امکان می دهد تصویری را برای یک منبع بازی آپلود کنید.

گزینه های آپلود

Play Games Services Publishing API به شما امکان می‌دهد انواع خاصی از داده‌های باینری یا رسانه را آپلود کنید. ویژگی های خاص داده هایی که می توانید آپلود کنید در صفحه مرجع برای هر روشی که از آپلود رسانه پشتیبانی می کند مشخص شده است:

• حداکثر اندازه فایل آپلود : حداکثر مقدار داده ای که می توانید با این روش ذخیره کنید.

• انواع MIME رسانه های پذیرفته شده : انواع داده های باینری که می توانید با استفاده از این روش ذخیره کنید.

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

• آپلود ساده : uploadType=media . برای انتقال سریع فایل های کوچکتر، به عنوان مثال، 5 مگابایت یا کمتر.

• آپلود چند قسمتی : uploadType=multipart . برای انتقال سریع فایل های کوچکتر و متادیتا؛ فایل را به همراه ابرداده ای که آن را توصیف می کند، همه در یک درخواست منتقل می کند.

• بارگذاری مجدد : uploadType=resumable . برای انتقال مطمئن، به ویژه در مورد فایل های بزرگتر مهم است. با این روش، شما از یک درخواست شروع جلسه استفاده می کنید که به صورت اختیاری می تواند شامل ابرداده باشد. این یک استراتژی خوب برای استفاده برای اکثر برنامه‌ها است، زیرا برای فایل‌های کوچک‌تر با هزینه یک درخواست HTTP اضافی در هر بارگذاری نیز کار می‌کند.

هنگام آپلود رسانه، از یک URI ویژه استفاده می کنید. در واقع، روش هایی که از آپلود رسانه پشتیبانی می کنند، دارای دو نقطه پایانی URI هستند:

• URI / آپلود، برای رسانه . قالب نقطه پایانی آپلود، URI منبع استاندارد با پیشوند "/upload" است. از این URI هنگام انتقال خود داده رسانه استفاده کنید.

  مثال: POST /upload/games/v1configuration/images/resourceId/imageType/imageType

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

  مثال: POST /games/v1configuration/images/resourceId/imageType/imageType

آپلود ساده

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

• فایل به اندازه‌ای کوچک است که در صورت خرابی اتصال، دوباره به‌طور کامل آپلود شود.

• هیچ ابرداده ای برای ارسال وجود ندارد. این ممکن است درست باشد اگر قصد دارید متادیتا را برای این منبع در یک درخواست جداگانه ارسال کنید، یا اگر هیچ ابرداده ای پشتیبانی یا در دسترس نباشد. برای استفاده از آپلود ساده، یک درخواست POST یا PUT به /upload URI روش ارسال کنید و پارامتر query uploadType=media را اضافه کنید. به عنوان مثال:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media

هدرهای HTTP برای استفاده در هنگام درخواست آپلود ساده عبارتند از:

• Content-Type روی یکی از انواع داده های رسانه آپلود پذیرفته شده روش، که در مرجع انتشار API مشخص شده است، تنظیم کنید.

• Content-Length . تعداد بایت هایی را که آپلود می کنید تنظیم کنید. اگر از رمزگذاری انتقال تکه‌تکه استفاده می‌کنید، لازم نیست.

مثال: آپلود ساده

مثال زیر استفاده از یک درخواست آپلود ساده برای Play Games Services Publishing API را نشان می دهد.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/png
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

PNG data

اگر درخواست با موفقیت انجام شود، سرور کد وضعیت HTTP 200 OK را به همراه هر متادیتا برمی گرداند. به عنوان مثال:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

آپلود چند قسمتی

اگر متادیتا دارید که می‌خواهید همراه با داده‌ها برای آپلود ارسال کنید، می‌توانید یک درخواست multipart/related داشته باشید. اگر داده‌هایی که می‌فرستید به اندازه‌ای کوچک هستند که در صورت خرابی اتصال، دوباره به طور کامل آپلود شوند، این انتخاب خوبی است.

برای استفاده از آپلود چند قسمتی، یک درخواست POST یا PUT به /upload URI روش ارسال کنید و پارامتر query uploadType=multipart را اضافه کنید. به عنوان مثال:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart

هدرهای سطح بالای HTTP برای استفاده در هنگام درخواست آپلود چند قسمتی عبارتند از:

- Content-Type روی چندبخشی/مرتبط تنظیم کنید و رشته مرزی را که برای شناسایی بخش‌های درخواست استفاده می‌کنید، اضافه کنید.

- Content-Length تعداد کل بایت ها را در بدنه درخواست تنظیم کنید. بخش رسانه درخواست باید کمتر از حداکثر اندازه فایل مشخص شده برای این روش باشد.

بدنه درخواست به عنوان یک محتوای چندبخشی/مرتبط از نوع RFC2387 فرمت شده است و دقیقاً شامل دو بخش است. قسمت ها با یک رشته مرزی مشخص می شوند و رشته مرزی نهایی با دو خط فاصله دنبال می شود.

هر بخش از درخواست چند قسمتی به یک سرصفحه Content-Type اضافی نیاز دارد:

• بخش فراداده : باید اول باشد و Content-Type باید با یکی از قالب‌های فراداده پذیرفته شده مطابقت داشته باشد.

• بخش رسانه : باید در رتبه دوم قرار گیرد و Content-Type باید با انواع MIME رسانه پذیرفته شده روش مطابقت داشته باشد.

به انتشار مرجع API برای فهرست انواع MIME رسانه های پذیرفته شده هر روش و محدودیت های اندازه برای فایل های آپلود شده مراجعه کنید.

مثال: آپلود چند قسمتی

مثال زیر یک درخواست آپلود چند قسمتی برای Play Games Services Publishing API را نشان می دهد.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

--foo_bar_baz
Content-Type: image/png

PNG data
--foo_bar_baz--

اگر درخواست با موفقیت انجام شود، سرور کد وضعیت HTTP 200 OK را به همراه هر متادیتا برمی گرداند:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

بارگذاری مجدد

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

مراحل استفاده از بارگذاری مجدد شامل موارد زیر است:

1. یک جلسه قابل ازسرگیری را شروع کنید. یک درخواست اولیه به URI آپلود که شامل ابرداده است، در صورت وجود، ارائه دهید.

2. URI جلسه قابل ازسرگیری را ذخیره کنید. URI جلسه ای را که در پاسخ درخواست اولیه بازگردانده شده است ذخیره کنید. شما از آن برای درخواست های باقی مانده در این جلسه استفاده خواهید کرد. فایل را آپلود کنید.

3. فایل رسانه را به URI جلسه قابل تجدید ارسال کنید.

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

یک جلسه قابل ازسرگیری را شروع کنید

برای شروع یک آپلود مجدد، یک درخواست POST یا PUT به /upload URI متد ارسال کنید و پارامتر query uploadType=resumable را اضافه کنید. به عنوان مثال:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable

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

از هدرهای HTTP زیر برای درخواست اولیه استفاده کنید:

• X-Upload-Content-Type . نوع رسانه MIME داده های آپلود را برای انتقال در درخواست های بعدی تنظیم کنید.

• X-Upload-Content-Length . تعداد بایت های داده آپلود را برای انتقال در درخواست های بعدی تنظیم کنید. اگر طول در زمان این درخواست ناشناخته است، می توانید این هدر را حذف کنید.

• در صورت ارائه فراداده: Content-Type . با توجه به نوع داده ابرداده تنظیم کنید.

• Content-Length . تعداد بایت های ارائه شده در بدنه این درخواست اولیه را تنظیم کنید. اگر از رمزگذاری انتقال تکه‌تکه استفاده می‌کنید، لازم نیست.

به انتشار مرجع API برای فهرست انواع MIME رسانه های پذیرفته شده هر روش و محدودیت های اندازه برای فایل های آپلود شده مراجعه کنید.

مثال: درخواست شروع مجدد جلسه

مثال زیر نحوه راه‌اندازی یک جلسه قابل ازسرگیری برای Play Games Services Publishing API را نشان می‌دهد.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: image/png
X-Upload-Content-Length: 2000000

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

بخش بعدی نحوه رسیدگی به پاسخ را شرح می دهد.

URI جلسه قابل ازسرگیری را ذخیره کنید

اگر درخواست شروع جلسه با موفقیت انجام شود، سرور API با یک کد وضعیت HTTP 200 OK پاسخ می دهد. علاوه بر این، یک هدر Location ارائه می کند که URI جلسه قابل ازسرگیری شما را مشخص می کند. سرصفحه Location ، که در مثال زیر نشان داده شده است، شامل بخش پارامتر query upload_id است که شناسه آپلود منحصر به فرد را برای استفاده برای این جلسه می دهد.

مثال: پاسخ شروع مجدد جلسه

در اینجا پاسخ به درخواست در مرحله 1 آمده است:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

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

URI جلسه را کپی و ذخیره کنید تا بتوانید برای درخواست های بعدی از آن استفاده کنید.

فایل را آپلود کنید

برای آپلود فایل، یک درخواست PUT به URI آپلود که در مرحله قبل دریافت کردید ارسال کنید. فرمت درخواست آپلود:

PUT session_uri

هدرهای HTTP برای استفاده در هنگام درخواست بارگذاری مجدد فایل شامل Content-Length است. این را روی تعداد بایت هایی که در این درخواست آپلود می کنید، تنظیم کنید، که معمولاً اندازه فایل آپلود است.

مثال: درخواست بارگذاری مجدد فایل

در اینجا یک درخواست مجدد برای آپلود کل فایل PNG 2,000,000 بایتی برای مثال فعلی وجود دارد.

PUT https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/png

bytes 0-1999999

اگر درخواست با موفقیت انجام شود، سرور با HTTP 201 Created به همراه هر ابرداده مرتبط با این منبع پاسخ می دهد. اگر درخواست اولیه جلسه قابل ازسرگیری یک PUT برای به روز رسانی یک منبع موجود بود، پاسخ موفقیت آمیز 200 OK بود، همراه با هر ابرداده مرتبط با این منبع.

اگر درخواست آپلود قطع شد یا اگر یک HTTP 503 Service Unavailable یا هر پاسخ 5xx دیگری از سرور دریافت کردید، رویه ذکر شده در رزومه آپلود قطع شده را دنبال کنید.

فایل را به صورت تکه ای آپلود کنید

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

اگر داده‌ها را به صورت تکه‌ای آپلود می‌کنید، هدر Content-Range به همراه سرصفحه Content-Length مورد نیاز برای آپلود فایل کامل نیز لازم است:

• Content-Length . همانطور که برای آخرین درخواست ممکن است روی اندازه تکه یا احتمالاً کمتر تنظیم کنید.

• Content-Range . تنظیم کنید تا نشان دهد کدام بایت ها در فایلی که آپلود می کنید. به عنوان مثال، Content-Range: bytes 0-524287/2000000 نشان می دهد که شما اولین 524288 بایت (256 x 1024 x 2) را در یک فایل 2000000 بایتی ارائه می کنید.

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: image/jpeg
Content-Range: bytes 0-524287/2000000

bytes 0-524288

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

از سرگیری آپلود قطع شده

اگر یک درخواست آپلود قبل از دریافت پاسخ خاتمه یافت یا اگر پاسخ HTTP 503 Service Unavailable از سرور دریافت کردید، باید آپلود قطع شده را از سر بگیرید. برای از سرگیری آپلود قطع شده، موارد زیر را انجام دهید:

1. وضعیت درخواست با ارسال یک درخواست PUT خالی به URI آپلود، وضعیت فعلی آپلود را پرس و جو کنید. برای این درخواست، سرصفحه‌های HTTP باید شامل یک هدر Content-Range باشد که نشان می‌دهد موقعیت فعلی در فایل ناشناخته است. به عنوان مثال، Content-Range روی */2000000 تنظیم کنید اگر طول کل فایل شما 2000000 باشد. اگر اندازه کامل فایل را نمی دانید، Content-Range را روی */* تنظیم کنید.

2. دریافت تعداد بایت های آپلود شده پاسخ از پرس و جو وضعیت را پردازش کنید. سرور در پاسخ خود از هدر Range استفاده می کند تا مشخص کند که تا کنون کدام بایت را دریافت کرده است. به عنوان مثال، هدر Range از 0-299999 نشان می دهد که 300000 بایت اول فایل دریافت شده است.

3. داده های باقی مانده را آپلود کنید . در نهایت، اکنون که می‌دانید کجا درخواست را از سر بگیرید، داده‌های باقی‌مانده یا تکه فعلی را ارسال کنید. توجه داشته باشید که در هر صورت باید داده‌های باقی‌مانده را به‌عنوان یک تکه جداگانه در نظر بگیرید، بنابراین باید هدر Content-Range را هنگام از سرگیری آپلود ارسال کنید.

مثال: آپلود قطع شده را از سر بگیرید

1. وضعیت آپلود را درخواست کنید. درخواست زیر از هدر Content-Range برای نشان دادن اینکه موقعیت فعلی در فایل 2,000,000 بایتی ناشناخته است استفاده می کند.

   PUT {session_uri} HTTP/1.1
   Content-Length: 0
   Content-Range: bytes */2000000
   

2. تعداد بایت های آپلود شده تا کنون را از پاسخ استخراج کنید. پاسخ سرور از هدر Range استفاده می کند تا نشان دهد که 43 بایت اول فایل را تاکنون دریافت کرده است. از مقدار بالای هدر Range برای تعیین اینکه آپلود مجدد از کجا شروع شود استفاده کنید.

   HTTP/1.1 308 Resume Incomplete
   Content-Length: 0
   Range: 0-42
   

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

   PUT {session_uri} HTTP/1.1
   Content-Length: 1999957
   Content-Range: bytes 43-1999999/2000000
   
   bytes 43-1999999
   

رسیدگی به خطا

هنگام آپلود رسانه، آگاهی از برخی بهترین شیوه های مربوط به مدیریت خطا مفید است.

• آپلودهایی را که به دلیل قطع اتصال یا هر گونه خطای 5xx ناموفق هستند، از سر بگیرید یا دوباره امتحان کنید، از جمله:

  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

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

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

• با شروع بارگذاری از ابتدا، خطاهای 404 Not Found و 410 Gone را هنگام انجام آپلودهای قابل ازسرگیری مدیریت کنید.

عقب نشینی نمایی

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

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

جریان برای پیاده سازی عقب نشینی نمایی ساده به شرح زیر است:

1. یک درخواست به API بدهید.
2. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
3. 1 ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
4. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
5. 2 ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
6. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
7. 4 ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
8. یک HTTP 503 response دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
9. ۸ ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
10. یک HTTP 503 response دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
11. 16 ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
12. توقف کنید. یک خطا را گزارش یا ثبت کنید.

در لیست بالا، random_number_milliseconds تعداد تصادفی میلی‌ثانیه‌ها کمتر یا مساوی 1000 است. این امر ضروری است، زیرا معرفی یک تاخیر تصادفی کوچک به توزیع یکنواخت بار و جلوگیری از احتمال ضربه زدن به سرور کمک می‌کند. مقدار random_number_milliseconds باید بعد از هر انتظار دوباره تعریف شود.

الگوریتم تنظیم شده است تا زمانی که n 5 باشد خاتمه یابد. این سقف مانع از تلاش مجدد مشتریان برای بی نهایت می شود و منجر به تأخیر کلی در حدود 32 ثانیه قبل از اینکه یک درخواست "خطایی غیرقابل جبران" تلقی شود، می شود. حداکثر تعداد بیشتری از تلاش های مجدد خوب است، به خصوص اگر یک آپلود طولانی در حال انجام باشد. فقط مطمئن شوید که تاخیر تلاش مجدد را در چیزی معقول، مثلاً کمتر از یک دقیقه محدود کنید.

راهنمای کتابخانه مشتری API

• دات نت

• جاوا

• PHP

• پایتون

• روبی