Android SDK resumable upload sample code - Object Storage Service

Le téléchargement de fichiers volumineux via un réseau sans fil peut prendre beaucoup de temps. Une connexion réseau instable ou un changement de réseau peuvent entraîner l'échec du téléchargement, vous obligeant à le recommencer depuis le début. Le kit de développement logiciel (SDK) Android propose une fonctionnalité de téléchargement avec reprise pour résoudre ce problème.

Notes d'utilisation

Le SDK OSS pour Android fournit les méthodes suivantes pour effectuer un téléchargement avec reprise : resumableUpload et sequenceUpload.

(Recommandé) resumableUpload permet le téléchargement parallèle de plusieurs parties. Jusqu'à cinq parties peuvent être téléchargées simultanément.
sequenceUpload spécifie que les parties sont téléchargées séquentiellement. La partie suivante est téléchargée une fois la précédente terminée.

Dans cette rubrique, l'exemple de code illustre uniquement l'utilisation de la méthode resumableUpload. Pour télécharger plusieurs objets avec reprise, vous devez créer plusieurs requêtes resumableUpload.

Remarques importantes

Avant d'exécuter l'exemple de code présenté dans cette rubrique, vous devez créer une instance OSSClient en utilisant des méthodes telles qu'un nom de domaine personnalisé ou le Security Token Service (STS). Pour plus d'informations, consultez Initialisation (SDK Android).

Il est déconseillé d'utiliser le téléchargement avec reprise pour des objets inférieurs à 5 Go sur un appareil mobile. Cette fonctionnalité s'appuie sur le téléchargement multipartite, qui nécessite plusieurs requêtes réseau pour un seul objet, ce qui s'avère inefficace. Lors du téléchargement avec reprise d'un objet supérieur à 5 Go, tenez compte des points suivants :

Avant le téléchargement avec reprise

Avant de télécharger un objet vers OSS avec reprise, vous pouvez spécifier un répertoire pour le fichier de point de contrôle (checkpoint) qui enregistre la progression du téléchargement. Ce fichier ne s'applique qu'à la tâche de téléchargement en cours.
- Si vous ne spécifiez pas de répertoire pour le fichier de point de contrôle et qu'une partie d'un objet volumineux échoue en raison de problèmes réseau, le re-téléchargement complet de l'objet prendra beaucoup de temps et consommera une quantité importante de trafic.
- Si vous spécifiez le répertoire du fichier de point de contrôle, une tâche de téléchargement interrompue pourra reprendre exactement là où elle s'était arrêtée, selon les informations enregistrées dans ce fichier.
Pendant le téléchargement avec reprise
- Le téléchargement avec reprise concerne uniquement les fichiers locaux. Il prend en charge la fonctionnalité de rappel (callback), utilisée de la même manière que pour les tâches de téléchargement standard. Pour plus d'informations, consultez Rappel.
- Le téléchargement avec reprise fait appel aux opérations API suivantes : InitMultipartUpload, UploadPart, ListParts, CompleteMultipartUpload et AbortMultipartUpload. Si vous utilisez le Security Token Service (STS), assurez-vous d'être autorisé à appeler ces opérations.
- Par défaut, la validation MD5 est activée pour chaque partie lors d'un téléchargement avec reprise. Vous n'avez donc pas besoin de définir l'en-tête Content-Md5 dans la requête.
- Si une tâche de téléchargement avec reprise échoue et n'est pas finalisée, les parties déjà téléchargées deviennent inutiles dans OSS. Pour gérer cela, configurez des règles de cycle de vie sur le bucket contenant ces parties afin de les supprimer régulièrement. Pour plus d'informations, consultez Configurer des règles de cycle de vie.

Exemples

Vous pouvez télécharger un fichier local vers OSS de manière synchrone ou asynchrone en utilisant le téléchargement avec reprise.

Méthodes synchrones

L'exemple de code suivant montre comment télécharger de manière synchrone un fichier local nommé examplefile.txt vers le répertoire exampledir du bucket examplebucket. Une fois le fichier local téléchargé, l'objet sera nommé exampleobject.txt. Le fichier de point de contrôle est stocké sur votre ordinateur.

// Specify the bucket name, for example, examplebucket.
String bucketName = "examplebucket";
// Specify the full path of the object, for example, exampledir/exampleobject.txt. The full path cannot contain the bucket name.
String objectName = "exampledir/exampleobject.txt";
// Specify the full path of the file, for example, /storage/emulated/0/oss/examplefile.txt.
String localFilepath = "/storage/emulated/0/oss/examplefile.txt";

String recordDirectory = Environment.getExternalStorageDirectory().getAbsolutePath() + "/oss_record/";

File recordDir = new File(recordDirectory);

// Make sure that the folder to save the breakpoint record exists. If the folder does not exist, create it.
if (!recordDir.exists()) {
    recordDir.mkdirs();
}

// Create a resumable upload request and specify the path to save the breakpoint record file. The path must be an absolute path.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath, recordDirectory);
// When you call the OSSAsyncTask cancel() method, set DeleteUploadOnCancelling to false. This setting prevents the deletion of the breakpoint record file. The next time you upload the same file, the upload resumes from the breakpoint. If you do not set this parameter, the default value is true, which deletes the breakpoint record file. The next time you upload the same file, the upload starts from the beginning.
request.setDeleteUploadOnCancelling(false);
// Set the upload callback.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
    @Override
    public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
        Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
    }
});

ResumableUploadResult uploadResult = oss.resumableUpload(request);

L'exemple de code suivant montre comment utiliser l'URI d'un fichier pour le télécharger vers OSS dans le cadre du stockage étendu (scoped storage) sur Android 10 ou version ultérieure :

// Specify the bucket name, for example, examplebucket.
String bucketName = "examplebucket";
// Specify the full path of the object, for example, exampledir/exampleobject.txt. The full path cannot contain the bucket name.
String objectName = "exampledir/exampleobject.txt";

String recordDirectory = getApplication().getFilesDir().getAbsolutePath() + "/oss_record/";

File recordDir = new File(recordDirectory);

// Make sure that the folder to save the breakpoint record exists. If the folder does not exist, create it.
if (!recordDir.exists()) {
    recordDir.mkdirs();
}

// Create a resumable upload request and specify the path to save the breakpoint record file. The path must be an absolute path.
// The "fileUri" parameter must be set to the actual URI of the file.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, fileUri, recordDirectory);
// When you call the OSSAsyncTask cancel() method, set DeleteUploadOnCancelling to false. This setting prevents the deletion of the breakpoint record file. The next time you upload the same file, the upload resumes from the breakpoint. If you do not set this parameter, the default value is true, which deletes the breakpoint record file. The next time you upload the same file, the upload starts from the beginning.
request.setDeleteUploadOnCancelling(false);
// Set the upload callback.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
    @Override
    public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
        Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
    }
});

ResumableUploadResult uploadResult = oss.resumableUpload(request);

L'exemple de code suivant montre comment effectuer un téléchargement avec reprise sans stocker le fichier de point de contrôle sur votre ordinateur :

// Specify the bucket name, for example, examplebucket.
String bucketName = "examplebucket";
// Specify the full path of the object, for example, exampledir/exampleobject.txt. The full path cannot contain the bucket name.
String objectName = "exampledir/exampleobject.txt";
// Specify the full path of the file, for example, /storage/emulated/0/oss/examplefile.txt.
String localFilepath = "/storage/emulated/0/oss/examplefile.txt";

// Create a resumable upload request.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath);
// Set the upload callback.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
    @Override
    public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
        Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
    }
});

ResumableUploadResult uploadResult = oss.resumableUpload(request);

Méthode asynchrone

L'exemple de code suivant montre comment télécharger de manière asynchrone un fichier local nommé examplefile.txt vers le répertoire exampledir du bucket examplebucket. Une fois le fichier local téléchargé, l'objet sera nommé exampleobject.txt. Le fichier de point de contrôle est stocké sur votre ordinateur.

// Specify the bucket name, for example, examplebucket.
String bucketName = "examplebucket";
// Specify the full path of the object, for example, exampledir/exampleobject.txt. The full path cannot contain the bucket name.
String objectName = "exampledir/exampleobject.txt";
// Specify the full path of the file, for example, /storage/emulated/0/oss/examplefile.txt.
String localFilepath = "/storage/emulated/0/oss/examplefile.txt";
String recordDirectory = Environment.getExternalStorageDirectory().getAbsolutePath() + "/oss_record/";

File recordDir = new File(recordDirectory);

// Make sure that the path to save the breakpoint record exists. If the path does not exist, create it.
if (!recordDir.exists()) {
    recordDir.mkdirs();
}

// Create a resumable upload request and specify the path to save the breakpoint record file. The path must be an absolute path.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath, recordDirectory);
// When you call the OSSAsyncTask cancel() method, set DeleteUploadOnCancelling to false. This setting prevents the deletion of the breakpoint record file. The next time you upload the same file, the upload resumes from the breakpoint. If you do not set this parameter, the default value is true, which deletes the breakpoint record file. The next time you upload the same file, the upload starts from the beginning.
request.setDeleteUploadOnCancelling(false);
// Set the upload progress callback.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
    @Override
    public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
        Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
    }
});

OSSAsyncTask resumableTask = oss.asyncResumableUpload(request, new OSSCompletedCallback<ResumableUploadRequest, ResumableUploadResult>() {
    @Override
    public void onSuccess(ResumableUploadRequest request, ResumableUploadResult result) {
        Log.d("resumableUpload", "success!");
    }

    @Override
    public void onFailure(ResumableUploadRequest request, ClientException clientExcepion, ServiceException serviceException) {
        // Handle exceptions.
    }
});

// Wait for the resumable upload task to complete.
resumableTask.waitUntilFinished();

L'exemple de code suivant montre comment utiliser l'URI d'un fichier pour le télécharger vers OSS dans le cadre du stockage étendu (scoped storage) sur Android 10 ou version ultérieure :

// Specify the bucket name, for example, examplebucket.
String bucketName = "examplebucket";
// Specify the full path of the object, for example, exampledir/exampleobject.txt. The full path cannot contain the bucket name.
String objectName = "exampledir/exampleobject.txt";
String recordDirectory = getApplication().getFilesDir().getAbsolutePath() + "/oss_record/";

File recordDir = new File(recordDirectory);

// Make sure that the folder to save the breakpoint record exists. If the folder does not exist, create it.
if (!recordDir.exists()) {
    recordDir.mkdirs();
}

// Create a resumable upload request and specify the path to save the breakpoint record file. The path must be an absolute path.
// The "fileUri" parameter must be set to the actual URI of the file.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, fileUri, recordDirectory);
// When you call the OSSAsyncTask cancel() method, set DeleteUploadOnCancelling to false. This setting prevents the deletion of the breakpoint record file. The next time you upload the same file, the upload resumes from the breakpoint. If you do not set this parameter, the default value is true, which deletes the breakpoint record file. The next time you upload the same file, the upload starts from the beginning.
request.setDeleteUploadOnCancelling(false);
// Set the upload callback.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
    @Override
    public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
        Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
    }
});

OSSAsyncTask resumableTask = oss.asyncResumableUpload(request, new OSSCompletedCallback<ResumableUploadRequest, ResumableUploadResult>() {
    @Override
    public void onSuccess(ResumableUploadRequest request, ResumableUploadResult result) {
        Log.d("resumableUpload", "success!");
    }

    @Override
    public void onFailure(ResumableUploadRequest request, ClientException clientExcepion, ServiceException serviceException) {
        // Handle exceptions.
    }
});

// Wait for the resumable upload task to complete.
resumableTask.waitUntilFinished();

L'exemple de code suivant montre comment effectuer un téléchargement avec reprise sans stocker le fichier de point de contrôle sur votre ordinateur :

// Specify the bucket name, for example, examplebucket.
String bucketName = "examplebucket";
// Specify the full path of the object, for example, exampledir/exampleobject.txt. The full path cannot contain the bucket name.
String objectName = "exampledir/exampleobject.txt";
// Specify the full path of the file, for example, /storage/emulated/0/oss/examplefile.txt.
String localFilepath = "/storage/emulated/0/oss/examplefile.txt";

// Create a resumable upload request.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath);

// Set the upload progress callback.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
    @Override
    public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
        Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
    }
});
// Asynchronously call the resumable upload method.
OSSAsyncTask resumableTask = oss.asyncResumableUpload(request, new OSSCompletedCallback<ResumableUploadRequest, ResumableUploadResult>() {
    @Override
    public void onSuccess(ResumableUploadRequest request, ResumableUploadResult result) {
        Log.d("resumableUpload", "success!");
    }

    @Override
    public void onFailure(ResumableUploadRequest request, ClientException clientExcepion, ServiceException serviceException) {
        // Handle exceptions.
    }
});

// Wait for the resumable upload task to complete.
resumableTask.waitUntilFinished();

Références

Pour plus d'informations sur la configuration des règles de cycle de vie d'un bucket, consultez Configurer des règles de cycle de vie.
Pour plus d'informations sur la mise en œuvre d'un rappel (callback) lors d'un téléchargement avec reprise, consultez Rappel.
Pour plus d'informations sur l'initialisation d'une instance OSSClient, consultez Initialisation.