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

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

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

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

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

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

לכל חלק בבקשת ה-multipart צריך להוסיף כותרת 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 של ה-method‏ /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 משיב עם קוד סטטוס 200 OK של HTTP. בנוסף, היא מספקת כותרת 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. ממתינים שנייה אחת + מספר אקראי של אלפיות השנייה ומנסים לשלוח שוב את הבקשה.
  4. מקבלים תגובה HTTP 503, שמציינת שצריך לנסות שוב לשלוח את הבקשה.
  5. ממתינים 2 שניות + מספר אקראי של אלפיות השנייה, ואז מנסים לשלוח שוב את הבקשה.
  6. מקבלים תגובה HTTP 503, שמציינת שצריך לנסות שוב לשלוח את הבקשה.
  7. ממתינים 4 שניות + מספר אקראי של אלפיות השנייה, ואז מנסים לשלוח שוב את הבקשה.
  8. מקבלים תגובה HTTP 503, שמציינת שצריך לנסות שוב לשלוח את הבקשה.
  9. ממתינים 8 שניות + מספר אקראי של אלפיות השנייה, ומנסים לשלוח שוב את הבקשה.
  10. מקבלים תגובה HTTP 503, שמציינת שצריך לנסות שוב לשלוח את הבקשה.
  11. ממתינים 16 שניות + מספר אקראי של אלפיות השנייה, ומנסים לשלוח שוב את הבקשה.
  12. תפסיק. דיווח על שגיאה או רישום שלה ביומן.

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

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

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

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