CreateFileSystem - Amazon Elastic File System
請求語法URI 請求參數請求主體回應語法回應元素錯誤範例另請參閱

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

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。您可以使用掛載目標，在您 VPC 中的 EC2 執行個體上掛載您的 Amazon EFS 檔案系統。如需詳細資訊，請參閱 Amazon EFS：運作方式。

這項操作需要 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 EFS 的 AWS 區域 地方均可使用。

類型：布林值

必要：否

CreationToken

字串最多為 64 個 ASCII 字元。Amazon EFS 使用這項功能來確保等冪建立。

類型：字串

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

模式：.+

必要：是

Encrypted

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

類型：布林值

必要：否

KmsKeyId

您要使用 KMS 金鑰 ID 來保護加密檔案系統。此參數只有在您希望使用非預設 KMS 金鑰時才是必要參數。若沒有指定此參數，則會使用 Amazon EFS 的預設 KMS 金鑰。您可以使用以下格式指定此 KMS 金鑰 ID。

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

  • ARN - 金鑰的 Amazon Resource Name (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，則必須將「CreateFile系統:加密」參數設定為 true。

重要

EFS 只接受對稱 KMS 金鑰。Amazon EFS 檔案系統不能使用非對稱 KMS 金鑰。

類型：字串

長度限制：長度上限為 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

指定檔案系統的輸送量模式。模式可以是 bursting、provisioned 或 elastic。若您將 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

Amazon EFS 檔案系統的 Amazon Resource Name (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 EFS 指派的檔案系統 ID。

類型：字串

長度限制：長度上限為 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 狀態碼：400

FileSystemAlreadyExists

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

HTTP 狀態碼：409

FileSystemLimitExceeded

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

HTTP 狀態碼：403

InsufficientThroughputCapacity

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

HTTP 狀態碼：503

InternalServerError

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

HTTP 狀態碼：500

ThroughputLimitExceeded

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

HTTP 狀態碼：400

UnsupportedAvailabilityZone

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

HTTP 狀態碼：400

範例

建立加密檔案系統

下列範例會傳送 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"
}

另請參閱

如需在其中一個特定語言 AWS SDK 中使用此 API 的詳細資訊，請參閱下列內容：