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

‫Gmail API מאפשר להעלות נתוני קבצים כשיוצרים או מעדכנים טיוטה, או כשמוסיפים או שולחים הודעה.

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

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

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

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

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

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

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

    לדוגמה: POST /upload/gmail/v1/users/userId/messages/send

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

    לדוגמה: POST /gmail/v1/users/userId/messages/send

העלאה פשוטה

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

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

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

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=media

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

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

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

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

POST /upload/gmail/v1/users/userId/messages/send?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: message/rfc822
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

Email Message data

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

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

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

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

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

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=multipart

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

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

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

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

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

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

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

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

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

POST /upload/gmail/v1/users/userId/messages/send?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

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

--foo_bar_baz
Content-Type: message/rfc822

Email Message data
--foo_bar_baz--

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

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

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

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

כדי להשתמש בהעלאה שניתן להמשיך:

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

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

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

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

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

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable

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

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

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

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

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

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

POST /upload/gmail/v1/users/userId/messages/send?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: message/rfc822
X-Upload-Content-Length: 2000000

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

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

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

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

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

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

PUT session_uri

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

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

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

PUT https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: message/rfc822

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

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

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

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

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

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

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

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

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

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