在 Android 上上传文件

Cloud Storage 可让开发者向 Firebase 提供和管理的 Google Cloud Storage 存储分区快速轻松地上传文件。

上传文件

要将文件上传到 Cloud Storage,首先要创建对文件的完整路径(包括文件名)的引用。

// Create a storage reference from our app
StorageReference storageRef = storage.getReference();

// Create a reference to "mountains.jpg"
StorageReference mountainsRef = storageRef.child("mountains.jpg");

// Create a reference to 'images/mountains.jpg'
StorageReference mountainImagesRef = storageRef.child("images/mountains.jpg");

// While the file names are the same, the references point to different files
mountainsRef.getName().equals(mountainImagesRef.getName());    // true
mountainsRef.getPath().equals(mountainImagesRef.getPath());    // false

创建适当的引用后,您可以调用 putBytes()putFile()putStream() 方法将文件上传到 Cloud Storage。

您无法通过对您的 Google Cloud Storage 存储分区根目录的引用来上传数据。您的引用必须指向一个子网址。

通过内存中的数据上传

putBytes() 方法是将文件上传到 Cloud Storage 的最简单方法。putBytes() 需要一个 byte[] 并返回 UploadTask,您可以用它来管理和监控上传状态。

// Get the data from an ImageView as bytes
imageView.setDrawingCacheEnabled(true);
imageView.buildDrawingCache();
Bitmap bitmap = ((BitmapDrawable) imageView.getDrawable()).getBitmap();
ByteArrayOutputStream baos = new ByteArrayOutputStream();
bitmap.compress(Bitmap.CompressFormat.JPEG, 100, baos);
byte[] data = baos.toByteArray();

UploadTask uploadTask = mountainsRef.putBytes(data);
uploadTask.addOnFailureListener(new OnFailureListener() {
    @Override
    public void onFailure(@NonNull Exception exception) {
        // Handle unsuccessful uploads
    }
}).addOnSuccessListener(new OnSuccessListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onSuccess(UploadTask.TaskSnapshot taskSnapshot) {
        // taskSnapshot.getMetadata() contains file metadata such as size, content-type, etc.
        // ...
    }
});

由于 putBytes() 接受了 byte[],因此它需要应用立即将文件的全部内容保存在内存中。请考虑使用 putStream()putFile() 以使用较少的内存。

通过数据流上传

putStream() 方法是将文件上传到 Cloud Storage 最通用的方法。putStream() 接受了 InputStream 并返回 UploadTask,您可以使用它来管理和监控上传状态。

InputStream stream = new FileInputStream(new File("path/to/images/rivers.jpg"));

uploadTask = mountainsRef.putStream(stream);
uploadTask.addOnFailureListener(new OnFailureListener() {
    @Override
    public void onFailure(@NonNull Exception exception) {
        // Handle unsuccessful uploads
    }
}).addOnSuccessListener(new OnSuccessListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onSuccess(UploadTask.TaskSnapshot taskSnapshot) {
        // taskSnapshot.getMetadata() contains file metadata such as size, content-type, etc.
        // ...
    }
});

通过本地文件上传

您可以使用 putFile() 方法上传设备上的本地文件,例如相机中的照片和视频。putFile() 需要一个 File 并返回 UploadTask,您可以使用它来管理和监控上传状态。

Uri file = Uri.fromFile(new File("path/to/images/rivers.jpg"));
StorageReference riversRef = storageRef.child("images/"+file.getLastPathSegment());
uploadTask = riversRef.putFile(file);

// Register observers to listen for when the download is done or if it fails
uploadTask.addOnFailureListener(new OnFailureListener() {
    @Override
    public void onFailure(@NonNull Exception exception) {
        // Handle unsuccessful uploads
    }
}).addOnSuccessListener(new OnSuccessListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onSuccess(UploadTask.TaskSnapshot taskSnapshot) {
        // taskSnapshot.getMetadata() contains file metadata such as size, content-type, etc.
        // ...
    }
});

获取下载网址

上传文件后,您可以对 StorageReference 调用 getDownloadUrl() 方法,获取下载文件的网址:

final StorageReference ref = storageRef.child("images/mountains.jpg");
uploadTask = ref.putFile(file);

Task<Uri> urlTask = uploadTask.continueWithTask(new Continuation<UploadTask.TaskSnapshot, Task<Uri>>() {
    @Override
    public Task<Uri> then(@NonNull Task<UploadTask.TaskSnapshot> task) throws Exception {
        if (!task.isSuccessful()) {
            throw task.getException();
        }

        // Continue with the task to get the download URL
        return ref.getDownloadUrl();
    }
}).addOnCompleteListener(new OnCompleteListener<Uri>() {
    @Override
    public void onComplete(@NonNull Task<Uri> task) {
        if (task.isSuccessful()) {
            Uri downloadUri = task.getResult();
        } else {
            // Handle failures
            // ...
        }
    }
});

添加文件元数据

在上传文件时,您还可以包括元数据。此元数据包含常见的文件元数据属性,如 namesizecontentType(通常称为 MIME 类型)。putFile() 方法自动从 File 扩展名推断 MIME 类型,但您可以通过在元数据中指定 contentType 来替换自动检测到的类型。如果您未提供 contentType,并且 Cloud Storage 无法从文件扩展名推断出默认值,Cloud Storage 将使用 application/octet-stream。如需了解文件元数据的详情,请参阅使用文件元数据部分。

// Create file metadata including the content type
StorageMetadata metadata = new StorageMetadata.Builder()
        .setContentType("image/jpg")
        .build();

// Upload the file and metadata
uploadTask = storageRef.child("images/mountains.jpg").putFile(file, metadata);

管理上传

除了启动上传外,您还可以使用 pause()resume()cancel() 方法暂停、恢复和取消上传。暂停和恢复事件分别会引起 pauseprogress 状态变化。取消上传会导致上传失败,并显示一个错误,指示上传被取消。

uploadTask = storageRef.child("images/mountains.jpg").putFile(file);

// Pause the upload
uploadTask.pause();

// Resume the upload
uploadTask.resume();

// Cancel the upload
uploadTask.cancel();

监控上传进度

您可以添加侦听器来处理上传任务中的成功、失败、进度或暂停:

侦听器类型 典型用法
OnProgressListener 此侦听器将在数据传输时定期调用,可用于填充上传/下载指示符。
OnPausedListener 此侦听器将在任务暂停时调用。
OnSuccessListener 此侦听器将在任务成功完成时调用。
OnFailureListener 此侦听器将在上传失败时调用。网络超时、授权失败或取消任务时可能会发生此事件。

OnFailureListener 是通过 Exception 实例调用的。其他侦听器则是通过 UploadTask.TaskSnapshot 对象调用的。此对象是事件发生时的任务视图,该视图不可改变。UploadTask.TaskSnapshot 包含以下属性:

属性 类型 说明
getDownloadUrl String 可用于下载对象的网址。这是一个公共可知的网址,可以与其他客户端共享。上传完成后,就会使用此值进行填充。
getError Exception 如果任务失败,其原因是发生了异常。
getBytesTransferred long 生成此快照时已传输的总字节数。
getTotalByteCount long 期望上传的总字节数。
getUploadSessionUri String 可以通过对 putFile 的另一个调用来继续此任务的 URI。
getMetadata StorageMetadata 在上传完成之前,其是发送到服务器的元数据。上传完成后,其是服务器返回的元数据。
getTask UploadTask 创建此快照的任务。使用此任务可以取消、暂停或恢复上传。
getStorage StorageReference 用于创建 UploadTaskStorageReference

UploadTask 事件侦听器提供了一种简单而强大的方法来监控上传事件。

// Observe state change events such as progress, pause, and resume
uploadTask.addOnProgressListener(new OnProgressListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onProgress(UploadTask.TaskSnapshot taskSnapshot) {
        double progress = (100.0 * taskSnapshot.getBytesTransferred()) / taskSnapshot.getTotalByteCount();
        System.out.println("Upload is " + progress + "% done");
    }
}).addOnPausedListener(new OnPausedListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onPaused(UploadTask.TaskSnapshot taskSnapshot) {
        System.out.println("Upload is paused");
    }
});

处理 Activity 生命周期变更

即使 Activity 生命周期发生变化(例如显示对话框或旋转屏幕),下载也将继续在后台进行。您连接的任何侦听器也都会保持连接状态。如果在 Activity 停止后调用这些侦听器,会产生意外结果。

向 Activity 作用域订阅您的侦听器,以便在 Activity 停止时自动注销它们,通过这种方式可以解决此问题。然后,在 Activity 重新启动后使用 getActiveUploadTasks 方法获取仍在进行或刚刚完成的上传任务。

下面的示例演示了这一操作,还显示了如何保留使用的存储引用路径。

@Override
protected void onSaveInstanceState(Bundle outState) {
    super.onSaveInstanceState(outState);

    // If there's an upload in progress, save the reference so you can query it later
    if (mStorageRef != null) {
        outState.putString("reference", mStorageRef.toString());
    }
}

@Override
protected void onRestoreInstanceState(Bundle savedInstanceState) {
    super.onRestoreInstanceState(savedInstanceState);

    // If there was an upload in progress, get its reference and create a new StorageReference
    final String stringRef = savedInstanceState.getString("reference");
    if (stringRef == null) {
        return;
    }
    mStorageRef = FirebaseStorage.getInstance().getReferenceFromUrl(stringRef);

    // Find all UploadTasks under this StorageReference (in this example, there should be one)
    List tasks = mStorageRef.getActiveUploadTasks();
    if (tasks.size() > 0) {
        // Get the task monitoring the upload
        UploadTask task = tasks.get(0);

        // Add new listeners to the task using an Activity scope
        task.addOnSuccessListener(this, new OnSuccessListener() {
            @Override
            public void onSuccess(UploadTask.TaskSnapshot state) {
                // Success!
                // ...
            }
        });
    }
}

getActiveUploadTasks 在提供的引用中检索所有活动上传任务,因此您可能需要处理多个任务。

通过重新启动进程继续上传

如果您的进程关闭,则正在进行的任何上传都将中断。但是,通过恢复与服务器的上传会话,您可以在进程重新启动后继续上传。通过不从文件开头部分开始上传,可以节省时间和带宽。

为此,请通过 putFile 开始上传。在生成的 StorageTask 中,调用 getUploadSessionUri 并将生成的值保存在永久存储空间(如 SharedPreferences)中。

uploadTask = mStorageRef.putFile(localFile);
uploadTask.addOnProgressListener(new OnProgressListener() {
    @Override
    public void onProgress(UploadTask.TaskSnapshot taskSnapshot) {
        Uri sessionUri = taskSnapshot.getUploadSessionUri();
        if (sessionUri != null && !mSaved) {
            mSaved = true;
            // A persisted session has begun with the server.
            // Save this to persistent storage in case the process dies.
        }
    }
});

您的进程由于上传中断而重新启动后,请再次调用 putFile。但这次还会传递已保存的 URI。

//resume the upload task from where it left off when the process died.
//to do this, pass the sessionUri as the last parameter
uploadTask = mStorageRef.putFile(localFile,
        new StorageMetadata.Builder().build(), sessionUri);

会话将持续一周。如果您尝试在过期后恢复会话,或者会话遇到了错误,您将收到一个失败回调。您应确保两次上传之间文件没有更改。

错误处理

导致上传时出现错误的原因有很多,包括本地文件不存在,或者用户不具备上传所需文件的权限。如需了解有关错误的详情,请参阅相关文档的处理错误部分。

完整示例

下面是一个包含进度监控和错误处理的完整上传示例:

// File or Blob
file = Uri.fromFile(new File("path/to/mountains.jpg"));

// Create the file metadata
metadata = new StorageMetadata.Builder()
        .setContentType("image/jpeg")
        .build();

// Upload file and metadata to the path 'images/mountains.jpg'
uploadTask = storageRef.child("images/"+file.getLastPathSegment()).putFile(file, metadata);

// Listen for state changes, errors, and completion of the upload.
uploadTask.addOnProgressListener(new OnProgressListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onProgress(UploadTask.TaskSnapshot taskSnapshot) {
        double progress = (100.0 * taskSnapshot.getBytesTransferred()) / taskSnapshot.getTotalByteCount();
        System.out.println("Upload is " + progress + "% done");
    }
}).addOnPausedListener(new OnPausedListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onPaused(UploadTask.TaskSnapshot taskSnapshot) {
        System.out.println("Upload is paused");
    }
}).addOnFailureListener(new OnFailureListener() {
    @Override
    public void onFailure(@NonNull Exception exception) {
        // Handle unsuccessful uploads
    }
}).addOnSuccessListener(new OnSuccessListener<UploadTask.TaskSnapshot>() {
    @Override
    public void onSuccess(UploadTask.TaskSnapshot taskSnapshot) {
        // Handle successful uploads on complete
        // ...
    }
});

现在您已经上传了文件,接下来,我们将学习如何从 Cloud Storage 下载文件

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面