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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. שולחים בקשה ל-API.
  2. מקבלים תגובה מסוג HTTP 503, שמציינת שצריך לנסות שוב את הבקשה.
  3. ממתינים 1 שנייה + 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