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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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