העלה את המדיה

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

  1. מעלים את הבייטים של קובצי המדיה לשרת Google באמצעות נקודת הקצה להעלאות. הפעולה הזו מחזירה אסימון העלאה שמזהה את הבייטים שהועלו.
  2. משתמשים בקריאה ב-batchCreate עם אסימון ההעלאה כדי ליצור פריט מדיה בחשבון Google Photos של המשתמש.

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

לפני שמתחילים

היקפי ההרשאות הנדרשים

כדי להעלות פריטי מדיה לספרייה או לאלבום של משתמש, נדרש ההיקף photoslibrary.appendonly. מידע נוסף על היקפים זמין במאמר היקפי הרשאה.

סוגי הקבצים והגדלים הקבילים

אפשר להעלות את סוגי הקבצים שמפורטים בטבלה הזו.

סוג מדיה סוגי קבצים קבילים גודל קובץ מקסימלי
תמונות AVIF,‏ BMP,‏ GIF,‏ HEIC,‏ ICO,‏ JPG,‏ PNG,‏ TIFF,‏ WEBP,‏ קובצי RAW מסוימים. ‎200 GB
סרטונים 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD, WMV. ‎20 GB

שלב 1: העלאת בייטים

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

REST

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

שדות כותרת
Content-type מגדירים את הערך application/octet-stream.
X-Goog-Upload-Content-Type מומלץ. מגדירים את סוג ה-MIME של הבייטים שאתם מעלים. סוגי MIME נפוצים כוללים את image/jpeg,‏ image/png ו-image/gif.
X-Goog-Upload-Protocol מגדירים את הערך raw.

זוהי כותרת של בקשת POST:

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-type: application/octet-stream
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: raw

בגוף הבקשה, כוללים את הקובץ הבינארי של הקובץ: 

media-binary-data

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

upload-token

גודל הקובץ המוצע לתמונות קטן מ-50MB. קבצים שגודלם עולה על 50MB עלולים לגרום לבעיות בביצועים.

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

שלב 2: יצירת פריט מדיה

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

כדי ליצור פריטי מדיה חדשים, צריך להפעיל את mediaItems.batchCreate ולציין רשימה של newMediaItems. כל newMediaItem מכיל אסימון העלאה שצוין ב-simpleMediaItem ותיאור אופציונלי שמוצג למשתמש.

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

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

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

REST

זוהי כותרת בקשת ה-POST:

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer oauth2-token

גוף הבקשה צריך לציין רשימה של newMediaItems.

{
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

אפשר גם לציין albumId ו-albumPosition כדי להוסיף קובצי מדיה למיקום ספציפי באלבום.

REST

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
    , ...
  ],
  "albumPosition": {
    "position": "after-media-item",
    "relativeMediaItemId": "media-item-id"
  }
}

פרטים נוספים על מיקום התמונות באלבומים זמינים במאמר הוספת תוכן נוסף.

תגובה ליצירת פריט

קריאה ל-mediaItems.batchCreate מחזירה את התוצאה לכל פריט מדיה שניסיתם ליצור. הרשימה של newMediaItemResults מציינת את הסטטוס וכוללת את uploadToken של הבקשה. קוד סטטוס שאינו אפס מציין שגיאה.

REST

אם כל פריטי המדיה נוצרו בהצלחה, הבקשה תחזיר את סטטוס ה-HTTP 200 OK. אם אי אפשר ליצור פריטי מדיה מסוימים, הבקשה תחזיר את הסטטוס 207 MULTI-STATUS של HTTP כדי לציין שהפעולה הושלמה בהצלחה.

{
  "newMediaItemResults": [
    {
      "uploadToken": "upload-token",
      "status": {
        "message": "Success"
      },
      "mediaItem": {
        "id": "media-item-id",
        "description": "item-description",
        "productUrl": "https://photos.google.com/photo/photo-path",
        "mimeType": "mime-type",
        "mediaMetadata": {
          "width": "media-width-in-px",
          "height": "media-height-in-px",
          "creationTime": "creation-time",
          "photo": {}
        },
        "filename": "filename"
      }
    },
    {
      "uploadToken": "upload-token",
      "status": {
        "code": 13,
        "message": "Internal error"
      }
    }
  ]
}

אם הפריט נוסף בהצלחה, מוחזר mediaItem שמכיל את הערכים של mediaItemId,‏ productUrl ו-mediaMetadata. מידע נוסף זמין במאמר גישה לפריטי מדיה.

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

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

התוצאות תמיד מוחזרות באותו הסדר שבו הושלחו אסימוני ההעלאה.

שיטות מומלצות להעלאות

השיטות המומלצות והמקורות הבאים יעזרו לכם לשפר את היעילות הכוללת של ההעלאות:

  • פועלים לפי השיטות המומלצות לניהול שגיאות וניסיון חוזר, תוך שמירה על הנקודות הבאות:
    • שגיאות מסוג 429 יכולות להתרחש אם המכסה שלכם נוצלה או אם יש הגבלת קצב בגלל ביצוע יותר מדי קריאות במהירות גבוהה מדי. חשוב לוודא שלא קוראים לפונקציה batchCreate עבור אותו משתמש עד שהבקשה הקודמת הושלמה.
    • כשמתקבלות שגיאות מסוג 429, צריך להמתין 30s שניות לפחות לפני שמנסים שוב. כשמנסים לשלוח שוב בקשות, כדאי להשתמש באסטרטגיה של השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
    • שגיאות מסוג 500 מתרחשות כשהשרת נתקל בשגיאה. סביר להניח שהסיבה לכך היא ביצוע כמה קריאות כתיבה (למשל, batchCreate) לאותו משתמש בו-זמנית. צריך לבדוק את פרטי הבקשה ולא לבצע קריאות ל-batchCreate במקביל.
  • כדאי להשתמש בתהליך ההעלאה שניתן להמשיך כדי לשפר את העמידות של ההעלאות במקרה של שיבושים ברשת, וכך לצמצם את השימוש ברוחב הפס על ידי האפשרות להמשיך העלאות שהושלמו חלקית. חשוב להשתמש בהגדרה הזו כשאתם מעלים קבצים גדולים או מעלים קבצים ממכשירים ניידים של לקוחות.

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

העלאת בייטים

  • אפשר להעלות בייטים (כדי לאחזר אסימוני העלאה) במקביל.
  • צריך להגדיר תמיד את סוג ה-MIME הנכון בכותרת X-Goog-Upload-Content-Type בכל קריאת העלאה.

יצירת פריטים של מדיה

  • אין לבצע שיחות במקביל ל-batchCreate עבור משתמש יחיד.

    • לכל משתמש, מבצעים קריאות ל-batchCreate ברצף.
    • אם יש כמה משתמשים, תמיד צריך לבצע קריאות ל-batchCreate לכל משתמש בנפרד. לבצע במקביל רק שיחות עבור משתמשים שונים.

  • מומלץ לכלול כמה שיותר NewMediaItems בכל קריאה ל-batchCreate כדי לצמצם את מספר הקריאות הכולל שצריך לבצע. אפשר לכלול עד 50 פריטים.

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

הדרכה מפורטת לדוגמה

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

שלב 1: מעלים בייטים גולמיים

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

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

פסאודו קוד

CREATE uploadQueue FROM users, filesToUpload
// Upload media bytes in parallel.
START multiple THREADS
  WHILE uploadQueue is not empty
    POP uploadQueue
    UPLOAD file for user
    GET uploadToken
    CHECK and HANDLE errors
    STORE uploadToken for user in uploadTokensQueue
  END

שלב 2: יוצרים פריטים של מדיה

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

פסאודו קוד

// For each user, create media items once 50 upload tokens have been
// saved, or no more uploads are left per user.
WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user
  // Calls can be made in parallel for different users,
  // but only make a single call per user at a time.
  START new thread for (this) user if there is no thread yet
    POP 50 uploadTokens from uploadTokensQueue for user
    CALL mediaItems.batchCreate with uploadTokens
    WAIT UNTIL batchCreate call has completed
    CHECK and HANDLE errors (retry as needed)
  DONE.

צריך להמשיך בתהליך הזה עד להשלמת כל ההעלאות והשיחות ליצירת מדיה.