Tải tệp lên bằng Cloud Storage cho C++

Cloud Storage for Firebase cho phép bạn nhanh chóng và dễ dàng tải tệp lên một vùng chứa Cloud Storage do Firebase cung cấp và quản lý.

Lưu ý: Theo mặc định, một vùng chứa Cloud Storage for Firebase yêu cầu Firebase Authentication để thực hiện mọi thao tác trên dữ liệu hoặc tệp của vùng chứa. Bạn có thể thay đổi Firebase Security Rules cho Cloud Storage thành cho phép truy cập chưa xác thực trong một số trường hợp cụ thể. Tuy nhiên, trong hầu hết các trường hợp, bạn nên hạn chế quyền truy cập và thiết lập các quy tắc bảo mật mạnh mẽ (đặc biệt là đối với các ứng dụng phát hành công khai). Xin lưu ý rằng nếu bạn sử dụng Google App Engine và có một vùng chứa Cloud Storage mặc định có định dạng tên là *.appspot.com, thì bạn có thể cần cân nhắc mức độ ảnh hưởng của các quy tắc bảo mật đến quyền truy cập vào tệp App Engine.

Lưu ý: Đối với các dự án thuộc gói Spark, Firebase sẽ chặn việc tải lên và lưu trữ một số loại tệp thực thi nhất định cho Windows (tệp có đuôi .exe, .dll và .bat), Android (đuôi .apk) và Apple (đuôi .ipa) bằng Cloud Storage for Firebase và Firebase Hosting. Chính sách này nhằm ngăn chặn hành vi sai trái trên nền tảng của chúng tôi. Các dự án thuộc gói Blaze sẽ không bị ảnh hưởng. Để biết thêm thông tin, hãy xem phần Câu hỏi thường gặp này.

Tạo tệp đối chiếu

Để tải một tệp lên, trước tiên, hãy tạo một Cloud Storage tham chiếu đến vị trí trong Cloud Storage mà bạn muốn tải tệp lên.

Bạn có thể tạo một tham chiếu bằng cách thêm các đường dẫn con vào thư mục gốc của vùng chứa Cloud Storage:

// Create a root reference
StorageReference storage_ref = storage->GetReference();

// Create a reference to "mountains.jpg"
StorageReference mountains_ref = storage_ref.Child("mountains.jpg");

// Create a reference to 'images/mountains.jpg'
StorageReference mountain_images_ref = storage_ref.Child("images/mountains.jpg");

// While the file names are the same, the references point to different files
mountains_ref.name() == mountain_images_ref.name();           // true
mountains_ref.full_path() == mountain_images_ref.full_path(); // false

Bạn không thể tải dữ liệu lên bằng một tham chiếu đến thư mục gốc của nhóm Cloud Storage. Tham chiếu của bạn phải trỏ đến một URL con.

Tải tệp lên

Sau khi có tệp tham chiếu, bạn có thể tải tệp lên Cloud Storage theo hai cách:

1. Tải lên từ bộ nhớ đệm byte trong bộ nhớ
2. Tải lên từ một đường dẫn tệp đại diện cho một tệp trên thiết bị

Tải lên từ dữ liệu trong bộ nhớ

Phương thức PutData() là cách đơn giản nhất để tải tệp lên Cloud Storage. PutData() lấy một vùng đệm byte và trả về một Future<Metadata> chứa thông tin về tệp khi Future hoàn tất. Bạn có thể dùng Controller để quản lý quá trình tải lên và theo dõi trạng thái của quá trình này.

// Data in memory
const size_t kByteBufferSize = ...
uint8_t byte_buffer[kByteBufferSize] = { ... };

// Create a reference to the file you want to upload
StorageReference rivers_ref = storage_ref.Child("images/rivers.jpg");

// Upload the file to the path "images/rivers.jpg"
Future future = rivers_ref.PutBytes(byte_buffer, kByteBufferSize);

Tại thời điểm yêu cầu được thực hiện, chúng ta phải đợi Future hoàn tất trước khi tệp được tải lên. Vì các trò chơi thường chạy trong một vòng lặp và ít dựa vào lệnh gọi lại hơn các ứng dụng khác, nên bạn thường sẽ thăm dò để biết trạng thái hoàn tất.

if (future.status() != firebase::kFutureStatusPending) {
  if (future.status() != firebase::kFutureStatusComplete) {
    LogMessage("ERROR: GetData() returned an invalid future.");
    // Handle the error...
  } else if (future.Error() != firebase::storage::kErrorNone) {
    LogMessage("ERROR: GetData() returned error %d: %s", future.Error(),
               future.error_message());
    // Handle the error...
    }
  } else {
    // Metadata contains file metadata such as size, content-type, and download URL.
    Metadata* metadata = future.Result();
    std::string download_url = metadata->download_url();
  }
}

Tải lên từ tệp trên máy

Bạn có thể tải các tệp trên thiết bị lên, chẳng hạn như ảnh và video từ camera, bằng phương thức PutFile(). PutFile() lấy một std::string đại diện cho đường dẫn đến tệp và trả về một Future<Metadata> sẽ chứa thông tin về tệp khi Future hoàn tất. Bạn có thể dùng Controller để quản lý tệp tải lên và theo dõi trạng thái của tệp.

// File located on disk
std::string local_file = ...

// Create a reference to the file you want to upload
StorageReference rivers_ref = storage_ref.Child("images/rivers.jpg");

// Upload the file to the path "images/rivers.jpg"
Future future = rivers_ref.PutFile(localFile);

// Wait for Future to complete...

if (future.Error() != firebase::storage::kErrorNone) {
  // Uh-oh, an error occurred!
} else {
  // Metadata contains file metadata such as size, content-type, and download URL.
  Metadata* metadata = future.Result();
  std::string download_url = metadata->download_url();
}

Nếu muốn chủ động quản lý quá trình tải lên, bạn có thể cung cấp một Controller cho phương thức PutFile() hoặc PutBytes(). Điều này cho phép bạn sử dụng bộ điều khiển để theo dõi hoạt động tải lên đang diễn ra. Hãy xem phần Quản lý tệp tải lên để biết thêm thông tin.

Thêm siêu dữ liệu tệp

Bạn cũng có thể thêm siêu dữ liệu khi tải tệp lên. Siêu dữ liệu này chứa các thuộc tính siêu dữ liệu tệp thông thường, chẳng hạn như name, size và content_type (thường được gọi là loại MIME). Phương thức PutFile() tự động suy luận loại nội dung từ phần mở rộng tên tệp, nhưng bạn có thể ghi đè loại được tự động phát hiện bằng cách chỉ định content_type trong siêu dữ liệu. Nếu bạn không cung cấp content_type và Cloud Storage không thể suy ra giá trị mặc định từ đuôi tệp, thì Cloud Storage sẽ dùng application/octet-stream. Hãy xem phần Sử dụng siêu dữ liệu tệp để biết thêm thông tin về siêu dữ liệu tệp.

// Create storage reference
StorageReference mountains_ref = storage_ref.Child("images/mountains.jpg");

// Create file metadata including the content type
StorageMetadata metadata;
metadata.set_content_type("image/jpeg");

// Upload data and metadata
mountains_ref.PutBytes(data, metadata);

// Upload file and metadata
mountains_ref.PutFile(local_file, metadata);

Quản lý tải lên

Ngoài việc bắt đầu tải lên, bạn có thể tạm dừng, tiếp tục và huỷ tải lên bằng cách sử dụng các phương thức Pause(), Resume() và Cancel() trên Controller. Bạn có thể tuỳ ý truyền các phương thức này đến phương thức PutBytes() hoặc PutFile().

// Start uploading a file
firebase::storage::Controller controller;
storage_ref.Child("images/mountains.jpg").PutFile(local_file, nullptr, &controller);

// Pause the upload
controller.Pause();

// Resume the upload
controller.Resume();

// Cancel the upload
controller.Cancel();

Theo dõi tiến trình tải lên

Bạn có thể đính kèm trình nghe vào các tệp tải lên để theo dõi tiến trình tải lên.

class MyListener : public firebase::storage::Listener {
 public:
  virtual void OnProgress(firebase::storage::Controller* controller) {
    // A progress event occurred
  }
};

{
  // Start uploading a file
  MyEventListener my_listener;
  storage_ref.Child("images/mountains.jpg").PutFile(local_file, my_listener);
}

Lỗi xử lý

Có một số lý do khiến lỗi có thể xảy ra khi tải lên, bao gồm cả việc tệp cục bộ không tồn tại hoặc người dùng không có quyền tải tệp mong muốn lên. Bạn có thể tìm thêm thông tin về lỗi trong phần Xử lý lỗi của tài liệu.

Các bước tiếp theo

Giờ thì bạn đã tải tệp lên, hãy tìm hiểu cách tải tệp xuống từ Cloud Storage.