העלאת תמונות

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

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

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

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

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

הערה: כדי ליצור או לעדכן את החלק של המטא-נתונים בלבד, מבלי להעלות את הנתונים המשויכים, צריך פשוט לשלוח בקשת POST או PUT לנקודת הקצה הרגילה של המשאב: https://www.googleapis.com/games/v1configuration/images/resourceId/imageType/imageType

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

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

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

הערה: התוקף של ה-URI של ההעלאה פג לאחר שבוע.

שלב 1: התחלת סשן שניתן להמשיך

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

בחומר העזר בנושא API של ה-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
}

הערה: בבקשת עדכון ראשונית שניתן להמשיך ללא מטא-נתונים, צריך להשאיר את גוף הבקשה ריק ולהגדיר את הכותרת Content-Length ל-0.

בקטע הבא מוסבר איך לטפל בתשובה.

שלב 2: שומרים את ה-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 של הסשן כדי להשתמש בו לבקשות הבאות.

שלב 3: העלאת הקובץ

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

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

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

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

הערה: אם ההעלאה הושלמה, יכול להיות שהסטטוס של התגובה יהיה 201 Created או 200 OK. מצב זה עשוי להתרחש אם החיבור התנתק אחרי שכל הבייטים הועלו אבל לפני שהלקוח קיבל תגובה מהשרת.

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
  • צריך להשתמש באסטרטגיית השהיה מעריכית לפני ניסיון חוזר (exponential backoff) אם מוחזרת שגיאת שרת 5xx כשמממשים בקשות העלאה או מנסים שוב אותן. השגיאות האלה יכולות להתרחש אם יש עומס יתר בשרת. השהיה מעריכית לפני ניסיון חוזר (exponential backoff) יכולה לעזור לפתור בעיות כאלה במהלך תקופות של נפח גבוה של בקשות או תנועה כבדה ברשת.
  • לא צריך לטפל בסוגים אחרים של בקשות על ידי השהיה מעריכית לפני ניסיון חוזר (exponential backoff), אבל עדיין אפשר לנסות מספר מהן. כשמבצעים ניסיון חוזר של הבקשות האלה, צריך להגביל את מספר הניסיונות החוזרים שלהן. לדוגמה, הקוד יכול להגביל לעשרה ניסיונות חוזרים או פחות לפני דיווח על שגיאה.
  • כדי לטפל בשגיאות 404 Not Found ו-410 Gone, כשמבצעים העלאות שניתן להמשיך, צריך להתחיל את ההעלאה כולה מההתחלה.

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

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

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

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

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

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

הערה: ההמתנה היא תמיד (2 ^ n) +TRUE_number_milliseconds, כאשר n הוא מספר שלם מונוטוני שגדל בהתחלה כ-0. המספר השלם n גדל ב-1 לכל איטרציה (כל בקשה).

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

מדריכים בנושא ספריות לקוח ל-API