המדיה שהעלית

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

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

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

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

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

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

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

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

• ה-URI של ‎/upload, עבור המדיה. הפורמט של נקודת הקצה להעלאה הוא ב-URI של משאב סטנדרטי עם הקידומת ' /upload'. משתמשים ב-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. מגדירים את מספר הבייטים שמעלים. זה לא נדרש אם משתמשים בקידוד העברה במקטעים.

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

הדוגמה הבאה מציגה שימוש בבקשת העלאה פשוטה בשביל ה-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 של מדיה קבילים ומגבלות הגודל של קבצים שהועלו לכל שיטה.

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

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

בדוגמה הבאה מוצגת בקשה להעלאה מרובת חלקים ל-Farm 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 OK HTTP יחד עם כל המטא-נתונים:

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 של מדיה קבילים לכל שיטה, ומגבלות הגודל של קבצים שהועלו.

דוגמה: בקשה להתחלת סשן שניתן להמשיך

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

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

הרחבה לקבלת מידע נוסף

אם מעלים את הנתונים בחלקים, צריך גם את הכותרת Content-Range, יחד עם הכותרת Content-Length שנדרשת להעלאות של קובצים מלאים:

• Content-Length צריך להגדיר את גודל המקטע או יכול להיות קטן ממנו, כמו במקרה של הבקשה האחרונה.
• Content-Range: הגדרה זו מאפשרת להציג אילו בייטים בקובץ אתם מעלים. לדוגמה, Content-Range: bytes 0-524287/2000000 מראה שאתם מספקים את 524,288 הבייטים הראשונים (256 x 1,024 x 2) בקובץ בגודל 2,000,000 בייטים.

הגבלת גודל המקטע: כל המקטעים חייבים להיות כפולה של 256KB (256x1,024 בייטים), מלבד המקטע הסופי המשלים את ההעלאה. אם אתם משתמשים במקטע נתונים, חשוב להקפיד שגודל המקטע יהיה גדול ככל האפשר כדי שההעלאה תהיה יעילה.

דוגמה: בקשה להעלאת קובץ מקטעי נתונים שניתן להמשיך

בקשה ששולחת את 524,288 הבייטים הראשונים עשויה להיראות כך:

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: image/jpeg
Content-Range: bytes 0-524287/2000000

bytes 0-524288

אם הבקשה תתבצע בהצלחה, השרת ישיב עם 308 Resume Incomplete עם כותרת Range שמציינת את המספר הכולל של הבייטים שאוחסנו עד עכשיו:

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

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

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

הערות חשובות:

• יש להקפיד להשתמש בכותרת Range בתשובה כדי לקבוע מאיפה להתחיל את המקטע הבא. לא מניחים שהשרת קיבל את כל הבייטים שנשלחו בבקשה הקודמת.
• לכל URI להעלאה יש משך חיים מוגבל, ובסופו של דבר התוקף שלו יפוג (תוך יום בערך, אם לא נעשה בו שימוש). לכן מומלץ להתחיל העלאה שניתן להמשיך מיד לאחר קבלת ה-URI של ההעלאה, ולהמשיך בהעלאה שהופסקה זמן קצר לאחר ההפרעה.
• אם שולחים בקשה עם מזהה סשן העלאה שפג תוקפו, השרת מחזיר את קוד הסטטוס 404 Not Found. אם מתרחשת שגיאה שלא ניתן לשחזר אותה בסשן ההעלאה, השרת מחזיר את קוד המצב 410 Gone. במקרים כאלה, צריך להתחיל העלאה חדשה שניתן להמשיך, לקבל URI חדש להעלאה ולהתחיל את ההעלאה שניתן להמשיך מההתחלה עם נקודת הקצה החדשה.

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

---

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

אם בקשת העלאה הופסקה לפני קבלת תשובה, או אם מקבלים מהשרת תגובה מסוג 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

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

השהיה מעריכית לפני ניסיון חוזר (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 שניות + random_number_milliseconds ומנסים שוב את הבקשה.
8. מקבלים תגובה מסוג HTTP 503, שמציינת שצריך לנסות שוב את הבקשה.
9. צריך להמתין 8 שניות +Android_number_milliseconds, ולנסות שוב את הבקשה.
10. מקבלים את התשובה HTTP 503, שמצביעה על כך שצריך לנסות שוב את הבקשה.
11. צריך להמתין 16 שניות +Android_number_milliseconds, ולנסות שוב את הבקשה.
12. הפסקת ההפעלה. דיווח על שגיאה או רישום שלה ביומן.

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

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

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

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

• .NET
• Java
• PHP
• Python
• Ruby