Как загрузить файлы

Загрузка медиафайлов — это двухэтапный процесс:

1. Загрузите байты ваших медиафайлов на сервер Google, используя конечную точку загрузки . В результате будет возвращен токен загрузки, идентифицирующий загруженные байты.
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

Рекомендуемый размер файла изображения — менее 50 МБ. Файлы размером более 50 МБ могут вызывать проблемы с производительностью.

API библиотеки Google Фото поддерживает возобновляемую загрузку . Возобновляемая загрузка позволяет разделить медиафайл на несколько частей и загружать их по одной за раз.

Шаг 2: Создание медиа-элемента

После загрузки байтов медиафайлов вы можете создать их как медиаобъекты в Google Фото с помощью токенов загрузки. Токен загрузки действителен в течение одного дня после создания. Медиаобъект всегда добавляется в библиотеку пользователя. Медиаобъекты можно добавлять только в альбомы, созданные вашим приложением. Подробнее см. в разделе «Области авторизации» .

Чтобы создать новые медиа-элементы, вызовите метод mediaItems.batchCreate , указав список объектов newMediaItems . Каждый newMediaItem содержит токен загрузки, указанный внутри simpleMediaItem , и необязательное описание, которое отображается пользователю.

Длина поля описания ограничена 1000 символами и должна содержать только содержательный текст, созданный пользователями. Например, « Наша поездка в парк » или « Праздничный ужин ». Не включайте метаданные, такие как имена файлов, программные теги или другой автоматически сгенерированный текст.

Для достижения максимальной производительности сократите количество вызовов 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 содержит в своих mediaMetadata status , описывающий состояние обработки видеофайла. Только что загруженный файл сначала возвращает статус PROCESSING , а затем становится READY к использованию. Подробнее см. в разделе Доступ к медиафайлам .

Если во время этого вызова возникнет ошибка, следуйте рекомендациям и повторите запрос. Рекомендуется отслеживать успешные добавления, чтобы изображение можно было вставить в альбом в правильном месте при следующем запросе. Подробнее см. в разделе Создание альбомов .

Результаты всегда возвращаются в том же порядке, в котором были отправлены токены загрузки.

Лучшие практики для загрузок

Следующие рекомендации и ресурсы помогут повысить общую эффективность загрузок:

• Следуйте рекомендациям по повторным попыткам и обработке ошибок , учитывая следующие моменты:
  • Ошибки 429 могут возникать, если ваша квота исчерпана или скорость выполнения запросов ограничена из-за слишком большого количества вызовов, выполняемых слишком быстро. Не вызывайте batchCreate для того же пользователя до завершения предыдущего запроса.
  • При ошибках 429 требуется задержка не менее 30s перед повторной попыткой. Используйте стратегию экспоненциальной задержки при повторных попытках запросов.
  • Ошибки 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.

Продолжайте этот процесс до тех пор, пока не будут завершены все загрузки и вызовы по созданию медиафайлов.