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. Esto muestra un token de carga que identifica los bytes subidos.
2. Usa una llamada 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 de carga de un solo elemento multimedia. Si vas a subir varios elementos multimedia (muy probable en cualquier aplicación de producción), revisa las prácticas recomendadas para las cargas para mejorar la eficiencia de las cargas.

Antes de comenzar

Permisos de autorización obligatorios

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

Tipos y tamaños de archivo admitidos

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

Paso 1: Sube bytes

Sube bytes a Google con solicitudes de carga. Una solicitud de carga correcta muestra 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 a 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

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

La API de la Biblioteca de Google Fotos admite cargas reanudables. Una carga reanudable te permite dividir un archivo multimedia en varias secciones y subir una 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. Siempre se agrega un elemento multimedia 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 nuevos elementos multimedia, 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 tiene un límite de 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 archivo, etiquetas programáticas ni otro texto generado automáticamente.

Para obtener el mejor rendimiento, reduce la cantidad de llamadas a mediaItems.batchCreate que debes realizar si incluyes varios elementos multimedia en una sola llamada. Siempre espera hasta 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. Para ello, especifica las descripciones y los tokens de carga correspondientes:

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"
      }
    }
   , ...
  ]
}

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

{
  "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 los álbumes, consulta Agrega enriquecimientos.

Respuesta de creación de elementos

La llamada a mediaItems.batchCreate muestra el resultado de cada uno de los elementos multimedia que intentaste crear. La lista de newMediaItemResults indica el estado y, además, incluye el uploadToken de la solicitud. Un código de estado distinto de cero indica un error.

{
  "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 muestra 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 objeto mediaItem contiene un status dentro de su mediaMetadata que describe el estado de procesamiento del archivo de video. Un archivo subido recientemente muestra primero el estado PROCESSING, antes de que sea READY para su uso. Para obtener más información, 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 quieras hacer un seguimiento de las incorporaciones exitosas, de modo que la imagen se pueda insertar en el álbum en la posición correcta durante la siguiente solicitud. Para obtener más información, consulta Cómo crear álbumes.

Los resultados siempre se devuelven en el mismo orden en el 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 de reintento y manejo de errores, y ten en cuenta los siguientes puntos:
  • Los errores 429 pueden ocurrir cuando se agota tu cuota o cuando se 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 reintentarse. Usa una estrategia de retirada exponencial cuando vuelvas a intentar las solicitudes.
  • Los errores 500 se producen cuando el servidor encuentra un error. Cuando se sube contenido, lo más probable es que esto se deba a que se realizan varias llamadas de escritura (como batchCreate) para el mismo usuario al mismo tiempo. Revisa 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 red, lo que reduce el uso del ancho de banda, ya que te permite reanudar cargas completadas parcialmente. Esto es importante cuando se suben archivos grandes o desde dispositivos móviles del cliente.

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

Carga de bytes

• 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 hagas llamadas en paralelo a batchCreate para un solo usuario.

  • Para cada usuario, realiza llamadas a batchCreate una tras otra (en serie).
  • Para varios usuarios, siempre realiza llamadas de batchCreate para cada uno de ellos. Solo realiza llamadas para usuarios diferentes 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 50 elementos como máximo.

• Establece un texto descriptivo significativo que hayan creado tus usuarios. No incluyas metadatos, como nombres de archivo, 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 (subir bytes sin procesar y crear 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 tus elementos multimedia de todos tus usuarios. Realiza un seguimiento de cada uploadToken que se muestra por usuario. Recuerda estos puntos clave:

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

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.

// 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 llamadas de creación de contenido multimedia.