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

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

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

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

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

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

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

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

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

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

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

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

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

בהפניה ל-Publishing 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--

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

  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 של מדיה שמתקבלים ומגבלות הגודל של קבצים שמועלים לכל שיטה.

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

בדוגמה הבאה מוצג איך מתחילים סשן שאפשר להמשיך אותו ב-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 משיב עם קוד סטטוס 200 OK של HTTP. בנוסף, היא מספקת כותרת 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 שמציינת שהמיקום הנוכחי בקובץ לא ידוע. לדוגמה, אם האורך הכולל של הקובץ הוא 2,000,000, צריך להגדיר את הערך של Content-Range ל-*/2000000. אם לא יודעים מה הגודל המלא של הקובץ, מגדירים את 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 הבייטים הראשונים של הקובץ. משתמשים בערך העליון של הכותרת 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 כלשהי כשממשיכים או מנסים שוב להעלות בקשות, צריך להשתמש באסטרטגיית השהיה מעריכית לפני ניסיון חוזר. השגיאות האלה יכולות להתרחש אם יש עומס יתר על השרת. השהיה אקספוננציאלית יכולה לעזור להקל על בעיות כאלה בתקופות של נפח גדול של בקשות או עומס תנועה ברשת.

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

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

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

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

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

תהליך ההטמעה של השהיה מעריכית פשוטה לפני ניסיון חוזר הוא כדלקמן:

  1. שולחים בקשה ל-API.
  2. מקבלים תגובה HTTP 503, שמציינת שצריך לנסות שוב לשלוח את הבקשה.
  3. ממתינים שנייה אחת + מספר אקראי של אלפיות השנייה ומנסים לשלוח שוב את הבקשה.
  4. מקבלים תגובה HTTP 503, שמציינת שצריך לנסות שוב לשלוח את הבקשה.
  5. ממתינים 2 שניות + מספר אקראי של אלפיות השנייה, ואז מנסים לשלוח שוב את הבקשה.
  6. מקבלים תגובה HTTP 503, שמציינת שצריך לנסות שוב לשלוח את הבקשה.
  7. ממתינים 4 שניות + מספר אקראי של אלפיות השנייה, ואז מנסים לשלוח שוב את הבקשה.
  8. מקבלים את קוד השגיאה HTTP 503 response, שמציין שכדאי לנסות שוב לשלוח את הבקשה.
  9. ממתינים 8 שניות + מספר אקראי של אלפיות השנייה, ומנסים לשלוח שוב את הבקשה.
  10. מקבלים את קוד השגיאה HTTP 503 response, שמציין שכדאי לנסות שוב לשלוח את הבקשה.
  11. ממתינים 16 שניות + מספר אקראי של אלפיות השנייה, ומנסים לשלוח שוב את הבקשה.
  12. תפסיק. דיווח על שגיאה או רישום שלה ביומן.

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

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

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