מידע על העלאת מדיה

ממשק ה-API של Google Mirror מאפשר לך להוסיף קובץ מצורף בעת יצירת פריט ציר זמן חדש.

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

ה-Google Mirror API מאפשר לך להעלות סוגים מסוימים של נתונים בינאריים או פריטי מדיה. המאפיינים הספציפיים של הנתונים שניתן להעלות מצוינים בדף העזר לכל שיטה שתומכת בהעלאות מדיה:

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

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

  • העלאה פשוטה: uploadType=media. להעברה מהירה של קבצים קטנים יותר, למשל 5MB או פחות.
  • העלאה מרובת חלקים: uploadType=multipart. להעברה מהירה של קבצים קטנים יותר ומטא-נתונים; מעביר את הקובץ יחד עם מטא-נתונים שמתארים אותו – והכול בבקשה אחת.
  • העלאה מתחדשת: uploadType=resumable. להעברה אמינה, במיוחד כשמדובר בקבצים גדולים. בשיטה זו, אתה משתמש בבקשה ליזום פעילות באתר. אפשרות זו עשויה לכלול מטא נתונים. זוהי אסטרטגיה טובה לשימוש עבור רוב היישומים, מאחר שהיא פועלת גם עבור קבצים קטנים יותר בעלות בקשת HTTP אחת נוספת לכל העלאה.

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

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

    לדוגמה: POST /upload/mirror/v1/timeline

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

    דוגמה: POST /mirror/v1/timeline

העלאה פשוטה

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

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

כדי להשתמש בהעלאה פשוטה, צריך ליצור בקשת POST או PUT ל-URI של השיטה /upload ולהוסיף את פרמטר השאילתה uploadType=media. למשל:

POST https://www.googleapis.com/upload/mirror/v1/timeline?uploadType=media

כותרות HTTP שבהן יש להשתמש בעת בקשת העלאה פשוטה כוללות:

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

דוגמה: העלאה פשוטה

בדוגמה הבאה מוצג שימוש בבקשת העלאה פשוטה ל-Google Mirror API.

POST /upload/mirror/v1/timeline?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/jpeg
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

JPEG data

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

HTTP/1.1 200
Content-Type: application/json

{
  "text": "Hello world!"
}

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

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

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

POST https://www.googleapis.com/upload/mirror/v1/timeline?uploadType=multipart

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

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

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

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

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

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

הערה: כדי ליצור או לעדכן את החלק של המטא-נתונים בלבד, בלי להעלות את הנתונים המשויכים, פשוט שולחים בקשת POST או PUT לנקודת הקצה הרגילה של המשאב: https://www.googleapis.com/mirror/v1/timeline

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

הדוגמה הבאה מציגה בקשת העלאה מרובת חלקים עבור Google Mirror API.

POST /upload/mirror/v1/timeline?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

{
  "text": "Hello world!"
}

--foo_bar_baz
Content-Type: image/jpeg

JPEG data
--foo_bar_baz--

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

HTTP/1.1 200
Content-Type: application/json

{
  "text": "Hello world!"
}

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

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

השלבים לשימוש בהעלאה מתחדשת כוללים:

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

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

הערה: URI של העלאה יפוג לאחר שבוע.

שלב 1: התחלת סשן מתחדש

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

POST https://www.googleapis.com/upload/mirror/v1/timeline?uploadType=resumable

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

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

  • X-Upload-Content-Type. אפשר להגדיר את הסוג של ה-MIME של המדיה להעלאה בנתוני הבקשות הבאות.
  • X-Upload-Content-Length. עליך להגדיר את מספר הבייטים של נתוני העלאה שיועברו בבקשות הבאות. אם האורך לא ידוע בזמן הבקשה, אפשר להשמיט את הכותרת הזו.
  • אם מספקים מטא-נתונים: Content-Type. מגדירים את סוג הנתונים לפי המטא-נתונים.
  • Content-Length. יש להגדיר את המספר של הבייטים שסופקו בגוף הבקשה הראשונית. לא נדרש אם משתמשים בקידוד העברה מפוצל.

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

דוגמה: בקשה לחידוש הפעלה של סשן

הדוגמה הבאה מראה איך ליצור סשן מתחדש עבור Google Mirror API.

POST /upload/mirror/v1/timeline?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/jpeg
X-Upload-Content-Length: 2000000

{
  "text": "Hello world!"
}

הערה: אם מדובר בבקשה לעדכון ראשונית שניתן להמשיך ללא מטא-נתונים, יש להשאיר את גוף הבקשה ריק ולהגדיר את הכותרת 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/mirror/v1/timeline?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

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

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

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

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

PUT session_uri

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

דוגמה: בקשה להעלאת קובץ שניתנת לחידוש

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

PUT https://www.googleapis.com/upload/mirror/v1/timeline?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/jpeg

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

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

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

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

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

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

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

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

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

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