Cargar medios

La carga de elementos multimedia es un proceso de dos pasos:

  1. Sube los bytes de tus archivos multimedia a un servidor de Google con el extremo de cargas. Devuelve un token de carga que identifica los bytes cargados.
  2. Usa una llamada a batchCreate con el token de carga para crear un elemento multimedia en la cuenta de Google Fotos del usuario.

En estos pasos, se describe el proceso para subir un solo elemento multimedia. Si subes varios elementos multimedia (lo que es muy probable para cualquier aplicación de producción), revisa las prácticas recomendadas para las cargas y mejora la eficiencia de tus cargas.

Antes de comenzar

Permisos de autorización obligatorios

Para subir elementos multimedia a la biblioteca o el álbum de un usuario, se requiere el alcance de photoslibrary.appendonly. Para obtener más información sobre los permisos, consulta Permisos de autorización.

Tipos y tamaños de archivo aceptados

Puedes subir los tipos de archivos que se indican en esta tabla.

Tipo de medio Tipos de archivos aceptados Tamaño máximo del archivo
Fotos AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP y algunos archivos RAW 200 MB
Videos 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD, WMV. 20 GB

Paso 1: Subir bytes

Sube bytes a Google con solicitudes de carga. Una solicitud de carga exitosa devuelve un token de carga en forma de una cadena de texto sin procesar. Usa estos tokens de carga para crear elementos multimedia con la llamada batchCreate.

REST

Incluye los siguientes campos en el encabezado de la solicitud POST:

Campos de encabezado
Content-type Debes establecerlo en application/octet-stream.
X-Goog-Upload-Content-Type Es la opción recomendada. Se establece en el tipo de MIME de los bytes que subes. Los tipos de MIME comunes incluyen image/jpeg, image/png y image/gif.
X-Goog-Upload-Protocol Debes establecerlo en raw.

A continuación, se muestra un encabezado de solicitud 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

En el cuerpo de la solicitud, incluye el objeto binario del archivo: 

media-binary-data

Si esta solicitud POST se realiza correctamente, se muestra un token de carga en forma de cadena de texto sin procesar como cuerpo de la respuesta. Para crear elementos multimedia, usa estas cadenas de texto en la llamada a batchCreate.

upload-token

El tamaño de archivo sugerido para las imágenes es inferior a 50 MB. Los archivos de más de 50 MB son propensos a problemas de rendimiento.

La API de Google Photos Library admite cargas reanudables. Una carga reanudable te permite dividir un archivo multimedia en varias secciones y subir una sección a la vez.

Paso 2: Crea un elemento multimedia

Después de subir los bytes de tus archivos multimedia, puedes crearlos como elementos multimedia en Google Fotos con tokens de carga. Un token de carga es válido durante un día después de su creación. Un elemento multimedia siempre se agrega a la biblioteca del usuario. Los elementos multimedia solo se pueden agregar a los álbumes creados por tu app. Para obtener más información, consulta Permisos de autorización.

Para crear elementos multimedia nuevos, llama a mediaItems.batchCreate especificando una lista de newMediaItems. Cada newMediaItem contiene un token de carga que se especifica dentro de un simpleMediaItem y una descripción opcional que se muestra al usuario.

El campo de descripción está restringido a 1,000 caracteres y solo debe incluir texto significativo creado por los usuarios. Por ejemplo, "Nuestro viaje al parque" o "Cena de Navidad". No incluyas metadatos, como nombres de archivos, etiquetas programáticas ni otro texto generado automáticamente.

Para obtener el mejor rendimiento, incluye varios elementos multimedia en una sola llamada para reducir la cantidad de llamadas que debes realizar a mediaItems.batchCreate. Siempre espera a que se complete la solicitud anterior antes de realizar una llamada posterior para el mismo usuario.

Puedes crear uno o varios elementos multimedia en la biblioteca de un usuario especificando las descripciones y los tokens de carga correspondientes:

REST

A continuación, se muestra el encabezado de la solicitud POST:

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

El cuerpo de la solicitud debe especificar una lista de newMediaItems.

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

También puedes especificar albumId y albumPosition para insertar elementos multimedia en una ubicación específica del álbum.

REST

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

Para obtener más detalles sobre el posicionamiento en álbumes, consulta Cómo agregar enriquecimientos.

Respuesta de creación del elemento

La llamada a mediaItems.batchCreate devuelve el resultado de cada uno de los elementos multimedia que intentaste crear. La lista de newMediaItemResults indica el estado y también incluye el uploadToken de la solicitud. Un código de estado distinto de cero indica un error.

REST

Si todos los elementos multimedia se crearon correctamente, la solicitud devuelve el estado HTTP 200 OK. Si no se pueden crear algunos elementos multimedia, la solicitud devuelve el estado HTTP 207 MULTI-STATUS para indicar que la operación se realizó correctamente de forma parcial.

{
  "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"
      }
    }
  ]
}

Si se agrega un elemento correctamente, se devuelve un mediaItem que contiene su mediaItemId, productUrl y mediaMetadata. Para obtener más información, consulta Cómo acceder a elementos multimedia.

Si el elemento multimedia es un video, primero se debe procesar. El mediaItem contiene un status dentro de su mediaMetadata que describe el estado de procesamiento del archivo de video. Un archivo recién subido primero devuelve el estado PROCESSING antes de estar READY para su uso. Para obtener más detalles, consulta Cómo acceder a elementos multimedia.

Si encuentras un error durante esta llamada, sigue las Prácticas recomendadas y vuelve a intentar la solicitud. Es posible que desees hacer un seguimiento de las adiciones exitosas para que la imagen se pueda insertar en el álbum en la posición correcta durante la próxima solicitud. Para obtener más información, consulta Crea álbumes.

Los resultados siempre se devuelven en el mismo orden en que se enviaron los tokens de carga.

Prácticas recomendadas para las cargas

Las siguientes prácticas recomendadas y recursos te ayudarán a mejorar tu eficiencia general con las cargas:

  • Sigue las prácticas recomendadas para el reintento y el control de errores, teniendo en cuenta los siguientes puntos:
    • Los errores de 429 pueden ocurrir cuando se agotó tu cuota o cuando se te aplica un límite de frecuencia por realizar demasiadas llamadas con demasiada rapidez. Asegúrate de no llamar a batchCreate para el mismo usuario hasta que se complete la solicitud anterior.
    • Los errores 429 requieren una demora mínima de 30s antes de reintentar. Usa una estrategia de retirada exponencial cuando reintentes solicitudes.
    • Los errores 500 se producen cuando el servidor encuentra un error. Cuando se sube, lo más probable es que se deba a que se realizan varias llamadas de escritura (como batchCreate) para el mismo usuario al mismo tiempo. Verifica los detalles de tu solicitud y no realices llamadas a batchCreate en paralelo.
  • Usa el flujo de carga reanudable para que tus cargas sean más sólidas en caso de interrupciones de la red, lo que reduce el uso de ancho de banda, ya que te permite reanudar las cargas completadas parcialmente. Esto es importante cuando se suben archivos desde dispositivos móviles del cliente o cuando se suben archivos grandes.

Además, ten en cuenta las siguientes sugerencias para cada paso del proceso de carga: carga de bytes y, luego, creación de elementos multimedia.

Bytes subidos

  • La carga de bytes (para recuperar tokens de carga) se puede realizar en paralelo.
  • Siempre establece el tipo de MIME correcto en el encabezado X-Goog-Upload-Content-Type para cada llamada de carga.

Cómo crear elementos multimedia

  • No realices llamadas en paralelo a batchCreate para un solo usuario.

    • Para cada usuario, realiza llamadas a batchCreate una tras otra (en serie).
    • En el caso de varios usuarios, siempre realiza llamadas a batchCreate para cada usuario una tras otra. Solo realiza llamadas para diferentes usuarios en paralelo.

  • Incluye la mayor cantidad posible de NewMediaItems en cada llamada a batchCreate para minimizar la cantidad total de llamadas que debes realizar. Puedes incluir hasta 50 elementos.

  • Establece un texto de descripción significativo que hayan creado tus usuarios. No incluyas metadatos, como nombres de archivos, etiquetas programáticas ni otro texto generado automáticamente en el campo de descripción.

Ejemplo de explicación

En este ejemplo, se usa pseudocódigo para explicar cómo subir elementos multimedia para varios usuarios. El objetivo es describir ambos pasos del proceso de carga (carga de bytes sin procesar y creación de elementos multimedia) y detallar las prácticas recomendadas para crear una integración de carga eficiente y resiliente.

Paso 1: Sube bytes sin procesar

Primero, crea una fila para subir los bytes sin procesar de los elementos multimedia de todos tus usuarios. Haz un seguimiento de cada uploadToken devuelto por usuario. Recuerda estos puntos clave:

  • La cantidad de subprocesos de carga simultáneos depende de tu entorno operativo.
  • Considera reordenar la cola de carga según sea necesario. Por ejemplo, podrías priorizar las cargas según la cantidad de cargas restantes por usuario, el progreso general de un usuario o cualquier otro requisito.

Pseudocódigo

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

Paso 2: Crea elementos multimedia

En el paso 1, puedes subir varios bytes de varios usuarios en paralelo, pero en el paso 2, solo puedes realizar una sola llamada para cada usuario a la vez.

Pseudocódigo

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

Continúa con este proceso hasta que se completen todas las cargas y las llamadas de creación de contenido multimedia.