העלאת תמונות באמצעות Play Games Services Publishing API

ה-API לפרסום של Play Games Services מאפשר לכם להעלות תמונה של משאב במשחק.

האפשרויות להעלאה

ה-API לפרסום של Play Games Services מאפשר לכם להעלות סוגים מסוימים של נתונים בינאריים או מדיה. המאפיינים הספציפיים של הנתונים שאפשר להעלות מפורטים בדף העזרה של כל שיטה שתומכת בהעלאות מדיה:

  • גודל הקובץ המקסימלי להעלאה: כמות הנתונים המקסימלית שאפשר לאחסן בשיטה הזו.

  • סוגי ה-MIME המותרים של מדיה: סוגי הנתונים הבינאריים שאפשר לאחסן באמצעות השיטה הזו.

אפשר לשלוח בקשות העלאה בכל אחת מהדרכים הבאות. מציינים את השיטה שבה משתמשים באמצעות פרמטר הבקשה uploadType.

  • העלאה פשוטה: uploadType=media. להעברה מהירה של קבצים קטנים, למשל קבצים בגודל 5MB או פחות.

  • העלאה בכמה חלקים: uploadType=multipart. להעברה מהירה של קבצים קטנים ומטא-נתונים. הבקשה כוללת את הקובץ ואת המטא-נתונים שמתארים אותו.

  • העלאה שניתן להמשיך: uploadType=resumable. להעברה אמינה, במיוחד בקבצים גדולים. בשיטה הזו משתמשים בבקשה להתחלת סשן, שאפשר לכלול בה מטא-נתונים. זוהי אסטרטגיה טובה לרוב האפליקציות, כי היא עובדת גם לקבצים קטנים יותר בעלות של בקשת HTTP אחת נוספת לכל העלאה.

כשאתם מעלים מדיה, אתם משתמשים ב-URI מיוחד. למעשה, לשיטות שתומכות בהעלאות מדיה יש שתי נקודות קצה של URI:

  • ה-URI של ‎ /upload, עבור המדיה. הפורמט של נקודת הקצה להעלאה הוא מזהה ה-URI הרגיל של המשאב עם הקידומת ‎/upload. משתמשים ב-URI הזה כשמעבירים את נתוני המדיה עצמם.

    דוגמה: POST /upload/games/v1configuration/images/resourceId/imageType/imageType

  • מזהה המשאב האחיד (URI) הרגיל של המטא-נתונים. אם המשאב מכיל שדות נתונים, השדות האלה משמשים לאחסון מטא-נתונים שמתארים את הקובץ שהועלו. אפשר להשתמש ב-URI הזה כשיוצרים או מעדכנים ערכים של מטא-נתונים.

    דוגמה: POST /games/v1configuration/images/resourceId/imageType/imageType

העלאה פשוטה

השיטה הפשוטה ביותר להעלאת קובץ היא לשלוח בקשת העלאה פשוטה. האפשרות הזו מתאימה במקרים הבאים:

  • הקובץ קטן מספיק ואפשר להעלות אותו שוב בשלמותו אם החיבור נכשל.

  • אין מטא-נתונים לשלוח. המצב הזה יכול לקרות אם אתם מתכננים לשלוח את המטא-נתונים של המשאב הזה בבקשה נפרדת, או אם אין מטא-נתונים נתמכים או זמינים. כדי להשתמש בהעלאה פשוטה, שולחים בקשת POST או PUT לכתובת ה-URI ‎/upload של השיטה ומוסיפים את פרמטר השאילתה uploadType=media. לדוגמה:

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

כותרות ה-HTTP שצריך להשתמש בהן כששולחים בקשת העלאה פשוטה כוללות:

  • Content-Type. מגדירים את השדה לאחד מסוגי נתוני המדיה המותרים להעלאה בשיטה, כפי שמפורט בחומר העזרה של Publishing 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

אם הבקשה תתבצע בהצלחה, השרת יחזיר את קוד הסטטוס 200 OK של HTTP יחד עם המטא-נתונים. לדוגמה:

HTTP/1.1 200
Content-Type: application/json

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

העלאה מרובת חלקים

אם יש לכם מטא-נתונים שאתם רוצים לשלוח יחד עם הנתונים להעלאה, תוכלו לשלוח בקשה יחידה של multipart/related. האפשרות הזו מתאימה אם הנתונים שאתם שולחים קטנים מספיק ואפשר להעלות אותם שוב בשלמותם אם החיבור נכשל.

כדי להשתמש בהעלאה של חלקים מרובים, שולחים בקשה מסוג POST או PUT למזהה ה-URI /upload של השיטה, ומוסיפים את פרמטר השאילתה uploadType=multipart. לדוגמה:

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

אלה כותרות ה-HTTP ברמה העליונה שצריך להשתמש בהן כששולחים בקשת העלאה של חלקים מרובים:

-Content-Type. מגדירים את הערך multipart/related וכוללים את מחרוזת הגבול שבה משתמשים כדי לזהות את החלקים של הבקשה.

-Content-Length. מוגדר למספר הכולל של הבייטים בגוף הבקשה. החלק של המדיה בבקשה חייב להיות קטן מגודל הקובץ המקסימלי שצוין לשיטה הזו.

גוף הבקשה בפורמט של סוג תוכן מרוכב/קשור RFC2387, ומכיל בדיוק שני חלקים. החלקים מזוהים באמצעות מחרוזת גבול, ומחרוזת הגבול האחרונה מופיעה אחרי שני מקפים.

לכל חלק בבקשה שמכילה כמה חלקים צריכה להיות כותרת נוספת מסוג Content-Type:

  • חלק המטא-נתונים: חייב להופיע קודם, ו-Content-Type חייב להתאים לאחד מהפורמטים המותרים של מטא-נתונים.

  • חלק המדיה: חייב להופיע בשני, ו-Content-Type חייב להתאים לאחד מסוגי ה-MIME המותרים של המדיה של השיטה.

בחומר העזר של Publishing API מפורטת רשימת סוגי ה-MIME של מדיה קבילים לכל שיטה, ומגבלות הגודל של קבצים שהועלו.

דוגמה: העלאה מרובת חלקים

בדוגמה הבאה מוצגת בקשה להעלאה מרובת חלקים ל-API לפרסום של Play Games Services.

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

אם הבקשה תתבצע בהצלחה, השרת יחזיר את קוד הסטטוס 200 OK של HTTP יחד עם המטא-נתונים:

HTTP/1.1 200
Content-Type: application/json

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

העלאה שניתן להמשיך

כדי להעלות קבצים של נתונים בצורה מהימנה יותר, אפשר להשתמש בפרוטוקול ההעלאה שניתן להמשיך אותה. הפרוטוקול הזה מאפשר להמשיך את פעולת ההעלאה אחרי שכשל בתקשורת מפריע לזרימת הנתונים. התכונה הזו שימושית במיוחד אם מעבירים קבצים גדולים והסיכוי להפרעה ברשת או לכשלים אחרים בהעברה גבוה, למשל כשמעלים מאפליקציית לקוח לנייד. היא גם יכולה לצמצם את השימוש ברוחב הפס במקרה של כשלים ברשת, כי אין צורך להתחיל מחדש את ההעלאה של קבצים גדולים.

השלבים לשימוש בהעלאה שניתן להמשיך אותה כוללים:

  1. מתחילים סשן שניתן להמשיך. שולחים בקשה ראשונית למזהה ה-URI של ההעלאה, שכוללת את המטא-נתונים, אם יש כאלה.

  2. שומרים את ה-URI של הסשן שניתן להמשיך. שומרים את ה-URI של הסשן שמוחזר בתשובה לבקשה הראשונית. ה-URI הזה ישמש אתכם לבקשות שנותרו בסשן הזה. מעלים את הקובץ.

  3. שולחים את קובץ המדיה ל-URI של הסשן שניתן להמשיך.

בנוסף, באפליקציות שמשתמשות בהעלאה שניתן להמשיך אותה צריך להיות קוד להמשך העלאה שהופסק. אם ההעלאה מופסקת, צריך לבדוק כמה נתונים התקבלו בהצלחה ולהמשיך את ההעלאה מהנקודה הזו.

התחלת סשן שניתן להמשיך

כדי להתחיל העלאה שניתן להמשיך, שולחים בקשה מסוג POST או PUT למזהה ה-URI /upload של השיטה ומוסיפים את פרמטר השאילתה 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. מוגדר למספר הבייטים שצוין בגוף הבקשה הראשונית. זה לא נדרש אם משתמשים בקידוד העברה במקטעים.

במאמר העזרה של Publishing API מפורטת רשימת סוגי ה-MIME של מדיה קבילים לכל שיטה, ומגבלות הגודל של קבצים שהועלו.

דוגמה: בקשה להתחלת סשן שניתן להמשיך

בדוגמה הבאה מוסבר איך מתחילים סשן שניתן להמשיך אותו ב-API לפרסום של שירותי המשחקים של Play.

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, שמוצגת בדוגמה הבאה, כוללת חלק של פרמטר השאילתה 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 אחרת, פועלים לפי השלבים שמפורטים בקטע המשך של העלאה שהופסקה.

העלאת הקובץ בחלקים

כשמשתמשים בהעלאות שניתן להמשיך, אפשר לפצל קובץ למקטעים ולשלוח סדרה של בקשות להעלאת כל מקטע ברצף. זו לא הגישה המועדפת, כי יש עלויות ביצועים שמשויכות לבקשות הנוספות, ובדרך כלל אין צורך בכך. עם זאת, יכול להיות שתצטרכו להשתמש בחלוקה למקטעים כדי לצמצם את כמות הנתונים שמועברת בבקשה אחת. האפשרות הזו שימושית כשיש מגבלה זמן קבועה לבקשות ספציפיות, כמו בחלק מהבקשות של Google App Engine. הוא גם מאפשר לכם לבצע פעולות כמו לספק אינדיקציות של התקדמות ההעלאה בדפדפנים מדור קודם שלא תומכים בהצגת התקדמות ההעלאה כברירת מחדל.

אם מעלים את הנתונים בחלקים, צריך גם את הכותרת Content-Range, יחד עם הכותרת Content-Length שנדרשת להעלאות של קבצים מלאים:

  • Content-Length. מגדירים את גודל הקטע או גודל קטן יותר, כפי שעשוי להיות במקרה של הבקשה האחרונה.

  • Content-Range. מגדירים את האפשרות הזו כדי להציג אילו ביטים בקובץ שאתם מעלים. לדוגמה, הערך Content-Range: bytes 0-524287/2000000 מציין שאתם מספקים את 524,288 הבייטים הראשונים (256 x 1024 x 2) בקובץ של 2,000,000 בייטים.

המשך העלאה שהופסקה

אם בקשת העלאה הופסקה לפני קבלת תשובה, או אם מקבלים תשובה מסוג HTTP 503 Service Unavailable מהשרת, צריך להמשיך את ההעלאה שהופסקה. כדי להמשיך העלאה שהופסקה:

  1. סטטוס הבקשה. כדי לבדוק את הסטטוס הנוכחי של ההעלאה, שולחים בקשת PUT ריקה למזהה ה-URI של ההעלאה. בבקשה הזו, כותרות ה-HTTP צריכות לכלול כותרת Content-Range שמציינת שהמיקום הנוכחי בקובץ לא ידוע. לדוגמה, מגדירים את Content-Range כ-*/2000000 אם אורך הקובץ הכולל הוא 2,000,000. אם לא יודעים מה הגודל המלא של הקובץ, צריך להגדיר את Content-Range לערך */*.

  2. אחזור מספר הבייטים שהועלו עיבוד התגובה משאילתת הסטטוס. השרת משתמש בכותרת Range בתגובה שלו כדי לציין אילו בייטים הוא קיבל עד עכשיו. לדוגמה, כותרת Range של 0-299999 מציינת שה-300,000 הבייטים הראשונים של הקובץ התקבלו.

  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 הבייטים הראשונים של הקובץ. משתמשים בערך העליון של כותרת הטווח כדי לקבוע מאיפה להתחיל את ההעלאה המחודשת.

    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 כשממשיכים או מנסים שוב לבצע בקשות העלאה, מומלץ להשתמש באסטרטגיית השהיה מעריכית לפני ניסיון חוזר. השגיאות האלה יכולות להתרחש אם יש עומס יתר על השרת. השהיה מעריכית יכולה לעזור לצמצם את הבעיות האלה בתקופות של נפח גבוה של בקשות או תנועה כבדה ברשת.

  • לא מומלץ להשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) לטיפול בבקשות מסוגים אחרים, אבל עדיין אפשר לנסות שוב כמה מהן. כשמנסים שוב את הבקשות האלה, כדאי להגביל את מספר הניסיונות החוזרים. לדוגמה, הקוד יכול להגביל את מספר הניסיונות החוזרים ל-10 או פחות לפני שמדווחים על שגיאה.

  • כדי לטפל בשגיאות 404 Not Found ו-410 Gone כשמבצעים העלאות שניתן להמשיך, צריך להתחיל את כל ההעלאה מחדש מההתחלה.

השהיה מעריכית לפני ניסיון חוזר (exponential backoff)

השהיה מעריכית לפני ניסיון חוזר היא אסטרטגיה סטנדרטית לטיפול בשגיאות באפליקציות רשת, שבה הלקוח מנסה שוב ושוב לשלוח בקשה שנכשלה לאורך פרק זמן הולך וגדל. אם נפח גדול של בקשות או תנועה כבדה ברשת גורמים לשרת להחזיר שגיאות, השהיה מעריכית לפני ניסיון חוזר (exponential backoff) עשויה להיות אסטרטגיה טובה לטיפול בשגיאות האלה. לעומת זאת, זו לא אסטרטגיה רלוונטית לטיפול בשגיאות שלא קשורות לנפח התנועה ברשת או לזמני התגובה, כמו פרטי כניסה לא חוקיים או שגיאות מסוג 'הקובץ לא נמצא'.

כשמשתמשים בהשהיה מעריכית לפני ניסיון חוזר בצורה נכונה, היא מגדילה את היעילות של השימוש ברוחב הפס, מפחיתה את מספר הבקשות הנדרשות כדי לקבל תשובה מוצלחת וממקסמת את תפוקת הבקשות בסביבות בו-זמניות.

התהליך להטמעת השהיה מעריכית פשוטה לפני ניסיון חוזר (exponential backoff) הוא:

  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. ממתינים 8 שניות + random_number_milliseconds ומנסים שוב את הבקשה.
  10. מקבלים קוד HTTP 503 response, שמציין שצריך לנסות שוב את הבקשה.
  11. ממתינים 16 שניות + random_number_milliseconds ומנסים שוב את הבקשה.
  12. הפסקת ההפעלה. דיווח על שגיאה או רישום שלה ביומן.

ברשימה שלמעלה, הערך של random_number_milliseconds הוא מספר אקראי של אלפיות שנייה שקטן מ-1,000 או שווה לו. הדבר נחוץ כי הוספת עיכוב אקראי קטן עוזרת לחלק את העומס בצורה שווה יותר ומונעת את האפשרות של התקפת רמזור (stampede) על השרת. צריך להגדיר מחדש את הערך של random_number_milliseconds אחרי כל המתנה.

האלגוריתם מוגדר להסתיים כאשר n הוא 5. המכסה הזו מונעת מהלקוחות לנסות שוב ושוב, וכתוצאה מכך מתרחשת השהיה כוללת של כ-32 שניות לפני שהבקשה נחשבת "לשגיאה שלא ניתן לשחזור". אפשר להגדיר מספר מקסימלי גדול יותר של ניסיונות חוזרים, במיוחד אם מתבצע העלאה ארוכה. רק חשוב לוודא שהזמן שלפני הניסיון החוזר לא יהיה ארוך מדי, למשל פחות מדקה.

מדריכים לספריות לקוח של API