העלה את המדיה

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

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

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

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

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

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

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

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

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

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

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

upload-token

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

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

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

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

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

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

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

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

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

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

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

{
  "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 של הבקשה. קוד סטטוס שאינו אפס מציין שגיאה.

{
  "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 contains a status נמצא בתוך התג mediaMetadata ומתאר את מצב העיבוד של קובץ הווידאו. קובץ חדש שהועלה יחזיר קודם את הסטטוס PROCESSING, לפני שיהיה אפשר להשתמש בו.READY פרטים נוספים זמינים במאמר בנושא גישה לפריטי מדיה.

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

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

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

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

• כדאי לפעול לפי השיטות המומלצות לניסיון חוזר ולטיפול בשגיאות, ולזכור את הנקודות הבאות:
  • שגיאות 429 יכולות להתרחש אם מיציתם את המכסה או אם הוגבלה מהירות השליחה שלכם כי ביצעתם יותר מדי קריאות מהר מדי. חשוב לוודא שלא קוראים ל-batchCreate עבור אותו משתמש עד שהבקשה הקודמת מסתיימת.
  • צריך להמתין לפחות 30s לפני שמנסים שוב לפתור שגיאות מסוג 429. כדאי להשתמש באסטרטגיית השהיה מעריכית לפני ניסיון חוזר (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, אפשר להעלות כמה בייטים מכמה משתמשים במקביל, אבל בשלב 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.

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