ביצוע העלאות שניתן להמשיך

סקירה כללית

הדף הזה מסביר איך ליצור בקשת העלאה שניתן להמשיך בממשקי ה-API בפורמט JSON ובפורמט XML ב-Cloud Storage. הפרוטוקול הזה מאפשר להמשיך את פעולת ההעלאה אחרי שכשל בתקשורת מפריע לזרימת הנתונים.

מידע על שימוש בהעלאות שניתן להמשיך ב-Google Cloud CLI ובספריות לקוח מופיע במאמר איך כלים וממשקי API משתמשים בהעלאות שניתן להמשיך.

ההרשאות הנדרשות

‫API בפורמט JSON

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

רשימת ההרשאות הנדרשות לפעולות ספציפיות מופיעה במאמר הרשאות IAM ל-methods של JSON.

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

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

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

‫API בפורמט JSON

מקבלים אסימון גישה להרשאה מ-OAuth 2.0 Playground. מגדירים את ה-Playground לשימוש בפרטי הכניסה שלכם ב-OAuth. הוראות מפורטות מופיעות במאמר אימות API.
אפשר גם ליצור קובץ JSON שמכיל את המטא-נתונים שרוצים להגדיר באובייקט שמעלים. לדוגמה, קובץ ה-JSON הבא מגדיר את המטא-נתונים contentType של האובייקט שרוצים להעלות ל-image/png:
```
{
    "contentType": "image/png"
}
```
משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת אובייקט POST:
```
curl -i -X POST --data-binary @METADATA_LOCATION \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Content-Length: INITIAL_REQUEST_LENGTH" \
    "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=resumable&name=OBJECT_NAME"
```
כאשר:
- ‫METADATA_LOCATION הוא הנתיב המקומי לקובץ JSON שמכיל את המטא-נתונים האופציונליים שצוינו בשלב הקודם. אם לא כוללים קובץ מטא-נתונים, צריך לא לכלול זאת, יחד עם --data-binary @ והכותרת Content-Type.
- ‫OAUTH2_TOKEN הוא אסימון הגישה שיצרתם בשלב 1.
- ‫INITIAL_REQUEST_LENGTH הוא מספר הבייטים בגוף הבקשה הראשונית, לדוגמה 79. זה לא נדרש אם משתמשים בקידוד העברה במקטעים.
- ‫BUCKET_NAME הוא שם הקטגוריה שאליה מעלים את האובייקט. לדוגמה, my-bucket.
- ‫OBJECT_NAME הוא השם שרוצים לתת לאובייקט, מותאם לקידודי התווים שמתאימים לכתובות URL. לדוגמה, pets/dog.png יותאם לקידודי התווים שמתאימים לכתובות URL באופן הבא: pets%2Fdog.png. לא חובה לעשות זאת אם כללתם name בקובץ המטא-נתונים של האובייקט בשלב 2.
אם הפעלתם שיתוף משאבים בין מקורות, צריך לכלול גם את הכותרת Origin בבקשות ההעלאה האלו וגם בבקשות ההעלאה הבאות.

כותרות אופציונליות שאפשר להוסיף לבקשה כוללות את X-Upload-Content-Type ואת X-Upload-Content-Length.

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

ה-URI הזה משמש בבקשות הבאות להעלאת נתוני האובייקט.

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

‫API בפורמט XML

מקבלים אסימון גישה להרשאה מ-OAuth 2.0 Playground. מגדירים את ה-Playground לשימוש בפרטי הכניסה שלכם ב-OAuth. הוראות מפורטות מופיעות במאמר אימות API.
משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט XML עם בקשת אובייקט POST עם גוף ריק:
```
curl -i -X POST -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Length: 0" \
    -H "Content-Type: OBJECT_CONTENT_TYPE" \
    -H "x-goog-resumable: start" \
    "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
```
כאשר:
- ‫OAUTH2_TOKEN הוא אסימון הגישה שיצרתם בשלב 1.
- OBJECT_CONTENT_TYPE הוא סוג התוכן של האובייקט. לדוגמה, image/png. אם לא מציינים סוג תוכן, מערכת Cloud Storage מגדירה את המטא-נתונים Content-Type של האובייקט להיות application/octet-stream.
- ‫BUCKET_NAME הוא שם הקטגוריה שאליה מעלים את האובייקט. לדוגמה, my-bucket.
- OBJECT_NAME הוא השם בקידוד כתובת ה-URL שרוצים לתת לאובייקט. לדוגמה, pets/dog.png, בקידוד כתובת ה-URL כ-pets%2Fdog.png.
אם הפעלתם שיתוף משאבים בין מקורות, צריך לכלול גם את הכותרת Origin בבקשות ההעלאה האלו וגם בבקשות ההעלאה הבאות.

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

ה-URI הזה משמש בבקשות הבאות להעלאת נתוני האובייקט.

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

העלאת הנתונים

אחרי שמתחילים העלאה שניתן להמשיך, יש שתי דרכים להעלות את נתוני האובייקט:

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

העלאת מקטע יחיד

כדי להעלות את הנתונים במקטע יחיד:

‫API בפורמט JSON

משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת אובייקט PUT:
```
curl -i -X PUT --data-binary @OBJECT_LOCATION \
    -H "Content-Length: OBJECT_SIZE" \
    "SESSION_URI"
```
כאשר:
- ‫OBJECT_LOCATION הוא הנתיב המקומי לאובייקט. לדוגמה, Desktop/dog.png.
- ‫OBJECT_SIZE הוא מספר הבייטים באובייקט. לדוגמה, 20000000.
- ‫SESSION_URI הוא הערך שהוחזר בכותרת Location כשבוצע אתחול של ההעלאה שניתן להמשיך.
אפשר גם לכלול כותרות עם הקידומת X-Goog-Meta-, כדי להוסיף מטא-נתונים בהתאמה אישית בשביל האובייקט כחלק מהבקשה.

‫API בפורמט XML

משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט XML באמצעות בקשת אובייקט PUT:
```
curl -i -X PUT --data-binary @OBJECT_LOCATION \
    -H "Content-Length: OBJECT_SIZE" \
    "SESSION_URI"
```
כאשר:
- ‫OBJECT_LOCATION הוא הנתיב המקומי לאובייקט. לדוגמה, Desktop/dog.png.
- ‫OBJECT_SIZE הוא מספר הבייטים באובייקט. לדוגמה, 20000000.
- ‫SESSION_URI הוא הערך שהוחזר בכותרת Location כשבוצע אתחול של ההעלאה שניתן להמשיך.

אם ההעלאה תושלם במלואה, מקבלים תשובה מסוג 200 OK או 201 Created עם המטא-נתונים המשויכים למשאב.

אם בקשת ההעלאה הופסקה או אם מקבלים תשובה מסוג 5xx, אפשר להיעזר בהוראות שבקטע המשך של העלאה שהופסקה.

העלאה של מספר מקטעים

כדי להעלות את הנתונים במספר מקטעים:

‫API בפורמט JSON

יוצרים מקטע נתונים מתוך כלל הנתונים שרוצים להעלות.

גודל המקטע צריך להיות כפולה של 256KiB (256 x 1,024 בייטים), אלא אם הוא המקטע האחרון המשלים את ההעלאה. כשמדובר במקטעים גדולים יותר, בדרך כלל ההעלאה מהירה יותר, אבל חשוב לזכור שיש הבדל בין מהירות לבין שימוש בזיכרון. מומלץ להשתמש ב-8MiB לפחות לגודל המקטעים.
משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת אובייקט PUT:
```
curl -i -X PUT --data-binary @CHUNK_LOCATION \
    -H "Content-Length: CHUNK_SIZE" \
    -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"
```
כאשר:
- ‫CHUNK_LOCATION הוא הנתיב המקומי למקטע שאתם מעלים כרגע.
- ‫CHUNK_SIZE הוא מספר הבייטים שמעלים בבקשה הנוכחית. לדוגמה, 8388608.
- ‫CHUNK_FIRST_BYTE הוא הבייט ההתחלתי באובייקט הכולל, שמכיל את המקטע שמעלים.
- ‫CHUNK_LAST_BYTE הוא הבייט הסופי באובייקט הכללי שמכיל את המקטע שמעלים.
- ‫TOTAL_OBJECT_SIZE הוא הגודל הכולל של האובייקט שמעלים.
- ‫SESSION_URI הוא הערך שהוחזר בכותרת Location כשבוצע אתחול של ההעלאה שניתן להמשיך.
למשל, Content-Range הוא Content-Range: bytes 0-8388607/20000000. למידע נוסף על הכותרת הזו, ראו Content-Range.

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

אם רוצים, בבקשה הסופית של ההעלאה שניתן להמשיך, אפשר לכלול כותרות עם הקידומת X-Goog-Meta- כדי להוסיף לאובייקט מטא-נתונים בהתאמה אישית.

‫API בפורמט XML

יוצרים מקטע נתונים מתוך כלל הנתונים שרוצים להעלות.

גודל המקטע צריך להיות כפולה של 256KiB (256 x 1,024 בייטים), אלא אם הוא המקטע האחרון המשלים את ההעלאה. כשמדובר במקטעים גדולים יותר, בדרך כלל ההעלאה מהירה יותר, אבל חשוב לזכור שיש הבדל בין מהירות לבין שימוש בזיכרון. מומלץ להשתמש ב-8MiB לפחות לגודל המקטעים.
משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט XML באמצעות בקשת אובייקט PUT:
```
curl -i -X PUT --data-binary @CHUNK_LOCATION \
    -H "Content-Length: CHUNK_SIZE" \
    -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"
```
כאשר:
- ‫CHUNK_LOCATION הוא הנתיב המקומי למקטע שאתם מעלים כרגע.
- ‫CHUNK_SIZE הוא מספר הבייטים שמעלים בבקשה הנוכחית. לדוגמה, 8388608.
- ‫CHUNK_FIRST_BYTE הוא הבייט ההתחלתי באובייקט הכולל, שמכיל את המקטע שמעלים.
- ‫CHUNK_LAST_BYTE הוא הבייט הסופי באובייקט הכללי שמכיל את המקטע שמעלים.
- ‫TOTAL_OBJECT_SIZE הוא הגודל הכולל של האובייקט שמעלים.
- ‫SESSION_URI הוא הערך שהוחזר בכותרת Location כשבוצע אתחול של ההעלאה שניתן להמשיך.
למשל, Content-Range הוא Content-Range: bytes 0-8388607/20000000. למידע נוסף על הכותרת הזו, ראו Content-Range.

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

כשההעלאה מסתיימת במלואה, מקבלים את התשובה 200 OK או 201 Created עם כל המטא-נתונים שמשויכים למשאב.

אם אחת מהעלאות המקטעים הופסקה, או אם מקבלים תשובה 5xx צריך לשלוח שוב את המקטע שהופסק בשלמותו אולהמשיך את ההעלאה שהופסקה מהמקום שבו היא הפסיקה.

בדיקת הסטטוס של העלאה שניתן להמשיך

אם ההעלאה שניתן להמשיך הופסקה, או אם לא בטוחים שההעלאה הושלמה, אפשר לבדוק את סטטוס ההעלאה:

‫API בפורמט JSON

משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת אובייקט PUT:
```
curl -i -X PUT \
    -H "Content-Length: 0" \
    -H "Content-Range: bytes */OBJECT_SIZE" \
    "SESSION_URI"
```
כאשר:
- ‫OBJECT_SIZE הוא המספר הכולל של הבייטים באובייקט. אם לא יודעים מה הגודל המלא של האובייקט, אפשר להשתמש ב-* בשביל הערך הזה.
- ‫SESSION_URI הוא הערך שהוחזר בכותרת Location כשבוצע אתחול של ההעלאה שניתן להמשיך.

‫API בפורמט XML

משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט XML באמצעות בקשת אובייקט PUT:
```
curl -i -X PUT \
    -H "Content-Length: 0" \
    -H "Content-Range: bytes */OBJECT_SIZE" \
    "SESSION_URI"
```
כאשר:
- ‫OBJECT_SIZE הוא המספר הכולל של הבייטים באובייקט. אם לא יודעים מה הגודל המלא של האובייקט, אפשר להשתמש ב-* בשביל הערך הזה.
- ‫SESSION_URI הוא הערך שהוחזר בכותרת Location כשבוצע אתחול של ההעלאה שניתן להמשיך.

התשובה 200 OK או 201 Created מציינת שההעלאה הושלמה ולא צריך לבצע פעולה נוספת.

התשובה 308 Resume Incomplete מציינת שצריך להמשיך בהעלאת הנתונים.

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

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

אם בקשת העלאה הופסקה לפני קבלת תשובה, או אם מקבלים תשובה של 503 או 500, צריך להמשיך את ההעלאה מהמקום שבו היא הופסקה. כדי להמשיך העלאה שהופסקה:

‫API בפורמט JSON

בודקים את הסטטוס של ההעלאה שניתן להמשיך.
שומרים את הערך העליון של הכותרת Range שמופיעה בתשובה לבדיקת הסטטוס. אם התשובה לא כוללת את הכותרת Range, המשמעות היא שעדיין לא נשמרו בייטים ב-Cloud Storage וצריך לבצע העלאה מההתחלה.
צריך לוודא שנתוני האובייקטים שעומדים להעלות מתחילים בבייטים שאחרי הערך העליון בכותרת Range.
אם הבקשה שהופסקה הכילה כותרות עם קידומת X-Goog-Meta-, צריך לכלול את הכותרות האלו בבקשה כדי להמשיך את ההעלאה.
משתמשים ב-cURL כדי לקרוא ל-API בפורמט JSON עם בקשת אובייקט PUT, שממשיכה מהבייט שאחרי הערך שמופיע בכותרת Range:
```
curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
    -H "Content-Length: UPLOAD_SIZE_REMAINING" \
    -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"
```
כאשר:
- ‫PARTIAL_OBJECT_LOCATION הוא הנתיב המקומי לחלק הנותר של הנתונים שרוצים להעלות.
- ‫UPLOAD_SIZE_REMAINING הוא מספר הבייטים שמעלים בבקשה הנוכחית. לדוגמה, אם מעלים את שאר האובייקט בגודל כולל של 20,000,000 שהופסק אחרי העלאת הבייטים שבין 0 ל-42, הערך של UPLOAD_SIZE_REMAINING יהיה 19999957.
- ‫NEXT_BYTE הוא המספר השלם הבא אחרי הערך שנשמר בשלב 2. לדוגמה, אם 42 הוא הערך העליון בשלב 2, הערך של NEXT_BYTE הוא 43.
- ‫LAST_BYTE הוא הבייט הסופי שכלול בבקשת PUT הזו. לדוגמה, כדי לסיים להעלות אובייקט שהגודל הכולל שלו הוא 20000000, הערך של LAST_BYTE הוא 19999999.
- ‫TOTAL_OBJECT_SIZE הוא הגודל הכולל של האובייקט שמעלים. לדוגמה, 20000000.
- ‫SESSION_URI הוא הערך שהוחזר בכותרת Location כשבוצע אתחול של ההעלאה שניתן להמשיך.

‫API בפורמט XML

בודקים את הסטטוס של ההעלאה שניתן להמשיך.
שומרים את הערך העליון של הכותרת Range שמופיעה בתשובה לבדיקת הסטטוס. אם התשובה לא כוללת את הכותרת Range, המשמעות היא שעדיין לא נשמרו בייטים ב-Cloud Storage וצריך לבצע העלאה מההתחלה.
צריך לוודא שנתוני האובייקטים שעומדים להעלות מתחילים בבייטים שאחרי הערך העליון בכותרת Range.
משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט XML עם בקשת אובייקט PUT, שממשיכה מהבייט שאחרי הערך שמופיע בכותרת Range:
```
curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
    -H "Content-Length: UPLOAD_SIZE_REMAINING" \
    -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"
```
כאשר:
- ‫PARTIAL_OBJECT_LOCATION הוא הנתיב המקומי לחלק הנותר של הנתונים שרוצים להעלות.
- ‫UPLOAD_SIZE_REMAINING הוא מספר הבייטים שמעלים בבקשה הנוכחית. לדוגמה, אם מעלים את שאר האובייקט בגודל כולל של 20,000,000 שהופסק אחרי העלאת הבייטים שבין 0 ל-42, הערך של UPLOAD_SIZE_REMAINING יהיה 19999957.
- ‫NEXT_BYTE הוא המספר השלם הבא אחרי הערך שנשמר בשלב 2. לדוגמה, אם 42 הוא הערך העליון בשלב 2, הערך של NEXT_BYTE הוא 43.
- ‫LAST_BYTE הוא הבייט הסופי שכלול בבקשת PUT הזו. לדוגמה, כדי לסיים להעלות אובייקט שהגודל הכולל שלו הוא 20000000, הערך של LAST_BYTE הוא 19999999.
- ‫TOTAL_OBJECT_SIZE הוא הגודל הכולל של האובייקט שמעלים. לדוגמה, 20000000.
- ‫SESSION_URI הוא הערך שהוחזר בכותרת Location כשבוצע אתחול של ההעלאה שניתן להמשיך.

אפשר להמשיך את ההעלאות כמה פעמים שצריך בזמן שה-URI של הסשן פעיל. ה-URI של הסשן פג לאחר שבוע. כשמעלים את הנתונים בהצלחה, Cloud Storage משיב עם קוד סטטוס 200 OK או 201 created.

ביטול העלאה

כדי לבטל העלאה שניתן להמשיך שלא הושלמה ולמנוע פעולה עתידית נוספת לגביה:

‫API בפורמט JSON

משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON עם בקשת DELETE:
```
curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"
```
כאשר:
- ‫SESSION_URI הוא הערך שהוחזר בכותרת Location כשבוצע אתחול של ההעלאה שניתן להמשיך.

אם הפעולה מצליחה, התשובה תכיל קוד סטטוס 499. ניסיונות עתידיים לשלוח שאילתה לתוצאת ההעלאה או להמשיך אותה יביאו לתשובה 4xx.

‫API בפורמט XML

משתמשים ב-cURLכדי לשלוח קריאה ל-API בפורמט XML באמצעות בקשת DELETE:
```
curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"
```
כאשר:
- ‫SESSION_URI הוא הערך שהוחזר בכותרת Location כשבוצע אתחול של ההעלאה שניתן להמשיך.

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

המאמרים הבאים

מידע נוסף על העלאות שניתן להמשיך.
סקירה כללית של API בפורמט JSON ו-API בפורמט XML.
העלאות סטרימינג בגודל לא ידוע.
שליחת מספר בקשות באצווה ל-API בפורמט JSON ב-Cloud Storage.