storage package

Cloud Storage for Firebase

函数

函数	说明
function(应用, ...)
getStorage(app, bucketUrl)	获取指定 Firebase 应用的 FirebaseStorage 实例。
function(存储, ...)
connectStorageEmulator(存储、主机、端口、选项)	修改此 FirebaseStorage 实例以与 Cloud Storage 模拟器进行通信。
ref(存储空间, 网址)	返回指定网址的 StorageReference。
函数(ref, ...)
deleteObject(ref)	删除此位置的对象。
getBlob(ref, maxDownloadSizeBytes)	在对象所在位置下载数据。如果未找到对象，则返回错误。要使用此功能，您必须在 Cloud Storage 存储分区中将应用的来源列入白名单。另请参阅 https://cloud.google.com/storage/docs/enabling-cors此 API 在 Node 中不可用。
getBytes(ref, maxDownloadSizeBytes)	在对象所在位置下载数据。如果未找到对象，则返回错误。要使用此功能，您必须在 Cloud Storage 存储分区中将应用的来源列入白名单。另请参阅 https://cloud.google.com/storage/docs/troubleshooting-cors
getDownload网址(ref)	返回给定 StorageReference 的下载网址。
getMetadata(ref)	使用此对象的元数据进行解析的 Promise。如果此对象不存在或无法检索元数据，则 promise 会被拒绝。
getStream(ref, maxDownloadSizeBytes)	在对象所在位置下载数据。如果未找到对象，则引发错误事件。此 API 仅适用于 Node。
list(ref, options)	此存储引用下的列表项（文件）和前缀（文件夹）。List API 仅适用于 Firebase 规则版本 2。GCS 是 key-blob 存储区。Firebase 存储会强制采用“/”语义分隔的文件夹结构。如需了解详情，请参阅 GCS 的 List API。为遵循 Firebase 规则的语义，Firebase 存储不支持路径以“/”结尾的对象或包含两个连续的“/”。Firebase Storage List API 会过滤这些不受支持的对象。如果存储分区中不受支持的对象过多，list() 可能会失败。
listAll(ref)	列出此存储引用下的所有项（文件）和前缀（文件夹）。这是一种重复调用 list() 的辅助方法，直到没有更多结果为止。默认的分页大小为 1000。注意：如果在执行此操作期间更改对象，结果可能会不一致。警告：如果结果过多，listAll 可能会消耗过多资源。
updateMetadata(ref, metadata)	更新此对象的元数据。
uploadBytes(ref, data, metadata)	将数据上传到此对象的位置。上传操作不可恢复。
uploadBytesResumable(ref, data, metadata)	将数据上传到此对象的位置。上传可以暂停和恢复，并显示进度更新。
uploadString(ref, value, format, metadata)	将一个字符串上传到此对象的位置。上传操作不可恢复。
function(storageOrRef, ...)
ref(storageOrRef, path)	返回默认存储分区中给定路径的 StorageReference。

类

类	说明
StorageError	Firebase Storage SDK 返回的错误。

枚举

枚举	说明
StorageErrorCode	可附加到 StorageError 对象的错误代码。

接口

接口	说明
FirebaseStorage	Firebase 存储实例。
FullMetadata	一整套对象元数据，包括只读属性。
ListOptions	list() 接受的选项。
ListResult 类的构造函数	list() 返回的结果。
SettableMetadata	可随时设置的对象元数据。
StorageObserver	Firebase 存储的数据流观察器。
StorageReference	表示对 Google Cloud Storage 对象的引用。开发者可以上传、下载和删除对象，以及获取/设置对象元数据。
UploadMetadata	可在上传时设置的对象元数据。
UploadResult	不可续传的上传返回的结果。
UploadTask	表示上传对象的过程。让您能够监控和管理上传。
UploadTaskSnapshot	保存有关上传任务当前状态的数据。

变量

变量	说明
StringFormat	一个枚举，列出了可供上传的字符串格式。

类型别名

类型别名	说明
StringFormat	一个枚举，列出了可供上传的字符串格式。
TaskEvent	在任务上触发的事件。
TaskState	表示正在运行的上传的当前状态。

function(应用, ...)

getStorage(应用, 存储分区网址)

获取指定 Firebase 应用的 FirebaseStorage 实例。

签名：

export declare function getStorage(app?: FirebaseApp, bucketUrl?: string): FirebaseStorage;

参数

参数	类型	说明
应用	FirebaseApp	要为其获取 FirebaseStorage 实例的 Firebase 应用。
存储分区网址	字符串	Firebase Storage 存储分区的 gs:// 网址。如果未通过，则使用应用的默认存储分区。

返回：

FirebaseStorage

一个 FirebaseStorage 实例。

function(storage, ...)

connectStorageEmulator(存储、主机、端口、选项)

修改此 FirebaseStorage 实例以与 Cloud Storage 模拟器进行通信。

签名：

export declare function connectStorageEmulator(storage: FirebaseStorage, host: string, port: number, options?: {
    mockUserToken?: EmulatorMockTokenOptions | string;
}): void;

参数

参数	类型	说明
存储	FirebaseStorage	FirebaseStorage 实例
主机	字符串	模拟器主机（例如：localhost）
端口	数字	模拟器端口（例如：5001）
选项	{ mockUserToken?:EmulatorMockTokenOptions |字符串；}	模拟器选项。options.mockUserToken 是用于单元测试安全规则的模拟身份验证令牌。

返回：

void

ref(存储空间, 网址)

返回指定网址的 StorageReference。

签名：

export declare function ref(storage: FirebaseStorage, url?: string): StorageReference;

参数

参数	类型	说明
存储	FirebaseStorage	FirebaseStorage 实例。
网址	字符串	网址。如果为空，则返回根引用。

返回：

StorageReference

function(ref, ...)

deleteObject(参考)

删除此位置的对象。

签名：

export declare function deleteObject(ref: StorageReference): Promise<void>;

参数

参数	类型	说明
ref	StorageReference	要删除的对象的 StorageReference。

返回：

Promise<void>

在删除成功时解析的 Promise。

getBlob(ref, maxDownloadSizeBytes)

在对象所在位置下载数据。如果未找到对象，则返回错误。

要使用此功能，您必须在 Cloud Storage 存储分区中将应用的来源列入白名单。另请参阅 https://cloud.google.com/storage/docs/troubleshooting-cors

此 API 在 Node 中不可用。

签名：

export declare function getBlob(ref: StorageReference, maxDownloadSizeBytes?: number): Promise<Blob>;

参数

参数	类型	说明
ref	StorageReference	应下载数据的 StorageReference。
maxDownloadSizeBytes	数字	如果设置，则允许检索的大小上限（以字节为单位）。

返回：

Promise<Blob>

通过包含对象字节的 Blob 进行解析的 promise

getBytes(ref, maxDownloadSizeBytes)

在对象所在位置下载数据。如果未找到对象，则返回错误。

要使用此功能，您必须在 Cloud Storage 存储分区中将应用的来源列入白名单。另请参阅 https://cloud.google.com/storage/docs/troubleshooting-cors

签名：

export declare function getBytes(ref: StorageReference, maxDownloadSizeBytes?: number): Promise<ArrayBuffer>;

参数

参数	类型	说明
ref	StorageReference	应下载数据的 StorageReference。
maxDownloadSizeBytes	数字	如果设置，则允许检索的大小上限（以字节为单位）。

返回：

Promise<ArrayBuffer>

包含对象字节的 Promise

getDownload网址（参考）

返回给定 StorageReference 的下载网址。

签名：

export declare function getDownloadURL(ref: StorageReference): Promise<string>;

参数

参数	类型	说明
ref	StorageReference	StorageReference 获取的下载网址。

返回：

承诺<字符串>

使用此对象的下载网址进行解析的 Promise。

getMetadata（参考）

使用此对象的元数据进行解析的 Promise。如果此对象不存在或无法检索元数据，则 promise 会被拒绝。

签名：

export declare function getMetadata(ref: StorageReference): Promise<FullMetadata>;

参数

参数	类型	说明
ref	StorageReference	StorageReference 获取元数据。

返回：

Promise<FullMetadata>

getStream(ref, maxDownloadSizeBytes)

在对象所在位置下载数据。如果未找到对象，则引发错误事件。

此 API 仅适用于 Node。

签名：

export declare function getStream(ref: StorageReference, maxDownloadSizeBytes?: number): NodeJS.ReadableStream;

参数

参数	类型	说明
ref	StorageReference	应下载数据的 StorageReference。
maxDownloadSizeBytes	数字	如果设置，则允许检索的大小上限（以字节为单位）。

返回：

NodeJS.ReadableStream

以字节形式表示对象数据的数据流

列表（引用，选项）

列出此存储引用下的项（文件）和前缀（文件夹）。

List API 仅适用于 Firebase 规则版本 2。

GCS 是 Key-blob 存储区。Firebase 存储会强制采用“/”语义分隔的文件夹结构。如需了解详情，请参阅 GCS 的 List API。

为了遵循 Firebase 规则的语义，Firebase 存储不支持路径以“/”结尾的对象或包含两个连续的“/”。Firebase Storage List API 会过滤这些不受支持的对象。如果存储分区中不受支持的对象过多，list() 可能会失败。

签名：

export declare function list(ref: StorageReference, options?: ListOptions): Promise<ListResult>;

参数

参数	类型	说明
ref	StorageReference	StorageReference 获取列表。
选项	ListOptions	如需了解详情，请参阅 ListOptions。

返回：

Promise<ListResult>

使用项和前缀进行解析的 Promise。prefixes 包含对子文件夹的引用，items 包含对此文件夹中对象的引用。nextPageToken 可用于获取其余结果。

listAll(ref)

列出此存储引用下的所有项（文件）和前缀（文件夹）。

这是一个重复调用 list() 的辅助方法，直到没有更多结果为止。默认的分页大小为 1000。

注意：如果在执行此操作期间更改对象，结果可能会不一致。

警告：如果结果过多，listAll 可能会消耗过多资源。

签名：

export declare function listAll(ref: StorageReference): Promise<ListResult>;

参数

参数	类型	说明
ref	StorageReference	StorageReference 获取列表。

返回：

Promise<ListResult>

使用当前存储引用下的所有项和前缀进行解析的 Promise。prefixes 包含对子目录的引用，items 包含对此文件夹中对象的引用。绝不会返回 nextPageToken。

updateMetadata(ref, metadata)

更新此对象的元数据。

签名：

export declare function updateMetadata(ref: StorageReference, metadata: SettableMetadata): Promise<FullMetadata>;

参数

参数	类型	说明
ref	StorageReference	StorageReference 实例来更新元数据。
元数据	SettableMetadata	对象的新元数据。只有已明确设置的值才会更改。明确地将值设置为 null 会移除元数据。

返回：

Promise<FullMetadata>

使用此对象的新元数据进行解析的 Promise。

uploadBytes(ref, data, metadata)

将数据上传到此对象的位置。上传操作不可恢复。

签名：

export declare function uploadBytes(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): Promise<UploadResult>;

参数

参数	类型	说明
ref	StorageReference	StorageReference，表示应上传数据的位置。
数据	Blob |Uint8Array |数组缓冲区	要上传的数据。
元数据	UploadMetadata	要上传的数据的元数据。

返回：

Promise<UploadResult>

包含 UploadResult 的 Promise

uploadBytesResumable(ref, 数据, 元数据)

将数据上传到此对象的位置。上传可以暂停和恢复，并显示进度更新。

签名：

export declare function uploadBytesResumable(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): UploadTask;

参数

参数	类型	说明
ref	StorageReference	StorageReference，表示应上传数据的位置。
数据	Blob |Uint8Array |数组缓冲区	要上传的数据。
元数据	UploadMetadata	要上传的数据的元数据。

返回：

UploadTask

UploadTask

uploadString(ref, value, 格式, metadata)

将一个字符串上传到此对象的位置。上传操作不可恢复。

签名：

export declare function uploadString(ref: StorageReference, value: string, format?: StringFormat, metadata?: UploadMetadata): Promise<UploadResult>;

参数

参数	类型	说明
ref	StorageReference	StorageReference，您应在其中上传字符串。
值	字符串	要上传的字符串。
格式	StringFormat	要上传的字符串的格式。
元数据	UploadMetadata	要上传的字符串的元数据。

返回：

Promise<UploadResult>

包含 UploadResult 的 Promise

function(storageOrRef, ...)

ref(storageOrRef, 路径)

返回默认存储分区中给定路径的 StorageReference。

签名：

export declare function ref(storageOrRef: FirebaseStorage | StorageReference, path?: string): StorageReference;

参数

参数	类型	说明
存储空间或引用	FirebaseStorage |StorageReference	FirebaseStorage 或 StorageReference。
路径	字符串

返回：

StorageReference

字符串格式

一个枚举，列出了可供上传的字符串格式。

签名：

StringFormat: {
    readonly RAW: "raw";
    readonly BASE64: "base64";
    readonly BASE64URL: "base64url";
    readonly DATA_URL: "data_url";
}

字符串格式

一个枚举，列出了可供上传的字符串格式。

签名：

export declare type StringFormat = (typeof StringFormat)[keyof typeof StringFormat];

任务事件

在任务上触发的事件。

签名：

export declare type TaskEvent = 'state_changed';

任务状态

表示正在运行的上传的当前状态。

签名：

export declare type TaskState = 'running' | 'paused' | 'success' | 'canceled' | 'error';

StorageErrorCode

可附加到 StorageError 对象的错误代码。

签名：

export declare enum StorageErrorCode 

枚举成员

成员	值	说明
APP_DELETED	"app-deleted"
BUCKET_NOT_FOUND	"bucket-not-found"
已取消	"canceled"
CANNOT_SLICE_BLOB	"cannot-slice-blob"
INTERNAL_ERROR	"internal-error"
INVALID_ARGUMENT	"invalid-argument"
INVALID_ARGUMENT_COUNT	"invalid-argument-count"
INVALID_CHECKSUM	"invalid-checksum"
INVALID_DEFAULT_BUCKET	"invalid-default-bucket"
INVALID_EVENT_NAME	"invalid-event-name"
INVALID_FORMAT	"invalid-format"
ROOT_OPERATION 无效	"invalid-root-operation"
网址无效	"invalid-url"
无默认存储分区	"no-default-bucket"
NO_DOWNLOAD_网址	"no-download-url"
OBJECT_NOT_FOUND	"object-not-found"
PROJECT_NOT_FOUND	"project-not-found"
超出 QUOTA_EXCEEDED	"quota-exceeded"
RETRY_LIMIT_EXCEEDED	"retry-limit-exceeded"
SERVER_FILE_WRONG_SIZE	"server-file-wrong-size"
UNAUTHENTICATED	"unauthenticated"
UNAUTHORIZED	"unauthorized"
UNAUTHORIZED_APP	"unauthorized-app"
未知	"unknown"
UNSUPPORTED_ENVIRONMENT	"unsupported-environment"