La carga de elementos multimedia es un proceso de dos pasos:
- Sube los bytes de tus archivos multimedia a un servidor de Google con el extremo de cargas. Se mostrará un token de carga que identifica los bytes subidos.
- Usa una llamada batchCreate con el token de carga para Crear un elemento multimedia en la cuenta de Google Fotos del usuario
Estos pasos describen el proceso de carga de un solo elemento multimedia. Si eres subir varios elementos multimedia (muy probable para cualquier aplicación de producción) Revisa las prácticas recomendadas para las cargas y mejora tus resultados. la eficiencia de carga.
Antes de comenzar
Permisos de autorización obligatorios
Para subir elementos multimedia a la biblioteca o al álbum de un usuario, se requiere lo siguiente:
photoslibrary.appendonly
o el permiso photoslibrary
.
Los elementos multimedia también se pueden crear con el alcance photoslibrary.sharing
. Para
crear elementos con el permiso photoslibrary.sharing
, primero debes crear un
álbum y márcalo como compartido usando shareAlbum
. Luego, puedes crear elementos multimedia
que se comparten con el usuario en el álbum. No puedes crear elementos directamente en
la biblioteca del usuario o en álbumes que tu app no haya compartido.
Al enumerar álbumes, la propiedad isWriteable
indica si tu
aplicación tiene acceso para crear medios en un álbum en particular.
Tipos y tamaños de archivo aceptados
Puedes subir los tipos de archivo que se indican en la siguiente tabla.
Tipo de medio | Tipos de archivo 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 y WMV. | 20 GB |
Paso 1: Sube bytes
Sube bytes a Google mediante solicitudes de carga. Se realizó correctamente una solicitud de carga
devuelve un token de carga en forma de cadena de texto sin procesar. Usar estas cargas
tokens 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 como el tipo de MIME de los bytes que estás subiendo.
Los tipos de MIME comunes incluyen image/jpeg ,
image/png y image/gif .
|
X-Goog-Upload-Protocol |
Debes establecerlo en raw . |
Este es 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 tiene éxito, se generará un token de carga con el siguiente formato:
de una cadena de texto sin procesar, se devuelve como el cuerpo de la respuesta. Para crear contenido multimedia
elementos, usa estas cadenas de texto en la llamada a 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 }
El tamaño de archivo sugerido para las imágenes es inferior a 50 MB. Los archivos de más de 50 MB propensa a problemas de rendimiento.
La API de la Biblioteca de Google Fotos admite cargas reanudables. Un programa de carga 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 contenido multimedia elementos de 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 al nombre de usuario biblioteca. Los elementos multimedia solo pueden agregados a álbumes que creó 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 una carga
token 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 vacaciones”. No incluya metadatos, como nombres de archivo, publicidad programática etiquetas y otro texto generado automáticamente.
Para obtener el mejor rendimiento, reduzca la cantidad de llamadas a mediaItems.batchCreate
que debes hacer incluyendo varios elementos multimedia en una llamada. Esperar siempre
hasta que se haya completado 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:
REST
Este es 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" } } , ... ] }
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 }
Puedes agregar elementos multimedia a la biblioteca y a un álbum especificando el
álbum id
Para obtener más información, consulta
Crear álbumes
Cada álbum puede contener hasta 20,000 elementos multimedia. Solicitudes para crear contenido multimedia fallarán los elementos de un álbum que superen este límite.
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 }
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" } }
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 }
Para obtener más información sobre el posicionamiento en los álbumes, consulta Agrega enriquecimientos.
Respuesta de creación de elementos
La llamada mediaItems.batchCreate
muestra el resultado de cada uno de los elementos multimedia.
que intentaste crear. La lista de newMediaItemResults
indica el estado y
incluye el uploadToken
de la solicitud. Un código de estado distinto de cero indica que
.
REST
Si todos los elementos multimedia se crearon correctamente, la solicitud muestra
Estado de HTTP 200 OK
. Si no se pueden crear algunos elementos
la solicitud muestra el estado HTTP 207 MULTI-STATUS
para indicar
el éxito 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" } } ] }
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(); // ... } }
Si un elemento se agrega correctamente, se muestra una mediaItem
que contiene su
mediaItemId
, productUrl
y mediaMetadata
. Para obtener más información, consulta
Accede 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 procesamiento
estado del archivo de video. Un archivo recién subido muestra el estado PROCESSING
primero, antes de que sea READY
para usar. Para obtener más información, consulta
Accede a elementos multimedia.
Si encuentras un error durante la llamada, sigue las Prácticas recomendadas y vuelve a enviar la solicitud. Recomendamos que realice un seguimiento de las incorporaciones exitosas para que se pueda insertar la imagen al álbum en la posición correcta durante la siguiente solicitud. Para ver más información, consulta Crear álbumes
Los resultados se devuelven siempre en el mismo orden en que los tokens de carga enviados.
Prácticas recomendadas para las cargas
Los siguientes recursos y prácticas recomendadas ayudan a mejorar tu eficiencia general con subidas:
- Usa una de nuestras bibliotecas cliente compatibles.
- Sigue las prácticas recomendadas de reintento y manejo de errores.
teniendo en cuenta los siguientes puntos:
- Los errores
429
pueden ocurrir cuando se aumenta la cuota o tienes un límite de frecuencia por hacer demasiadas llamadas demasiado rápido. Asegúrate de que No debes llamar abatchCreate
para el mismo usuario hasta la fecha anterior. se haya completado la solicitud. - Los errores
429
requieren una demora mínima de30s
antes de reintentarse. Usa un retirada exponencial cuando se reintentan las solicitudes. - Los errores
500
se producen cuando el servidor encuentra un error. Cuando realices una carga, lo más probable es que se deba a que se realizan varias llamadas de escritura (comobatchCreate
) para el mismo usuario al mismo tiempo. Revisa los detalles de tu solicitud y no realices llamadas abatchCreate
en paralelo.
- Los errores
- Usa el flujo de carga reanudable para hacen que tus cargas sean más sólidas en caso de interrupciones de red, lo que reduce de ancho de banda, ya que te permite reanudar las cargas que se completaron en parte. Esto es importante cuando se suben datos desde dispositivos móviles del cliente cuando subas archivos grandes.
Ten en cuenta también las siguientes sugerencias para cada paso del proceso de carga: subir bytes y, luego, crear elementos multimedia.
Sube 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 realices llamadas en paralelo a
batchCreate
para un solo usuario.- Por cada usuario, realiza llamadas a
batchCreate
una tras otra (en serie). - Si tienes varios usuarios, siempre haz llamadas con
batchCreate
para cada uno de ellos tras otra. Solo realiza llamadas para diferentes usuarios en paralelo.
- Por cada usuario, realiza llamadas a
Incluye la mayor cantidad posible de
NewMediaItems
en cada llamada abatchCreate
para minimizar la cantidad total de llamadas que tienes que hacer. Puedes incluir 50 elementos como máximo.Establece un texto descriptivo significativo que crearon tus usuarios. No incluyas metadatos como nombres de archivo, etiquetas programáticas y otro texto generado automáticamente en el description [descripción].
Explicación de ejemplo
En este ejemplo, se usa pseudocódigo para explicar cómo subir elementos multimedia de varios usuarios. El objetivo es describir ambos pasos del proceso de carga (subir archivos sin procesar bytes y la creación de elementos multimedia) y detallar las prácticas recomendadas para crear una carga eficiente y resiliente y la integración de datos.
Paso 1: Sube bytes sin procesar
Primero, crea una cola para subir los bytes sin procesar de tus elementos multimedia de todas tus
usuarios. Realiza un seguimiento de cada uploadToken
que se muestra por usuario. Recuerda estos puntos clave:
- La cantidad de subprocesos de carga simultánea depende de tu sistema en un entorno de nube.
- Considera reordenar la cola de cargas según sea necesario. Por ejemplo, podrías priorizar las cargas según la cantidad de cargas restantes por usuario, una el progreso general de los usuarios y otros requisitos.
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 bytes de múltiples usuarios en paralelo, pero En el paso 2, solo se puede hacer una 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 llamadas de creación de contenido multimedia.