יצירת חבילה

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

ה-Android Over The Air API מאפשר להעלות נתוני חבילה כדי ליצור משאב Package חדש. אלו חבילות OTA שאפשר לשייך להגדרה אחת או יותר כדי שהעדכון יועבר למכשירים.

אנחנו מספקים קובץ בינארי ל-Linux ול-Windows כדי לאפשר העלאת חבילות שניתנת לחידוש, שהשימוש בה מותר לך במקום הפרוטוקולים המתוארים בהמשך. אם רוצים להעמיק את השילוב, אפשר להשתמש באחד מהפרוטוקולים שמתוארים בהמשך.

Linux

הורדת האפליקציה של מעלה התוכן Android Over The Air API v1 ל-Linux.

Windows

הורדת האפליקציה Android Over The Air API v1 שמעלה ל-Windows.

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

פרוטוקולי העלאה

אפשר לשלוח בקשות העלאה בכל אחת מהדרכים הבאות. צריך לציין את השיטה שבה משתמשים בכותרת הבקשה X-Goog-Upload-Protocol.

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

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

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

כדי להשתמש בהעלאה מרובת חלקים, צריך לשלוח בקשת POST ל-URI של /upload/package ולהגדיר את X-Goog-Upload-Protocol ל-multipart.

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

  • Content-Type. צריך להגדיר כמספר חלקים/קשור ולכלול את מחרוזת הגבולות שמשמשת לזיהוי חלקי הבקשה.
  • Content-Length. הגדרה למספר הבייטים הכולל בגוף הבקשה.

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

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

  1. חלק מהמטא-נתונים: צריך להופיע ראשון, ו-Content-Type צריך להיות application/json.
  2. חלק המדיה: צריך להיות שני, ו-Content-Type חייב להיות application/zip.

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

בדוגמה הבאה מוצגת בקשה להעלאה מרובת חלקים ל-Android Over The Air API.

POST /upload/package HTTP/1.1
Host: androidovertheair.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=BOUNDARY
Content-Length: number_of_bytes_in_entire_request_body

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

{"deployment": "id", "package_title": "title" }
--BOUNDARY
Content-Type: application/zip; charset=UTF-8

Package ZIP
--BOUNDARY--

אם הבקשה מצליחה, השרת מחזיר את קוד המצב 200 OK של HTTP

HTTP/1.1 200

דרך לעשות זאת בקלות היא להשתמש ב-curl וב-oauth2l. בהמשך מופיעה בקשה לדוגמה, שמתבססת על ההנחה שאתם משתמשים במפתח שירות (למידע נוסף, כדאי לעיין בהרשאה שלנו).

בקשת curl לדוגמה 
    JSON={"deployment": "id", "package_title": "title" }
    SERVICE_KEY_FILE=path to your service key json file
    curl \
    -H "$(./oauth2l header --json $SERVICE_KEY_FILE android_partner_over_the_air)" \
    -H "Host: androidovertheair.googleapis.com" \
    -H "X-Goog-Upload-Protocol: multipart" \
    -H "Content-Type: multipart/form-data" \
    -F "json=$JSON;type=application/json" \
    -F "data=@update.zip;type=application/zip" \
    androidovertheair.googleapis.com/upload/package

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

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

פרוטוקול ההעלאה שניתנת לחידוש משתמש בכמה פקודות:

  1. התחלת סשן שניתן להמשיך סשן. שליחת בקשה ראשונית ל-URI להעלאה שכוללת את המטא-נתונים ויוצרת מיקום העלאה ייחודי שניתן להמשיך אותו.
  2. שומרים את ה-URI של סשן שניתן להמשיך אותו. יש לשמור את ה-URI של הסשן שהוחזר בתגובה לבקשה הראשונית. הוא ישמש אותך לשאר הבקשות בסשן הזה.
  3. מעלים את הקובץ. שולחים את כל קובץ ה-ZIP או חלק ממנו ל-URI של הסשן שניתן להמשיך אותו.

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

הערה: תוקף ה-URI להעלאה פג לאחר 3 ימים.

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

כדי להתחיל בהעלאה שניתנת לחידוש, צריך לשלוח בקשת POST ל-URI של /upload/package ולהגדיר את הערך X-Goog-Upload-Protocol ל-resumable.

בבקשה יזומה הזו, גוף הקובץ חייב להכיל רק את המטא-נתונים. התוכן האמיתי של הקובץ ישמש אותך בבקשות הבאות.

השתמש בכותרות ה-HTTP הבאות עם הבקשה הראשונית:

  • X-Goog-Upload-Header-Content-Type. זהו סוג התוכן של הקובץ שמועלה, וצריך להגדיר אותו ל-application/zip.
  • X-Goog-Upload-Command. מוגדר ל-start
  • X-Goog-Upload-Header-Content-Length. מוגדר למספר הבייטים של נתוני ההעלאה שיועברו בבקשות הבאות. אם אורך הכותרת לא ידוע במועד הבקשה, אפשר להשמיט את הכותרת.
  • Content-Type. זהו סוג התוכן של המטא-נתונים וצריך להגדיר אותו ל-application/json.
  • Content-Length. מגדירים את מספר הבייטים בגוף הבקשה הראשונית.
דוגמה: בקשת התחלת סשן ניתנת לחידוש

הדוגמה הבאה מראה איך להתחיל סשן שניתן להמשיך להשתמש ב-Android Over The Air API.

POST /upload/package HTTP/1.1
Host: android/over-the-air.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Goog-Upload-Command: start
X-Goog-Upload-Header-Content-Type: application/zip
X-Goog-Upload-Header-Content-Length: 2000000

{"deployment": "id", "package_title": "title" }

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

שלב 2: שומרים את ה-URI של הסשן שניתן להמשיך

אם בקשת התחלת הסשן מצליחה, שרת ה-API מגיב עם קוד סטטוס HTTP 200 OK. בנוסף, היא מספקת כותרת X-Goog-Upload-URL שמציינת את ה-URI של הסשן שניתן להמשיך. הכותרת X-Goog-Upload-URL, שמוצגת בדוגמה למטה, כוללת חלק של פרמטר שאילתה upload_id שמספק את מזהה ההעלאה הייחודי לשימוש בסשן הזה. התגובה מכילה גם כותרת X-Goog-Upload-Status, שתהיה active אם בקשת ההעלאה אושרה ואושרה. הסטטוס הזה עשוי להיות final אם ההעלאה נדחתה.

דוגמה: תגובה של התחלת סשן מתחדשת

זו התגובה לבקשה בשלב 1:

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-URL: androidovertheair.googleapis.com/?upload_id=xa298sd_sdlkj2
Content-Length: 0

הערך של הכותרת X-Goog-Upload-URL, כפי שמוצג בתגובה לדוגמה שלמעלה, הוא ה-URI של הסשן שבו תשתמשו כנקודת הקצה של HTTP לצורך העלאת הקובץ בפועל או שליחת שאילתות לגבי סטטוס ההעלאה.

מעתיקים את ה-URI של הסשן ושומרים אותו כדי שתוכלו להשתמש בו בבקשות הבאות.

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

כדי להעלות את הקובץ, צריך לשלוח בקשת POST ל-URI להעלאה שקיבלת בשלב הקודם. הפורמט של בקשת ההעלאה הוא:

POST session_uri

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

  1. Content-Length. יש להגדיר ערך זה למספר הבייטים שמעלים בבקשה הזו, שהוא בדרך כלל גודל הקובץ להעלאה.
  2. X-Goog-Upload-Command. מגדירים את הערך upload ואת הערך finalize.
  3. X-Goog-Upload-Offset. צוין הקיזוז שבו יש לכתוב בייטים. חשוב לזכור שהלקוחות חייבים להעלות בייטים בכל פעם.
דוגמה: בקשה להעלאת קובץ שניתן להמשיך

זוהי בקשה שניתן להמשיך ולהעלות את קובץ ה-ZIP המלא בגודל 2,000,000 בייטים בדוגמה הנוכחית.

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0
Content-Length: 2000000
Content-Type: application/zip

bytes 0-1999999

אם הבקשה מצליחה, השרת מגיב באמצעות HTTP 200 Ok.

אם בקשת ההעלאה הופסקה או אם קיבלת תגובת HTTP 503 Service Unavailable או תגובת 5xx אחרת מהשרת, עליך לפעול לפי ההוראות שמפורטות במאמר המשך העלאה של הפרעה.

העלאת הקובץ במקטעים

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

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

המשך העלאה שנקטעה

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

  1. סטטוס הבקשה. מבררים מה הסטטוס הנוכחי של ההעלאה, על ידי שליחת בקשה ל-URI להעלאה שבו X-Goog-Upload-Command מוגדר ל-query.

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

  2. קבלת מספר הבייטים שהועלו. לעבד את התגובה משאילתת הסטטוס. השרת משתמש בכותרת X-Goog-Upload-Size-Received בתגובה שלו כדי לציין כמה בייטים הוא קיבל עד כה.
  3. העלאת הנתונים שנותרו. לסיום, אחרי שהבנתם לאן להמשיך את הבקשה, אפשר לשלוח את שאר הנתונים או את קבוצת הנתונים הנוכחית. חשוב לזכור שצריך להתייחס לנתונים שנותרו כמקטע נפרד בכל מקרה, ולכן צריך להגדיר את הכותרת X-Goog-Upload-Offset לקיזוז המתאים כשההעלאה ממשיכה.
דוגמה: המשך העלאה של סרטון שנקטע

1) מבקשים את סטטוס ההעלאה.

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Command: query

כמו בכל הפקודות, הלקוח חייב לבדוק את הכותרת X-Goog-Upload-Status בתגובת ה-HTTP של פקודת שאילתה. אם הכותרת קיימת והערך אינו active, ההעלאה כבר הסתיימה.

2) מחלצים את מספר הבייטים שהועלו עד עכשיו מהתגובה.

בתגובת השרת, נעשה שימוש בכותרת X-Goog-Upload-Size-Received כדי לציין שהוא קיבל עד כה את 43 הבייטים הראשונים של הקובץ.

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 42

3) המשך את ההעלאה מהנקודה שבה הופסקה.

הבקשה הבאה ממשיכה את ההעלאה על ידי שליחת הבייטים שנותרו בקובץ, החל מבייט 43.

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Command: upload, finalize
Content-Length: 1999957
X-Goog-Upload-Offset: 43

bytes 43-1999999

שיטות מומלצות

כשמעלים מדיה, כדאי להכיר כמה שיטות מומלצות לטיפול בשגיאות.

  • להמשיך או לנסות שוב העלאות שנכשלו עקב הפרעות בחיבור או שגיאות מסוג 5xx, כולל:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • יש להשתמש באסטרטגיה של השהיה מעריכית לפני ניסיון חוזר אם מוחזרת שגיאת שרת כלשהי מסוג 5xx במהלך המשך או ניסיון חוזר של בקשות העלאה. השגיאות האלה יכולות להתרחש כשהשרת עמוס. השהיה מעריכית יכולה לפתור בעיות מהסוג הזה בתקופות של נפח גדול של בקשות או עומס תנועה כבד ברשת.
  • לא כדאי לטפל בסוגים אחרים של בקשות באמצעות השהיה מעריכית לפני ניסיון חוזר (backoff), אבל עדיין אפשר לנסות שוב ושוב למספר קטן של בקשות. כשאתה מנסה שוב את הבקשות האלה, עליך להגביל את מספר הפעמים שמנסים שוב לבצע אותן. לדוגמה, ייתכן שהקוד שלכם מוגבל ל-10 ניסיונות חוזרים לפני דיווח על שגיאה.
  • צריך לטפל בשגיאות 404 Not Found כשמבצעים העלאות שניתנות לחידוש על ידי התחלת ההעלאה כולה.

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

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

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

כך מטמיעים השהיה מעריכית פשוטה:

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

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

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

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