העלה את המדיה

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

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

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

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

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

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

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

כשיוצרים אלבומים, המאפיין isWriteable מציין אם לאפליקציה יש גישה ליצירת מדיה באלבום מסוים.

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

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

סוג מדיה סוגי הקבצים האפשריים גודל קובץ מקסימלי
תמונות 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

Java

// Open the file and automatically close it after upload
try (RandomAccessFile file = new RandomAccessFile(pathToFile, "r")) {
  // Create a new upload request
  UploadMediaItemRequest uploadRequest =
      UploadMediaItemRequest.newBuilder()
              // The media type (e.g. "image/png")
              .setMimeType(mimeType)
              // The file to upload
              .setDataFile(file)
          .build();
  // Upload and capture the response
  UploadMediaItemResponse uploadResponse = photosLibraryClient.uploadMediaItem(uploadRequest);
  if (uploadResponse.getError().isPresent()) {
    // If the upload results in an error, handle it
    Error error = uploadResponse.getError().get();
  } else {
    // If the upload is successful, get the uploadToken
    String uploadToken = uploadResponse.getUploadToken().get();
    // Use this upload token to create a media item
  }
} catch (ApiException e) {
  // Handle error
} catch (IOException e) {
  // Error accessing the local file
}

PHP

try {
    // Create a new upload request by opening the file
    // and specifying the media type (e.g. "image/png")
    $uploadToken = $photosLibraryClient->upload(file_get_contents($localFilePath), null, $mimeType);
} catch (\GuzzleHttp\Exception\GuzzleException $e) {
    // Handle error
}

גודל הקובץ המוצע לתמונות קטן מ-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"
      }
    }
   , ...
  ]
}

Java

try {
  // Create a NewMediaItem with the following components:
  // - uploadToken obtained from the previous upload request
  // - filename that will be shown to the user in Google Photos
  // - description that will be shown to the user in Google Photos
  NewMediaItem newMediaItem = NewMediaItemFactory
          .createNewMediaItem(uploadToken, fileName, itemDescription);
  List<NewMediaItem> newItems = Arrays.asList(newMediaItem);

  BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);
  for (NewMediaItemResult itemsResponse : response.getNewMediaItemResultsList()) {
    Status status = itemsResponse.getStatus();
    if (status.getCode() == Code.OK_VALUE) {
      // The item is successfully created in the user's library
      MediaItem createdItem = itemsResponse.getMediaItem();
    } else {
      // The item could not be created. Check the status and try again
    }
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $newMediaItems = [];
    // Create a NewMediaItem with the following components:
    // - uploadToken obtained from the previous upload request
    // - filename that will be shown to the user in Google Photos
    // - description that will be shown to the user in Google Photos
    $newMediaItems[0] = PhotosLibraryResourceFactory::newMediaItemWithDescriptionAndFileName(
            $uploadToken, $itemDescription, $fileName);

    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems);
    foreach ($response->getNewMediaItemResults() as $itemResult) {
        $status = $itemResult->getStatus();
        if ($status->getCode() != Code::OK) {
            // Error while creating the item.
        }
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

ניתן להוסיף פריטי מדיה לספרייה ולאלבום באמצעות ציון אלבום id. מידע נוסף זמין במאמר הבא: ליצור אלבומים.

כל אלבום יכול להכיל עד 20,000 פריטי מדיה. בקשות ליצירת מדיה פריטים באלבום שיחרגו מהמגבלה הזו ייכשלו.

REST

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

Java

try {
  // Create new media items in a specific album
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

אפשר גם לציין את 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"
  }
}

Java

try {
  // Create new media items in a specific album, positioned after a media item
  AlbumPosition positionInAlbum = AlbumPositionFactory.createFirstInAlbum();
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems, positionInAlbum);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems,
        ['albumId' => $albumId, 'albumPosition' => $albumPosition]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

לפרטים נוספים לגבי מיקום באלבומים, להוסיף העשרות.

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

הקריאה 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"
      }
    }
  ]
}

Java

BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);

// The response contains a list of NewMediaItemResults
for (NewMediaItemResult result : response.getNewMediaItemResultsList()) {
  // Each result item is identified by its uploadToken
  String uploadToken = result.getUploadToken();
  Status status = result.getStatus();

  if (status.getCode() == Code.OK_VALUE) {
    // If the request is successful, a MediaItem is returned
    MediaItem mediaItem = result.getMediaItem();
    String id = mediaItem.getId();
    String productUrl = mediaItem.getProductUrl();
    // ...
  }
}

PHP

// The response from a call to batchCreateMediaItems returns a list of NewMediaItemResults
foreach ($response->getNewMediaItemResults() as $itemResult) {
    // Each result item is identified by its uploadToken
    $itemUploadToken = $itemResult->getUploadToken();
    // Verify the status of each entry to ensure that the item has been uploaded correctly
    $itemStatus = $itemResult->getStatus();
    if ($itemStatus->getCode() != Code::OK) {
        // Error when item is being created
    } else {
        // Media item is successfully created
        // Get the MediaItem object from the response
        $mediaItem = $itemResult->getMediaItem();
        // It contains details such as the Id of the item, productUrl
        $id = $mediaItem->getId();
        $productUrl = $mediaItem->getProductUrl();
        // ...
    }
}

אם פריט נוסף בהצלחה, מוחזר 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 פריטים לכל היותר.

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

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

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

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

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

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