CreateFileSystem - Amazon Elastic File System

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

CreateFileSystem

建立新且空白的文件系統。該操作需要在 Amazon EFS 用於確保冪等創建的請求中使用創建令牌(使用相同的創建令牌調用操作沒有任何效果)。如果呼叫者目前不存在 AWS 帳戶 具有指定建立權杖的呼叫者所擁有的檔案系統,則此作業會執行下列動作:

  • 建立新且空白的文件系統。檔案系統將具有 Amazon EFS 指派的 ID 和初始生命週期狀態creating

  • 傳回所建立檔案系統的描述。

否則,此操作會傳回 FileSystemAlreadyExists 錯誤,其中包含現有檔案系統的 ID。

注意

對於基本用例,您可以使用隨機生成UUID的創建令牌。

等冪操作可讓您重試 CreateFileSystem 呼叫,而無須承擔建立額外檔案系統的風險。在初始呼叫失敗,導致不確定檔案系統實際上是否已建立時,便可能會發生此狀況。其中一個範例便是發生傳輸層逾時,或是您的連線重設時。只要您使用相同的建立字符,若初始呼叫成功建立檔案系統,用戶端便會從 FileSystemAlreadyExists 錯誤中得知該檔案系統已存在。

如需詳細資訊,請參閱 Amazon EFS 使用者指南中的建立檔案系統

注意

CreateFileSystem 呼叫會在檔案系統的生命週期狀態仍處於 creating 時傳回。您可以透過呼叫 DescribeFileSystems 操作來檢查檔案系統的建立狀態,該操作與其他項目會一起傳回檔案系統狀態。

此操作會接受一個為檔案系統選擇的選用 PerformanceMode 參數。我們建議所generalPurposePerformanceMode有檔案系統使用。該maxIO模式是上一代的效能類型,專為高度平行化的工作負載而設計,可以容忍比模式更高的延遲。generalPurpose MaxIO使用彈性輸送量的單一區域檔案系統或檔案系統不支援 mode。

檔案系統建立後無法變更。PerformanceMode如需詳細資訊,請參閱 Amazon EFS 效能模式

您可以使用 ThroughputMode 參數設定檔案系統的輸送量模式。

檔案系統完全建立之後,Amazon 會將其生命週期狀態EFS設定為available,此時您可以為檔案系統中的檔案系統建立一或多個掛載目標VPC。如需詳細資訊,請參閱 CreateMountTarget。您可以使用掛載目標在您的EC2VPC執行個體上掛載 Amazon EFS 檔案系統。如需詳細資訊,請參閱 AmazonEFS:其運作方式。

這項操作需要 elasticfilesystem:CreateFileSystem 動作的許可。

檔案系統可在建立時加上標籤。如果在建立動作中指定了標籤,請對動作IAM執行其他授權,以確認使用者是否具有建立標籤的權限。elasticfilesystem:TagResource因此,您必須授予使用 elasticfilesystem:TagResource 動作的明確許可。如需詳細資訊,請參閱在建立期間授予標記資源的許可

請求語法

POST /2015-02-01/file-systems HTTP/1.1 Content-type: application/json { "AvailabilityZoneName": "string", "Backup": boolean, "CreationToken": "string", "Encrypted": boolean, "KmsKeyId": "string", "PerformanceMode": "string", "ProvisionedThroughputInMibps": number, "Tags": [ { "Key": "string", "Value": "string" } ], "ThroughputMode": "string" }

URI請求參數

請求不使用任何URI參數。

請求主體

請求接受以下JSON格式的數據。

AvailabilityZoneName

對於「單一區域」檔案系統,請指 AWS 定要在其中建立檔案系統的可用區域。使用格式 us-east-1a 來指定可用區域。如需有關單一區域檔案系統的詳細資訊,請參閱 Amazon EFS 使用者指南中的EFS檔案系統類型

注意

並非提供 Amazon EFS 服務的所有可用區域都不提供單 AWS 區域 一區域檔案系統。

類型:字串

長度限制:長度下限為 1。長度上限為 64。

模式:.+

必要:否

Backup

指定是否在您正在建立的檔案系統上啟用自動備份。將值設定為 true 以啟用自動備份。如果您要建立單區域檔案系統,預設會啟用自動備份。如需詳細資訊,請參閱 Amazon EFS 使用者指南中的自動備份

預設值為 false。但是,如果您指定 AvailabilityZoneName,預設值為 true

注意

AWS Backup 並非在所有 Amazon 可用的 AWS 區域 地方EFS都可用。

類型:布林值

必要:否

CreationToken

最多 64 個字元的ASCII字串。Amazon EFS 使用它來確保冪等創建。

類型:字串

長度限制:長度下限為 1。長度上限為 64。

模式:.+

必要:是

Encrypted

布林值,若為 True 便會建立加密檔案系統。建立加密的檔案系統時,您可以選擇指定現有的 AWS Key Management Service 金鑰 (KMS金鑰)。如果您未指定KMS金鑰,則會使用 Amazon EFS 的預設KMS金鑰來保護加密的檔案系統。/aws/elasticfilesystem

類型:布林值

必要:否

KmsKeyId

您要用來保護加密檔案系統的KMS金鑰識別碼。只有當您想要使用非預設KMS金鑰時,才需要此參數。如果未指定此參數,則會使用 Amazon EFS 的預設KMS金鑰。您可以使用下列格式指定KMS金鑰 ID:

  • 金鑰 ID - 金鑰的唯一識別碼,例如 1234abcd-12ab-34cd-56ef-1234567890ab

  • ARN-例如,金鑰的 Amazon 資源名稱 (ARN) arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

  • 金鑰別名 - 先前為金鑰建立的顯示名稱,例如 alias/projectKey1

  • 索引鍵別名 ARN-ARN 例如,代表索引鍵別名arn:aws:kms:us-west-2:444455556666:alias/projectKey1

如果您使用KmsKeyId,則必須將:加密CreateFileSystem參數設定為 true。

重要

EFS僅接受對稱KMS金鑰。您無法將非對稱KMS金鑰與 Amazon EFS 檔案系統搭配使用。

類型:字串

長度限制:長度上限為 2048。

模式:^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|mrk-[0-9a-f]{32}|alias/[a-zA-Z0-9/_-]+|(arn:aws[-a-z]*:kms:[a-z0-9-]+:\d{12}:((key/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})|(key/mrk-[0-9a-f]{32})|(alias/[a-zA-Z0-9/_-]+))))$

必要:否

PerformanceMode

檔案系統的效能模式。我們建議針對所有的檔案系統使用 generalPurpose 效能模式。使用 maxIO 效能模式的檔案系統可擴展到更高層級的彙整輸送量及每秒操作數,其代價是針對大多數的檔案操作,會有稍高的延遲。效能模式在檔案系統建立之後便無法變更。單區域檔案系統不支援 maxIO 模式。

重要

由於最大 I/O 的每個操作延遲較高,我們建議所有檔案系統使用「一般用途」效能模式。

預設值為 generalPurpose

類型:字串

有效值:generalPurpose | maxIO

必要:否

ProvisionedThroughputInMibps

您要佈建的檔案系統輸送量,以每秒 MB (MiBps) 為單位。若將 ThroughputMode 設為 provisioned,則為必要項目。有效值為 1-3414 MiBps,上限取決於地區。若要提高此限制,請聯絡 AWS Support。如需詳細資訊,請參閱 Amazon EFS使用者指南中可增加的 Amazon EFS 配額

類型:Double

有效範圍:最小值為 1.0。

必要:否

Tags

用於建立一或多個與檔案系統相關聯的標籤。每個標籤都是使用者定義的鍵/值對。透過包含 "Key":"Name","Value":"{value}" 鍵/值對來在建立時為您的檔案系統命名。每個鍵都必須是唯一的。如需詳細資訊,請參閱《 AWS 一般參考指南》中的標記 AWS 資源

類型:Tag 物件陣列

必要:否

ThroughputMode

指定檔案系統的輸送量模式。模式可以是 burstingprovisionedelastic。若您將 ThroughputMode 設為 provisioned,您也必須為 ProvisionedThroughputInMibps 設定值。建立檔案系統後,在有限時間内,您可以減少佈建輸送量或變更輸送量模式。如需詳細資訊,請參閱 Amazon EFS 使用者指南中的使用佈建模式指定輸送量。

預設值為 bursting

類型:字串

有效值:bursting | provisioned | elastic

必要:否

回應語法

HTTP/1.1 201 Content-type: application/json { "AvailabilityZoneId": "string", "AvailabilityZoneName": "string", "CreationTime": number, "CreationToken": "string", "Encrypted": boolean, "FileSystemArn": "string", "FileSystemId": "string", "FileSystemProtection": { "ReplicationOverwriteProtection": "string" }, "KmsKeyId": "string", "LifeCycleState": "string", "Name": "string", "NumberOfMountTargets": number, "OwnerId": "string", "PerformanceMode": "string", "ProvisionedThroughputInMibps": number, "SizeInBytes": { "Timestamp": number, "Value": number, "ValueInArchive": number, "ValueInIA": number, "ValueInStandard": number }, "Tags": [ { "Key": "string", "Value": "string" } ], "ThroughputMode": "string" }

回應元素

如果動作成功,服務會傳回 HTTP 201 回應。

服務會以JSON格式傳回下列資料。

AvailabilityZoneId

檔案系統所在可用區域的唯一且一致的識別碼僅對單區域有效。例如,use1-az1是 us-east-1 的可用區域識別碼 AWS 區域,而且它在每個項目中都有相同的位置。 AWS 帳戶

類型:字串

AvailabilityZoneName

描述檔案系統所在的 AWS 可用區域,且僅對單一區域檔案系統有效。如需詳細資訊,請參閱 Amazon 使用EFS者指南中的使用EFS儲存類別

類型:字串

長度限制:長度下限為 1。長度上限為 64。

模式:.+

CreationTime

建立檔案系統的時間,以秒為單位 (自 1970-01-01T00:00:00Z 以來)。

類型:Timestamp

CreationToken

請求中指定的不透明字串。

類型:字串

長度限制:長度下限為 1。長度上限為 64。

模式:.+

Encrypted

布林值,若為 true,指出加密檔案系統。

類型:布林值

FileSystemArn

EFS檔案系統的 Amazon 資源名稱 (ARN),格式為arn:aws:elasticfilesystem:region:account-id:file-system/file-system-id 。示例資料範例:arn:aws:elasticfilesystem:us-west-2:1111333322228888:file-system/fs-01234567

類型:字串

FileSystemId

由 Amazon 分配的文件系統的 ID EFS。

類型:字串

長度限制:長度上限為 128。

模式:^(arn:aws[-a-z]*:elasticfilesystem:[0-9a-z-:]+:file-system/fs-[0-9a-f]{8,40}|fs-[0-9a-f]{8,40})$

FileSystemProtection

說明檔案系統的防護。

類型:FileSystemProtectionDescription 物件

KmsKeyId

AWS KMS key 用來保護加密檔案系統的識別碼。

類型:字串

長度限制:長度上限為 2048。

模式:^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|mrk-[0-9a-f]{32}|alias/[a-zA-Z0-9/_-]+|(arn:aws[-a-z]*:kms:[a-z0-9-]+:\d{12}:((key/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})|(key/mrk-[0-9a-f]{32})|(alias/[a-zA-Z0-9/_-]+))))$

LifeCycleState

檔案系統的生命周期階段。

類型:字串

有效值:creating | available | updating | deleting | deleted | error

Name

您可以將標籤 (包括 Name 標籤) 新增至檔案系統。如需詳細資訊,請參閱 CreateFileSystem。如果檔案系統有Name標籤,Amazon 會EFS傳回此欄位中的值。

類型:字串

長度限制:長度上限為 256。

模式:^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

NumberOfMountTargets

檔案系統目前擁有的掛載目標數。如需詳細資訊,請參閱 CreateMountTarget

類型:整數

有效範圍:最小值為 0。

OwnerId

建 AWS 帳戶 立檔案系統的。

類型:字串

長度限制:長度上限為 14。

模式:^(\d{12})|(\d{4}-\d{4}-\d{4})$

PerformanceMode

檔案系統的效能模式。

類型:字串

有效值:generalPurpose | maxIO

ProvisionedThroughputInMibps

檔案系統的佈建輸送量量 MiBps,以測量單位。對使用 ThroughputMode 設定為 provisioned 的檔案系統有效。

類型:Double

有效範圍:最小值為 1.0。

SizeInBytes

儲存在檔案系統、Value 欄位中的資料最新已知計量大小 (以位元組為單位),以及在 Timestamp 欄位中決定該大小的時間。Timestamp 值是自 1970-01-01T00:00:00Z 以來的整數秒數。SizeInBytes 值不代表檔案系統的一致快照集大小,但是在沒有寫入檔案系統時,它最終會保持一致。也就是說,只有超過幾個小時未修改檔案系統,SizeInBytes 才能表示實際大小。否則,該值并不能代表檔案系統在任何時間點的確切大小。

類型:FileSystemSize 物件

Tags

與檔案系統相關聯的標籤以 Tag 物件陣列形式呈現出來。

類型:Tag 物件陣列

ThroughputMode

顯示檔案系統的輸送量模式。如需詳細資訊,請參閱 Amazon EFS 使用者指南中的輸送量模式

類型:字串

有效值:bursting | provisioned | elastic

錯誤

BadRequest

如果請求格式錯誤或包含錯誤,例如無效的參數值或缺少必要參數,則傳回。

HTTP狀態碼:4

FileSystemAlreadyExists

如果您嘗試建立的檔案系統已經存在,並使用了您提供的建立權杖,則傳回。

HTTP狀態碼:4

FileSystemLimitExceeded

如果 AWS 帳戶 已經建立了每個帳戶允許的最大檔案系統數,則傳回。

HTTP狀態碼:4

InsufficientThroughputCapacity

如果沒有足夠容量佈建其他輸送量,則傳回。當您嘗試以佈建輸送量模式建立檔案系統、嘗試增加現有檔案系統的佈建輸送量,或嘗試將現有檔案系統從「爆增輸送量」變更為「佈建輸送量」模式時,系統可能會傳回此值。請稍後再試。

HTTP狀態碼:5

InternalServerError

如果伺服器端發生錯誤,則傳回。

HTTP狀態碼:5

ThroughputLimitExceeded

如果因為已達到 1024 MB 的輸送量限制而無法變更輸送量模式或佈建輸送量縂量,則傳回。

HTTP狀態碼:4

UnsupportedAvailabilityZone

如果請求的 Amazon EFS 功能在指定的可用區域中不可用,則傳回。

HTTP狀態碼:4

範例

建立加密的EFS檔案系統

下列範例會傳送POST要求,在啟用自動備份的us-west-2區域中建立檔案系統。該請求指定 myFileSystem1 為等冪性的建立權杖。

請求範例

POST /2015-02-01/file-systems HTTP/1.1 Host: elasticfilesystem.us-west-2.amazonaws.com x-amz-date: 20140620T215117Z Authorization: <...> Content-Type: application/json Content-Length: 42 { "CreationToken" : "myFileSystem1", "PerformanceMode" : "generalPurpose", "Backup": true, "Encrypted": true, "Tags":[ { "Key": "Name", "Value": "Test Group1" } ] }

回應範例

HTTP/1.1 201 Created x-amzn-RequestId: 01234567-89ab-cdef-0123-456789abcdef Content-Type: application/json Content-Length: 319 { "ownerId":"251839141158", "CreationToken":"myFileSystem1", "Encrypted": true, "PerformanceMode" : "generalPurpose", "fileSystemId":"fs-01234567", "CreationTime":"1403301078", "LifeCycleState":"creating", "numberOfMountTargets":0, "SizeInBytes":{ "Timestamp": 1403301078, "Value": 29313618372, "ValueInArchive": 201156, "ValueInIA": 675432, "ValueInStandard": 29312741784 }, "Tags":[ { "Key": "Name", "Value": "Test Group1" } ], "ThroughputMode": "elastic" }

建立具有單一區域可用性的加密EFS檔案系統

下列範例會傳送POST要求,在啟用自動備份的us-west-2區域中建立檔案系統。檔案系統在 us-west-2b可用區域中有單區域儲存。

請求範例

POST /2015-02-01/file-systems HTTP/1.1 Host: elasticfilesystem.us-west-2.amazonaws.com x-amz-date: 20140620T215117Z Authorization: <...> Content-Type: application/json Content-Length: 42 { "CreationToken" : "myFileSystem2", "PerformanceMode" : "generalPurpose", "Backup": true, "AvailabilityZoneName": "us-west-2b", "Encrypted": true, "ThroughputMode": "elastic", "Tags":[ { "Key": "Name", "Value": "Test Group1" } ] }

回應範例

HTTP/1.1 201 Created x-amzn-RequestId: 01234567-89ab-cdef-0123-456789abcdef Content-Type: application/json Content-Length: 319 { "ownerId":"251839141158", "CreationToken":"myFileSystem1", "Encrypted": true, "AvailabilityZoneId": "usew2-az2", "AvailabilityZoneName": "us-west-2b", "PerformanceMode" : "generalPurpose", "fileSystemId":"fs-01234567", "CreationTime":"1403301078", "LifeCycleState":"creating", "numberOfMountTargets":0, "SizeInBytes":{ "Timestamp": 1403301078, "Value": 29313618372, "ValueInArchive": 201156, "ValueInIA": 675432, "ValueInStandard": 29312741784 }, "Tags":[ { "Key": "Name", "Value": "Test Group1" } ], "ThroughputMode": "elastic" }

另請參閱

如需API在其中一種特定語言中使用此功能的詳細資訊 AWS SDKs,請參閱下列內容: