storage package

Cloud Storage for Firebase

函式

函式	說明
功能(應用程式, ...)
getStorage(應用程式, bucketUrl)	取得指定 Firebase 應用程式的 FirebaseStorage 執行個體。
功能(儲存空間, ...)
connectStorageEmulator(儲存空間、主機、通訊埠、選項)	修改這個 FirebaseStorage 執行個體，以便與 Cloud Storage 模擬器通訊。
ref(storage, 網址)	傳回指定網址的 StorageReference。
功能(參照, ...)
deleteObject(參照)	刪除這個位置中的物件。
getBlob(ref, maxDownloadSizeBytes)	從物件的位置下載資料。如果找不到物件，會傳回錯誤。如要使用此功能，您必須將 Cloud Storage 值區中的應用程式來源加入許可清單。另請參閱 https://cloud.google.com/storage/docs/configuring-cors這個 API 不適用於 Node。
getBytes(ref, maxDownloadSizeBytes)	從物件的位置下載資料。如果找不到物件，會傳回錯誤。如要使用此功能，您必須將 Cloud Storage 值區中的應用程式來源加入許可清單。另請參閱 https://cloud.google.com/storage/docs/configuring-cors
getDownloadURL(參考)	傳回指定 StorageReference 的下載網址。
getMetadata(參照)	使用這個物件中繼資料解析的 Promise。如果這個物件不存在，或是無法擷取中繼資料，承諾就會遭拒。
getStream(ref, maxDownloadSizeBytes)	從物件的位置下載資料。如果找不到物件，就會引發錯誤事件。這個 API 僅適用於 Node。
list(參照、選項)	在此儲存空間參考資料下列出項目 (檔案) 和前置字串 (資料夾)。List API 僅適用於 Firebase 規則 2 版；GCS 是 key-blob 儲存庫。Firebase 儲存空間採用「/」語意分隔資料夾結構如要瞭解詳情，請參閱 GCS 的 List API。為遵循 Firebase 規則的語意，Firebase Storage 不支援路徑結尾為「/」的物件或包含兩個連續的「/」Firebase Storage List API 會篩選這些不支援的物件。如果值區中有太多不支援的物件，list() 可能會失敗。
listAll(參照)	根據這個儲存空間參考資料，列出所有項目 (檔案) 和前置碼 (資料夾)。在沒有任何結果之前，這個方法可用來重複呼叫 list()。預設的分頁大小為 1000。注意：如果在這項作業執行期間變更物件，結果可能會不一致。警告：如果結果過多，listAll 可能會耗用過多資源。
updateMetadata(參照, 中繼資料)	更新這個物件的中繼資料。
uploadBytes(參照, 資料, 中繼資料)	將資料上傳至這個物件的位置。無法繼續上傳。
uploadBytesResumable(參考資料、資料、中繼資料)	將資料上傳至這個物件的位置。您可以暫停及繼續上傳作業，並公開進度更新，
uploadString(參照, 值, 格式, 中繼資料)	將字串上傳至這個物件的位置。無法繼續上傳。
功能(storageOrRef, ...)
ref(storageOrRef, 路徑)	傳回預設值區中指定路徑的 StorageReference。

類別

類別	說明
StorageError	Firebase Storage SDK 傳回錯誤。

列舉

列舉	說明
StorageErrorCode	可附加至 StorageError 物件的錯誤代碼。

介面

介面	說明
Firebase 儲存空間	Firebase 儲存執行個體。
FullMetadata	完整的物件中繼資料 (包括唯讀屬性)。
ListOptions	list() 接受的選項。
ListResult	list() 傳回的結果。
SettableMetadata	可隨時設定的物件中繼資料。
StorageObserver	Firebase 儲存空間的串流觀察器。
儲存空間參考資料	代表對 Google Cloud Storage 物件的參照。開發人員可以上傳、下載及刪除物件，以及取得/設定物件中繼資料。
上傳中繼資料	可在上傳時設定的物件中繼資料。
UploadResult	無法續傳的上傳作業傳回的結果。
UploadTask	代表上傳物件的程序。可讓您監控及管理上傳作業。
UploadTaskSnapshot	保留上傳工作目前狀態的相關資料。

變數

變數	說明
字串格式	列舉可能上傳的字串格式。

型別別名

類型別名	說明
字串格式	列舉可能上傳的字串格式。
TaskEvent	工作中觸發的事件。
工作狀態	代表執行中上傳作業的目前狀態。

function(應用程式, ...)

getStorage(應用程式, bucketUrl)

取得指定 Firebase 應用程式的 FirebaseStorage 執行個體。

簽名：

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

參數

參數	類型	說明
應用程式	Firebase 應用程式	Firebase 應用程式，以取得 FirebaseStorage 執行個體。
值區網址	字串	Firebase Storage 值區的 gs:// 網址。如果未通過，則會使用應用程式的預設 Storage 值區。

傳回：

Firebase 儲存空間

FirebaseStorage 執行個體。

function(儲存空間, ...)

linkStorageEmulator(儲存空間、主機、通訊埠、選項)

修改這個 FirebaseStorage 執行個體，以便與 Cloud Storage 模擬器通訊。

簽名：

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

參數

參數	類型	說明
儲存空間	Firebase 儲存空間	FirebaseStorage 執行個體
主機	字串	模擬器主機 (例如：localhost)
通訊埠	數字	模擬器通訊埠 (例如：5001)
選項	{ mockUserToken？：EmulatorMockTokenOptions |字串；}	模擬器選項。options.mockUserToken 是要用於單元測試安全性規則的模擬驗證權杖。

傳回：

void

ref(storage, 網址)

傳回指定網址的 StorageReference。

簽名：

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

參數

參數	類型	說明
儲存空間	Firebase 儲存空間	FirebaseStorage 執行個體。
網址	字串	網址。如果空白，則會傳回根參照。

傳回：

儲存空間參考資料

function(參照, ...)

deleteObject(參照)

刪除這個位置中的物件。

簽名：

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

參數

參數	類型	說明
參考資料	儲存空間參考資料	StorageReference。

傳回：

Promise<void>

如果刪除成功，Promise 會解析。

getBlob(ref, maxDownloadSizeBytes)

從物件的位置下載資料。如果找不到物件，會傳回錯誤。

如要使用這項功能，您必須在 Cloud Storage 值區中將應用程式來源加入許可清單。另請參閱 https://cloud.google.com/storage/docs/configuring-cors

這個 API 不適用於節點。

簽名：

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

參數

參數	類型	說明
參考資料	儲存空間參考資料	StorageReference，其中資料應下載。
maxDownloadSizeBytes	數字	設定後，可擷取的位元組大小上限 (以位元組為單位)。

傳回：

承諾<Blob>

使用包含物件位元組的 Blob 解析的 Promise

getBytes(ref, maxDownloadSizeBytes)

從物件的位置下載資料。如果找不到物件，會傳回錯誤。

如要使用這項功能，您必須在 Cloud Storage 值區中將應用程式來源加入許可清單。另請參閱 https://cloud.google.com/storage/docs/configuring-cors

簽名：

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

參數

參數	類型	說明
參考資料	儲存空間參考資料	StorageReference，其中資料應下載。
maxDownloadSizeBytes	數字	設定後，可擷取的位元組大小上限 (以位元組為單位)。

傳回：

Promise<ArrayBuffer>

包含物件位元組的 Promise

getDownloadURL(參照)

傳回指定 StorageReference 的下載網址。

簽名：

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

參數

參數	類型	說明
參考資料	儲存空間參考資料	StorageReference，以便取得下載網址。

傳回：

承諾<字串>

會以這個物件的下載網址解析的 Promise。

getMetadata(參照)

使用這個物件中繼資料解析的 Promise。如果這個物件不存在，或是無法擷取中繼資料，承諾產品就會遭到拒絕。

簽名：

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

參數

參數	類型	說明
參考資料	儲存空間參考資料	StorageReference 以取得中繼資料。

傳回：

Promise<FullMetadata>

getStream(ref, maxDownloadSizeBytes)

從物件的位置下載資料。如果找不到物件，則會引發錯誤事件。

這個 API 僅適用於節點。

簽名：

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

參數

參數	類型	說明
參考資料	儲存空間參考資料	StorageReference，其中資料應下載。
maxDownloadSizeBytes	數字	設定後，可擷取的位元組大小上限 (以位元組為單位)。

傳回：

NodeJS.ReadableStream

以位元組形式使用物件資料的串流

list(ref, options)

列出這個儲存空間參考資料中的項目 (檔案) 和前置字串 (資料夾)。

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>;

參數

參數	類型	說明
參考資料	儲存空間參考資料	StorageReference，用來取得清單。
選項	ListOptions	詳情請參閱 ListOptions。

傳回：

Promise<ListResult>

會以項目和前置字串解析的 Promise。prefixes 包含子資料夾的參照，items 包含此資料夾中物件的參照。nextPageToken 可用於取得其餘結果。

listAll(參照)

列出這個儲存空間參考資料中的所有項目 (檔案) 和前置字串 (資料夾)。

這是重複呼叫 list() 的輔助方法，直到沒有其他結果為止。分頁大小預設為 1000。

注意：如果在這項作業執行期間變更物件，結果可能會不一致。

警告：如果結果過多，listAll 可能會耗用過多資源。

簽名：

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

參數

參數	類型	說明
參考資料	儲存空間參考資料	StorageReference，用來取得清單。

傳回：

Promise<ListResult>

Promise，用於解析目前儲存空間參考資料中的所有項目和前置字串。prefixes 包含子目錄的參照，items 則包含此資料夾中物件的參照。nextPageToken 一律不會傳回，

updateMetadata(參照、中繼資料)

更新這個物件的中繼資料。

簽名：

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

參數

參數	類型	說明
參考資料	儲存空間參考資料	StorageReference 以更新中繼資料。
中繼資料	SettableMetadata	物件的新中繼資料。只有明確設定的值會變更。如果將值明確設為 null，系統就會移除中繼資料。

傳回：

Promise<FullMetadata>

Promise，會使用這個物件的新中繼資料來解析。

uploadBytes(參照, 資料, 中繼資料)

將資料上傳至這個物件的位置。無法繼續上傳。

簽名：

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

參數

參數	類型	說明
參考資料	儲存空間參考資料	StorageReference，其中資料要上傳。
資料	Blob |Uint8Array |ArrayBuffer	要上傳的資料。
中繼資料	上傳中繼資料	要上傳資料的中繼資料。

傳回：

承諾<UploadResult>

含有 UploadResult 的 Promise

uploadBytesResumable(參考資料, 資料, 中繼資料)

將資料上傳至這個物件的位置。您可以暫停及繼續上傳作業，並公開進度更新，

簽名：

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

參數

參數	類型	說明
參考資料	儲存空間參考資料	StorageReference，其中資料要上傳。
資料	Blob |Uint8Array |ArrayBuffer	要上傳的資料。
中繼資料	上傳中繼資料	要上傳資料的中繼資料。

傳回：

UploadTask

上傳工作

uploadString(參照, 值, 格式, 中繼資料)

將字串上傳至這個物件的位置。無法繼續上傳。

簽名：

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

參數

參數	類型	說明
參考資料	儲存空間參考資料	StorageReference，其中應上傳字串。
值	字串	要上傳的字串。
格式	字串格式	上傳字串的格式。
中繼資料	上傳中繼資料	要上傳字串的中繼資料。

傳回：

承諾<UploadResult>

含有 UploadResult 的 Promise

function(storageOrRef, ...)

ref(storageOrRef, 路徑)

傳回預設值區中指定路徑的 StorageReference。

簽名：

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

參數

參數	類型	說明
StorageOrRef	Firebase 儲存空間 |Storage 參考資料	FirebaseStorage 或 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];

TaskEvent

工作中觸發的事件。

簽名：

export declare type TaskEvent = 'state_changed';

工作狀態

代表執行中上傳作業的目前狀態。

簽名：

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

StorageErrorCode

可附加至 StorageError 物件的錯誤代碼。

簽名：

export declare enum StorageErrorCode 

列舉成員

成員	值	說明
已刪除應用程式	"app-deleted"
BUCKET_NOT_FOUND	"bucket-not-found"
已取消	"canceled"
CANNOT TRANSLATE	"cannot-slice-blob"
內部錯誤	"internal-error"
INVALID_ARGUMENT	"invalid-argument"
INVALID_src_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_網址	"invalid-url"
NO_DEFAULT_BUCKET	"no-default-bucket"
無下載網址	"no-download-url"
OBJECT_NOT_FOUND	"object-not-found"
專案未找到	"project-not-found"
超過 8000	"quota-exceeded"
重試次數	"retry-limit-exceeded"
SERVER_FILE_WRONG_SIZE	"server-file-wrong-size"
未驗證	"unauthenticated"
未經授權	"unauthorized"
未授權應用程式	"unauthorized-app"
不明	"unknown"
UNSUPPORTED_ENVIRONMENT	"unsupported-environment"