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

גוף הבקשה מעוצב כסוג תוכן multipart/related ‏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--

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

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

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

  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