העלה את המדיה

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

  1. מעלים את הבייטים של קובצי המדיה לשרת Google באמצעות ההעלאות נקודת קצה (endpoint). הפעולה הזו מחזירה אסימון העלאה שמזהה את הבייטים שהועלו.
  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. אם לא ניתן ליצור פריטי מדיה, הבקשה מחזירה את סטטוס HTTP 207 MULTI-STATUS כדי לציין הצלחה חלקית.

{
  "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 פריטים לכל היותר.

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

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

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

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

קוד פסאודוקוד

// 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.

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