Realiza cargas reanudables

Ir a los conceptos

En esta página, se describe cómo realizar una solicitud de carga reanudable en las API de JSON y XML de Cloud Storage. Este protocolo te permite reanudar una operación de carga luego de que una falla de comunicación haya interrumpido el flujo de datos.

Inicia una sesión de carga reanudable

Para iniciar una sesión de carga reanudable, haz lo siguiente:

API de JSON

  1. Obtén un token de autorización de acceso de OAuth 2.0 Playground. Configura Playground para usar tus propias credenciales de OAuth.
  2. De manera opcional, crea un archivo .json que contenga los metadatos que deseas configurar en el objeto que deseas subir.

  3. Usa cURL para llamar a la API de JSON con una solicitud de objeto POST:

    curl -i -X POST --data-binary @METADATA_LOCATION \
        -H "Authorization: Bearer OAUTH2_TOKEN" \
        -H "Content-Type: application/json" \
        -H "Content-Length: INITIAL_REQUEST_LENGTH" \
        "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=resumable&name=OBJECT_NAME"

    En el ejemplo anterior, se ilustra lo siguiente:

    • METADATA_LOCATION es la ruta de acceso local al archivo JSON que contiene los metadatos opcionales que especificaste en el paso anterior. Si no incluyes un archivo de metadatos, excluye esto, junto con --data-binary @ y el encabezado Content-Type.
    • OAUTH2_TOKEN es el token de acceso que generaste en el paso 1.
    • INITIAL_REQUEST_LENGTH es la cantidad de bytes en el cuerpo de esta solicitud inicial, por ejemplo, 79. No es necesario si usas la codificación de transferencia fragmentada.
    • BUCKET_NAME es el nombre del depósito al que subes el objeto. Por ejemplo, my-bucket.
    • OBJECT_NAME es el nombre nuevo que deseas dar a tu objeto. Por ejemplo, pets/dog.png. Esto no es necesario si incluiste un name en el archivo de metadatos del objeto en el paso 2.

    Si habilitaste el uso compartido de recursos entre dominios, también debes incluir un encabezado Origin en esta solicitud de carga y en las posteriores.

    Los encabezados opcionales que puedes agregar a la solicitud incluyen X-Upload-Content-Type y X-Upload-Content-Length.

    Si la solicitud se completa de forma correcta, la respuesta incluye un código de estado 200.

  4. Guarda el URI de la sesión reanudable que se proporcionó en el encabezado Location de la respuesta a tu solicitud de objeto POST.

    El URI de la sesión comienza con https://storage.googleapis.com/upload/ y termina con un upload_id. Este URI se usa en las solicitudes posteriores para subir los datos del objeto.

API de XML

  1. Obtén un token de autorización de acceso de OAuth 2.0 Playground. Configura Playground para usar tus propias credenciales de OAuth.
  2. Usa cURL para llamar a la API de XML con una solicitud de objeto POST que tenga un cuerpo vacío:

    curl -i -X POST -H "Authorization: Bearer OAUTH2_TOKEN" \
        -H "Content-Length: 0" \
        -H "Content-Type: OBJECT_CONTENT_TYPE" \
        -H "x-goog-resumable: start" \
        "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    En el ejemplo anterior, se ilustra lo siguiente:

    • OAUTH2_TOKEN es el token de acceso que generaste en el paso 1.
    • OBJECT_CONTENT_TYPE es el tipo de contenido del objeto. Por ejemplo, image/png. Si no especificas un tipo de contenido, el sistema de Cloud Storage establece los metadatos Content-Type para que el objeto sea application/octet-stream.
    • BUCKET_NAME es el nombre del depósito al que subes el objeto. Por ejemplo, my-bucket.
    • OBJECT_NAME es el nombre nuevo que deseas darle al objeto. Por ejemplo, pets/dog.png.

    Si habilitaste el uso compartido de recursos entre dominios, también debes incluir un encabezado Origin en esta solicitud de carga y en las posteriores.

    Si la solicitud se completa de forma correcta, la respuesta incluye un mensaje de estado 201.

  3. Guarda el URI de la sesión reanudable que se proporcionó en el encabezado Location de la respuesta a tu solicitud de objeto POST.

    Este URI se usa en las solicitudes posteriores para subir los datos del objeto.

Sube el archivo

Una vez que inicias una carga reanudable, hay dos formas de subir los datos del objeto:

  • En una sola solicitud: este método suele ser el mejor, ya que requiere menos solicitudes y, por lo tanto, tiene un mejor rendimiento.
  • En varios fragmentos: usa este método si necesitas reducir la cantidad de datos transferidos en una sola solicitud, como cuando hay un límite de tiempo fijo para solicitudes individuales, o si no sabes cuál es el tamaño total de la carga en el momento en que se inicia.

Carga en una sola solicitud

Para subir el archivo en una sola solicitud, sigue estos pasos:

API de JSON

  1. Usa cURL para llamar a la API de JSON con una solicitud de objeto PUT:

    curl -i -X PUT --data-binary @OBJECT_LOCATION \
        -H "Content-Length: OBJECT_SIZE" \
        "SESSION_URI"

    En el ejemplo anterior, se ilustra lo siguiente:

    • OBJECT_LOCATION es la ruta de acceso local a tu objeto. Por ejemplo, Desktop/dog.png.
    • OBJECT_SIZE es la cantidad de bytes en el objeto. Por ejemplo, 20000000.
    • SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

API de XML

  1. Usa cURL para llamar a la API de XML con una solicitud de objeto PUT:

    curl -i -X PUT --data-binary @OBJECT_LOCATION \
        -H "Content-Length: OBJECT_SIZE" \
        "SESSION_URI"

    En el ejemplo anterior, se ilustra lo siguiente:

    • OBJECT_LOCATION es la ruta de acceso local a tu objeto. Por ejemplo, Desktop/dog.png.
    • OBJECT_SIZE es la cantidad de bytes en el objeto. Por ejemplo, 20000000.
    • SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

Si la carga se completa en su totalidad, recibirás una respuesta 200 OK o 201 Created, junto con todos los metadatos asociados con el recurso.

Si la solicitud de carga se interrumpe o si recibes una respuesta 5xx, sigue el procedimiento que se describe en Reanuda una carga interrumpida.

Carga en varios fragmentos

Para subir el archivo en varios fragmentos, sigue estos pasos:

API de JSON

  1. Crea un fragmento de datos a partir del archivo que deseas subir.

    El tamaño del fragmento debe ser un múltiplo de 256 KB (256 x 1,024 bytes), a menos que sea el último fragmento que completa la carga. El tamaño del fragmento debe ser lo más grande posible para que la carga sea eficaz.

  2. Usa cURL para llamar a la API de JSON con una solicitud de objeto PUT:

    curl -i -X PUT --data-binary @CHUNK_LOCATION \
        -H "Content-Length: CHUNK_SIZE" \
        -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    En el ejemplo anterior, se ilustra lo siguiente:

    • CHUNK_LOCATION es la ruta de acceso local al fragmento que subes en este momento.
    • CHUNK_SIZE es la cantidad de bytes que subes en la solicitud actual. Por ejemplo, 524288.
    • CHUNK_FIRST_BYTE es el byte inicial en el objeto completo que contiene el fragmento que deseas subir.
    • CHUNK_LAST_BYTE es el byte final del objeto completo que contiene el fragmento que deseas subir.
    • TOTAL_OBJECT_SIZE es el tamaño total del objeto que deseas subir.
    • SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

    Un ejemplo de Content-Range es Content-Range: bytes 0-524287/2000000. Consulta Content-Range para obtener más información sobre este encabezado.

    Si la solicitud se completa de forma correcta, el servidor responde con 308 Resume Incomplete. La respuesta contiene un encabezado Range. Usa el valor superior de este encabezado para determinar dónde comenzar el siguiente fragmento. No debes suponer que el servidor recibió todos los bytes que se enviaron en la solicitud.

  3. Repite los pasos anteriores para cada fragmento restante de los datos que deseas subir.

Una vez que se completa la carga, recibirás una respuesta 200 OK o 201 Created, junto con todos los metadatos asociados al recurso.

Si se interrumpe alguna de las cargas de fragmentos, o si recibes una respuesta 5xx, sigue el procedimiento que se describe en Reanuda una carga interrumpida.

Verifica el estado de una carga reanudable

Si se interrumpe la carga reanudable, o no estás seguro de que se haya completado, puedes verificar su estado:

API de JSON

  1. Usa cURL para llamar a la API de XML con una solicitud de objeto PUT:

    curl -i -X PUT \
        -H "Content-Length: 0" \
        -H "Content-Range: bytes */OBJECT_SIZE" \
        "SESSION_URI"

    En el ejemplo anterior, se ilustra lo siguiente:

    • OBEJCT_SIZE es la cantidad total de bytes en el objeto. Si no sabes cuál es el tamaño completo del objeto, usa * para este valor.
    • SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

API de XML

  1. Usa cURL para llamar a la API de XML con una solicitud de objeto PUT:

    curl -i -X PUT \
        -H "Content-Length: 0" \
        -H "Content-Range: bytes */OBJECT_SIZE" \
        "SESSION_URI"

    En el ejemplo anterior, se ilustra lo siguiente:

    • OBEJCT_SIZE es la cantidad total de bytes en el objeto. Si no sabes cuál es el tamaño completo del objeto, usa * para este valor.
    • SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

Una respuesta 200 OK o 201 Created indica que se completó la carga y que no es necesario realizar ninguna otra acción.

Una respuesta 308 Resume Incomplete indica que debes continuar con la carga del archivo.

  • Si Cloud Storage aún no recibió bytes, la respuesta 308 no tiene un encabezado Range.
  • De lo contrario, la respuesta 308 tiene un encabezado Range, que especifica qué bytes recibió Cloud Storage hasta el momento. Usa este valor cuando reanudes una carga interrumpida.

Reanuda una carga interrumpida

Si una solicitud de carga se interrumpe antes de que recibas una respuesta, o si recibes una respuesta 503500, debes reanudar la carga interrumpida desde el punto en que se detuvo. Para reanudar una carga interrumpida, haz lo siguiente:

API de JSON

  1. Verifica el estado de la carga reanudable.

  2. Guarda el valor superior del encabezado Range que se encuentra en la respuesta a tu verificación de estado. Si la respuesta no tiene un encabezado Range, Cloud Storage aún no recibió ningún byte, y debes reanudar la carga desde el principio.

  3. Asegúrate de que los datos del objeto que estás a punto de subir comiencen en el byte que le sigue al valor superior en el encabezado Range.

  4. Usa cURL para llamar a la API de JSON con una solicitud de objeto PUT que reanude la carga a partir del byte que le sigue al valor en el encabezado Range:

    curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
        -H "Content-Length: UPLOAD_SIZE_REMAINING" \
        -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    En el ejemplo anterior, se ilustra lo siguiente:

    • PARTIAL_OBJECT_LOCATION es la ruta de acceso local a la parte restante de los datos que deseas subir.
    • UPLOAD_SIZE_REMAINING es la cantidad de bytes que subes en la solicitud actual. Por ejemplo, la carga del resto de un objeto con un tamaño total de 20,000,000 que se interrumpió después de haber subido los bytes 0-42 tendría un UPLOAD_SIZE_REMAINING de 1999957.
    • NEXT_BYTE es el siguiente número entero después del valor que guardaste en el paso 2. Por ejemplo, si 42 es el valor superior en el paso 2, el valor de NEXT_BYTE es 43.
    • LAST_BYTE es el byte final que contiene esta solicitud PUT. Por ejemplo, para terminar de subir un objeto cuyo tamaño total es 20000000, el valor de LAST_BYTE es 1999999.
    • TOTAL_OBJECT_SIZE es el tamaño total del objeto que deseas subir. Por ejemplo, 20000000.
    • SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

API de XML

  1. Verifica el estado de la carga reanudable.

  2. Guarda el valor superior del encabezado Range que se encuentra en la respuesta a tu verificación de estado. Si la respuesta no tiene un encabezado Range, Cloud Storage aún no recibió ningún byte, y debes reanudar la carga desde el principio.

  3. Asegúrate de que los datos del objeto que estás a punto de subir comiencen en el byte que le sigue al valor superior en el encabezado Range.

  4. Usa cURL para llamar a la API de XML con una solicitud de objeto PUT que reanude la carga a partir del byte que le sigue al valor en el encabezado Range:

    curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
        -H "Content-Length: UPLOAD_SIZE_REMAINING" \
        -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    En el ejemplo anterior, se ilustra lo siguiente:

    • PARTIAL_OBJECT_LOCATION es la ruta de acceso local a la parte restante de los datos que deseas subir.
    • UPLOAD_SIZE_REMAINING es la cantidad de bytes que subes en la solicitud actual. Por ejemplo, la carga del resto de un objeto con un tamaño total de 20,000,000 que se interrumpió después de haber subido los bytes 0-42 tendría un UPLOAD_SIZE_REMAINING de 1999957.
    • NEXT_BYTE es el siguiente número entero después del valor que guardaste en el paso 2. Por ejemplo, si 42 es el valor superior en el paso 2, el valor de NEXT_BYTE es 43.
    • LAST_BYTE es el byte final que contiene esta solicitud PUT. Por ejemplo, para terminar de subir un objeto cuyo tamaño total es 20000000, el valor de LAST_BYTE es 1999999.
    • TOTAL_OBJECT_SIZE es el tamaño total del objeto que deseas subir. Por ejemplo, 20000000.
    • SESSION_URI es el valor que se mostró en el encabezado Location cuando iniciaste la carga reanudable.

Puedes reanudar las cargas las veces que sea necesario, pero cuando vuelvas a enviar las solicitudes, usa la retirada exponencial truncada.

Cuando el archivo se sube de forma correcta, Cloud Storage responde con un código de estado 200 OK o 201 created.

Obtén más información sobre la optimización opcional.

Cancela una carga

Para cancelar una carga reanudable y evitar que se realicen más acciones, sigue estos pasos:

API de JSON

  1. Usa cURL para llamar a la API de JSON con una solicitud DELETE:

    curl -X DELETE -H "Content-Length: 0" \
      "SESSION_URI"

    En el ejemplo anterior, se ilustra lo siguiente:

API de XML

  1. Usa cURL para llamar a la API de XML con una solicitud DELETE:

    curl -X DELETE -H "Content-Length: 0" \
      "SESSION_URI"

    En el ejemplo anterior, se ilustra lo siguiente:

Si la solicitud se completa de forma correcta, la respuesta contendrá un código de estado 499. Los intentos posteriores de consultar o reanudar la carga generarán una respuesta 4xx.

Próximos pasos