דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

במדריך הזה מוסבר על רצף הבקשות מסוג HTTP שאפליקציה שולחת כדי להעלות סרטונים באמצעות תהליך העלאה שניתן להמשיך אותו. המדריך הזה מיועד בעיקר למפתחים שלא יכולים להשתמש בספריות הלקוח של Google API, שחלקן מספקות תמיכה מקורית בהעלאות שניתן להמשיך אותן. למעשה, במדריך YouTube Data API – העלאת סרטון מוסבר איך להשתמש בספריית הלקוח של Google APIs ל-Python כדי להעלות סרטון באמצעות תהליך העלאה שניתן להמשיך.

הערה: אפשר גם לראות את סדרת הבקשות שנשלחו להעלאה שניתן להמשיך אותה או לכל פעולת API אחרת באמצעות אחת מספריות הלקוח של Google API עם הפעלת הרישום ביומן של HTTPS. לדוגמה, כדי להפעיל את המעקב אחר HTTP ב-Python, משתמשים בספרייה httplib2:

httplib2.debuglevel = 4

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

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

https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=PARTS

מגדירים את גוף הבקשה למשאב video. צריך להגדיר גם את כותרות הבקשה הבאות של HTTP:

Authorization – טוקן ההרשאה של הבקשה.
Content-Length – מספר הבייטים שצוינו בגוף הבקשה. שימו לב שאין צורך לספק את הכותרת הזו אם משתמשים בקידוד העברה במקטעים.
Content-Type – מגדירים את הערך כ-application/json; charset=UTF-8.
X-Upload-Content-Length – מספר הבייטים שיועלה בבקשות הבאות. מגדירים את הערך הזה לגודל הקובץ שאתם מעלים.
x-upload-content-type – סוג ה-MIME של הקובץ שאתם מעלים. אפשר להעלות קובצים עם כל סוג MIME של סרטון (video/*) או עם סוג MIME של application/octet-stream.

הדוגמה הבאה מראה איך מתחילים סשן שניתן להמשיך אותו להעלאת סרטון. הבקשה מגדירה (ותאחזר) נכסים בחלקים snippet ו-status של המשאב video, והיא תאחזר גם נכסים בחלק contentdetails של המשאב.

post /upload/youtube/v3/videos?uploadType=resumable&part=parts http/1.1
host: www.googleapis.com
authorization: bearer auth_token
content-length: content_length
content-type: application/json; charset=utf-8
x-upload-content-length: x_upload_content_length
X-Upload-Content-Type: X_UPLOAD_CONTENT_TYPE

video resource

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

POST /upload/youtube/v3/videos?uploadType=resumable&part=snippet,status,contentDetails HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer AUTH_TOKEN
Content-Length: 278
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Length: 3000000
X-Upload-Content-Type: video/*

{
  "snippet": {
    "title": "My video title",
    "description": "This is a description of my video",
    "tags": ["cool", "video", "more keywords"],
    "categoryId": 22
  },
  "status": {
    "privacyStatus": "public",
    "embeddable": True,
    "license": "youtube"
  }
}

שלב 2 – שומרים את ה-URI של הסשן שניתן להמשיך

אם הבקשה תתבצע בהצלחה, שרת ה-API יגיב עם קוד סטטוס HTTP‏ 200 (OK), והתגובה תכלול כותרת HTTP‏ Location שמציינת את ה-URI של הסשן שניתן להמשיך. זהו ה-URI שבו תשתמשו כדי להעלות את קובץ הווידאו.

בדוגמה הבאה מוצגת תגובה לדוגמה של API לבקשה בשלב 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&upload_id=xa298sd_f&part=snippet,status,contentDetails
Content-Length: 0

שלב 3 – מעלים את קובץ הסרטון

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

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: CONTENT_LENGTH
Content-Type: CONTENT_TYPE

BINARY_FILE_DATA

הבקשה מגדירה את כותרות הבקשה הבאות של HTTP:

Authorization – טוקן ההרשאה של הבקשה.
Content-Length – הגודל של הקובץ שאתם מעלים. הערך הזה צריך להיות זהה לערך של כותרת בקשת ה-HTTP X-Upload-Content-Length בשלב 1.
Content-Type – סוג ה-MIME של הקובץ שאתם מעלים. הערך הזה צריך להיות זהה לערך של כותרת בקשת ה-HTTP X-Upload-Content-Type בשלב 1.

שלב 4 – משלימים את תהליך ההעלאה

הבקשה שלכם תוביל לאחד מהתרחישים הבאים:

ההעלאה בוצעה בהצלחה.

שרת ה-API מגיב עם קוד תגובה HTTP 201 (Created). גוף התגובה הוא המשאב video שיצרתם.
ההעלאה נכשלה, אבל אפשר להמשיך אותה.

אפשר להמשיך בהעלאה במקרים הבאים:
- הבקשה שלכם מופסקת כי החיבור בין האפליקציה שלכם לשרת ה-API אבד. במקרה כזה, לא תקבלו תשובה מה-API.
- תגובת ה-API מציינת אחד מקודי התגובה הבאים של 5xx. כשממשיכים את ההעלאות אחרי קבלת אחד מקודי התגובה האלה, צריך להשתמש בקוד עם אסטרטגיית השהיה מעריכית לפני ניסיון חוזר.
  - 500 – Internal Server Error
  - 502 – Bad Gateway
  - 503 – Service Unavailable
  - 504 – Gateway Timeout
כדי להמשיך בהעלאה, פועלים לפי ההוראות לבדיקת סטטוס ההעלאה ולהמשך ההעלאה שמפורטות בהמשך. חשוב לזכור שלכל URI של סשן שניתן להמשיך יש משך חיים מוגבל, והוא יפוג בסופו של דבר. לכן מומלץ להתחיל העלאה שניתן להמשיך ברגע שמקבלים את ה-URI של הסשן, ולהמשיך העלאה שהופסקה זמן קצר אחרי ההפסקה.
ההעלאה נכשלה באופן סופי.

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

אם שולחים בקשה עם URI של סשן שפג תוקפו, השרת מחזיר קוד תגובה HTTP‏ 404 (Not Found). במקרה כזה, תצטרכו להתחיל העלאה חדשה שניתן להמשיך, לקבל URI של סשן חדש ולהתחיל את ההעלאה מההתחלה באמצעות ה-URI החדש.

שלב 4.1: בדיקת הסטטוס של העלאה

כדי לבדוק את הסטטוס של העלאה מופסקת שניתן להמשיך, שולחים בקשת PUT ריקה לכתובת ה-URL להעלאה שאוחזרה בשלב 2 וששימשה גם בשלב 3. בבקשה, מגדירים את ערך הכותרת Content-Range כ-bytes */CONTENT_LENGTH, כאשר CONTENT_LENGTH הוא גודל הקובץ שאתם מעלים.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 0
Content-Range: bytes */CONTENT_LENGTH

שלב 4.2: עיבוד התגובה מה-API

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

עם זאת, אם ההעלאה הופסקה או שהיא עדיין מתבצעת, קוד התגובה של ה-API יהיה 308 (Resume Incomplete)‏ HTTP. בתגובה, הכותרת Range מציינת כמה בייטים של הקובץ כבר הועלאו בהצלחה.

ערך הכותרת נוסף לאינדקס מ-0. לכן, ערך כותרת של 0-999999 מציין שהבייטים הראשונים של הקובץ (1,000,000) הועלאו.
אם עדיין לא העליתם דבר, תגובה ה-API לא תכלול את הכותרת Range.

התגובה לדוגמה שבהמשך מראה את הפורמט של תגובה מ-API להעלאה שניתן להמשיך אותה:

308 Resume Incomplete
Content-Length: 0
Range: bytes=0-999999

אם התגובה מה-API כוללת גם את הכותרת Retry-After, משתמשים בערך של הכותרת הזו כדי לקבוע מתי לנסות להמשיך את ההעלאה.

שלב 4.3: ממשיכים את ההעלאה

כדי להמשיך את ההעלאה, שולחים בקשת PUT נוספת לכתובת ה-URL של ההעלאה שצוינה בשלב 2. מגדירים את גוף הבקשה לקוד הבינארי של החלק בקובץ הווידאו שעדיין לא הועלה.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: REMAINING_CONTENT_LENGTH
Content-Range: bytes FIRST_BYTE-LAST_BYTE/TOTAL_CONTENT_LENGTH

PARTIAL_BINARY_FILE_DATA

צריך להגדיר את כותרות הבקשה הבאות של HTTP:

Authorization – טוקן ההרשאה של הבקשה.
Content-Length – הגודל בבייטים של התוכן שעדיין לא הועלה. אם מעלים את שאר הקובץ, אפשר לחשב את הערך הזה על ידי חיסור הערך של FIRST_BYTE מהערך של TOTAL_CONTENT_LENGTH. המערכת משתמשת בשני הערכים האלה בכותרת Content-Range.
Content-Range – החלק של הקובץ שאתם מעלים. ערך הכותרת מורכב משלושה ערכים:
- FIRST_BYTE – האינדקס המספרי שמתחיל ב-0 של מספר הבייט שממנו מחדשים את ההעלאה. הערך הזה גבוה במספר אחד מהמספר השני בכותרת Range שאוחזרה בשלב הקודם. בדוגמה הקודמת, ערך הכותרת Range היה 0-999999, כך שהבייט הראשון בהעלאה חוזרת לאחר מכן יהיה 1000000.
- LAST_BYTE – האינדקס המספרי שמתחיל ב-0 של הבייט האחרון בקובץ הבינארי שאתם מעלים. בדרך כלל, זהו הבייט האחרון בקובץ. לדוגמה, אם גודל הקובץ היה 3000000 בייטים, הבייט האחרון בקובץ יהיה מספר 2999999.
- TOTAL_CONTENT_LENGTH – הגודל הכולל של קובץ הסרטון בבייטים. הערך הזה זהה לכותרת Content-Length שצוינה בבקשת ההעלאה המקורית.
הערה: אי אפשר להעלות בלוק לא רציף של הקובץ הבינארי. אם תנסו להעלות בלוק לא רציף, אף אחד מהתוכן הבינארי שנותר לא ייכלל בהעלאה.

לכן, הבייט הראשון שהולך להעלות בהעלאה מחודשת חייב להיות הבייט הבא אחרי הבייט האחרון שכבר הועלה ל-YouTube. (ראו את הדיון על הכותרת Range בקטע שלב 4.2).

לכן, אם הבייט האחרון בכותרת Range הוא 999999, הבייט הראשון בבקשה להמשך ההעלאה חייב להיות הבייט 1000000. (שני המספרים מבוססים על אינדקס שמתחיל בספרה 0). אם תנסו להמשיך את ההעלאה מהבייט 999999 או מבייט נמוך יותר (בייטים חופפים) או מהבייט 1000001 או מבייט גבוה יותר (דילוג על בייטים), אף אחד מהתוכן הבינארי לא יועלה.

העלאת קובץ במקטעים

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

ההוראות להעלאת קובץ בחלקים זהות כמעט לתהליך בן ארבעת השלבים שמתואר קודם במדריך הזה. עם זאת, כשקובץ מועלה בחלקים, הערכים של הכותרות Content-Length ו-Content-Range מוגדרים באופן שונה בבקשות להתחיל להעלות קובץ (שלב 3 למעלה) ובבקשות להמשיך העלאה (שלב 4.3 למעלה).

ערך הכותרת Content-Length מציין את גודל הקטע שנשלח בבקשה. שימו לב להגבלות הבאות על גודל הקטעים:
- הגודל של מקטע הנתונים חייב להיות כפולה של 256KB. (ההגבלה הזו לא חלה על המקטע האחרון, כי ייתכן שהגודל של הקובץ כולו לא יהיה כפולה של 256KB). חשוב לזכור שקטעים גדולים יותר יעילים יותר.
- גודל המקטע חייב להיות זהה בכל בקשה ברצף ההעלאה, מלבד הבקשה האחרונה שבה מצוין גודל המקטע האחרון.
הכותרת Content-Range מציינת את הבייטים בקובץ שהבקשה מעלה. ההוראות להגדרת הכותרת Content-Range בשלב 4.3 רלוונטיות גם להגדרת הערך הזה.

לדוגמה, ערך של bytes 0-524287/2000000 מראה שהבקשה שולחת את 524,288 הבייטים הראשונים (256 x 2048) בקובץ של 2,000,000 בייטים.

בדוגמה הבאה מוצג הפורמט של הבקשה הראשונה בסדרה של בקשות להעלאת קובץ בנפח 2,000,000 בייטים בחלקים:

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 524888
Content-Type: video/*
Content-Range: bytes 0-524287/2000000

{bytes 0-524287}

אם בקשה שאינה הבקשה האחרונה מצליחה, שרת ה-API משיב בתגובה מסוג 308 (Resume Incomplete). פורמט התגובה יהיה זהה לפורמט שמתואר בקטע שלב 4.2: עיבוד התגובה של ה-API למעלה.

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

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

אם בקשה כלשהי הופסקה או שהאפליקציה קיבלה קוד תשובה מסוג 5xx, צריך לפעול לפי ההליך שמתואר בשלב 4 כדי להשלים את ההעלאה. עם זאת, במקום לנסות להעלות את שאר הקובץ, פשוט ממשיכים להעלות קטעים מהמקום שבו ממשיכים את ההעלאה. חשוב לבדוק את סטטוס ההעלאה כדי לקבוע איפה להמשיך בהעלאת הקובץ. אל תניחו שהשרת קיבל את כל הבייטים שנשלחו בבקשה הקודמת (או אף אחד מהם).

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