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

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

מומלץ להשתמש בהעלאות שניתנות לחידוש בכל אחד מהמצבים הבאים:

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

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

העלאת קובץ בגושים

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

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

  • ערך הכותרת 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 שלמעלה.

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

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

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

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