המדיה שהעלית

התכונה 'העלאת מדיה' מאפשרת ל-Campaign Manager 360 API לאחסן נתונים בענן ולהפוך אותם לזמינים לשרת. סוגי הנתונים שכדאי להעלות כוללים תמונות, סרטונים, קובצי PDF, קובצי ZIP או כל סוג אחר של נתונים.

בדוגמאות שמופיעות במסמך הזה מוצג השימוש בהעלאות מדיה עבור API חקלאי בדיוני. עם זאת, אותם עקרונות רלוונטיים גם ל-Campaign Manager 360 API.

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

ה-API של Campaign Manager 360 מאפשר להעלות סוגים מסוימים של נתונים או קובצי מדיה בינאריים. המאפיינים הספציפיים של הנתונים שניתן להעלות מפורטים בדף העזר עבור כל שיטה שתומכת בהעלאות מדיה:

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

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

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

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

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

    לדוגמה: POST /upload/farm/v1/animals

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

    דוגמה: POST /farm/v1/animals

העלאה פשוטה

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

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

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

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=media

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

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

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

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

POST /upload/farm/v1/animals?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

{
  "name": "Llama"
}

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

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

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

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=multipart

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

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

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

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

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

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

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

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

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

POST /upload/farm/v1/animals?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

{
  "name": "Llama"
}

--foo_bar_baz
Content-Type: image/jpeg

JPEG data
--foo_bar_baz--

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

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

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

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

אלה השלבים לשימוש בהעלאה חוזרת:

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

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

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

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

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

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable

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

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

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

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

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

הדוגמה הבאה מראה איך ליזום סשן חוזר של ה-API הבדיוני ב-Essentials.

POST /upload/farm/v1/animals?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

{
  "name": "Llama"
}

הערה : לגבי בקשת עדכון ראשונית שניתן להמשיך ללא מטא-נתונים, משאירים את גוף הבקשה ריק ומגדירים את הכותרת 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/farm/v1/animals?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/farm/v1/animals?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) ממשיכים את ההעלאה מהנקודה שבה היא הופסקה.

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

השהיה מעריכית

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

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

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

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

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

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

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

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