本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
CreateFileSystem
创建新的空文件系统。该操作在 Amazon EFS 用于确保幂等创建的请求中需要一个创建令牌(使用相同的创建令牌调用该操作没有效果)。如果当前不存在由Amazon Web Services 账户具有指定创建令牌的调用者拥有的文件系统,则此操作将执行以下操作:
-
创建新的空文件系统。该文件系统将具有 Amazon EFS 分配的 ID,并且初始生命周期状态为
creating
。 -
返回所创建文件系统的描述。
否则,此操作将返回 FileSystemAlreadyExists
错误,其中包含现有文件系统的 ID。
对于基本使用案例,您可以对创建令牌使用随机生成的 UUID。
幂等操作允许您重试 CreateFileSystem
调用,而不会有创建额外文件系统的风险。当初始调用以某种方式失败时,可能会发生这种情况,使其无法确定是否已实际创建文件系统。例如,可能发生了传输级别超时或重置了连接。只要使用相同的创建令牌,如果初始调用已成功创建文件系统,则客户端可以从 FileSystemAlreadyExists
错误中了解文件系统的存在。
有关更多信息,请参阅 Amazon EFS 用户指南中的创建文件系统。
当文件系统的生命周期状态仍为 creating
时,CreateFileSystem
调用将返回。您可以通过调用该操作来检查文件系统的创建状态,该DescribeFileSystems操作除其他外,还会返回文件系统状态。
此操作接受您为文件系统选择的可选PerformanceMode
参数。我们针对大多数文件系统推荐使用 generalPurpose
性能模式。使用 maxIO
性能模式的文件系统可以扩展到更高级别的聚合吞吐量和每秒操作数,但代价是大多数文件操作的延迟较高。创建文件系统后,将无法更改性能模式。有关更多信息,请参阅 Amazon EFS 性能模式。
您可以使用ThroughputMode
参数设置文件系统的吞吐量模式。
在完全创建文件系统之后,Amazon EFS 将其生命周期状态设置为 available
,此时您可以在 VPC 中为文件系统创建一个或多个挂载目标。有关更多信息,请参阅CreateMountTarget:通过使用挂载目标,可以将 Amazon EFS 文件系统挂载到 VPC 中的 EC2 实例上。有关更多信息,请参阅 Amazon EFS:工作原理。
此操作需要 elasticfilesystem:CreateFileSystem
操作的权限。
请求语法
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
-
用于创建使用单区存储类的文件系统。它指定要在其中创建文件系统的 Amazon 可用区。使用格式
us-east-1a
指定可用区。有关单区存储类的更多信息,请参阅《Amazon EFS 用户指南》中的使用 EFS 存储类。注意 在提供 Amazon EFS 的 Amazon Web Services 区域 中,并非所有可用区都提供单区存储类。
类型:字符串
长度限制:最小长度为 1。最大长度为 64。
模式:
.+
必需:否
- Backup
-
指定是否在正在创建的文件系统上启用自动备份。将值设置为
true
以启用自动备份。如果您创建使用单区存储类的文件系统,则自动备份在默认情况下处于启用状态。有关更多信息,请参阅 Amazon EFS 的自动备份。默认为
false
。但是,如果您指定AvailabilityZoneName
,则默认值为true
。注意 Amazon Backup并非在提供 Amazon EFS 的全部Amazon Web Services 区域地区都可用。
类型:布尔值
必需:否
- CreationToken
-
最多 64 个 ASCII 字符的字符串。Amazon EFS 使用它来确保幂等创建。
类型:字符串
长度限制:最小长度为 1。最大长度为 64。
模式:
.+
必需:是
- Encrypted
-
一个布尔值,如果为 true,则创建一个加密文件系统。在创建加密文件系统时,可以选择指定现有Amazon Key Management Service密钥(KMS 密钥)。如果您不指定 KMS 密钥,则使用 Amazon EFS 的默认 KMS 密钥(即
/aws/elasticfilesystem
)来保护加密文件系统。类型:布尔值
必需:否
- KmsKeyId
-
要用于保护加密文件系统的 ID。仅当您想使用非默认 KMS 密钥时,此参数才是必需的。如果未指定此参数,则使用 Amazon EFS 的默认 CMK 密钥。您可以使用以下格式指定 KMS 密钥:
-
键 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
,则必须将:encrypted CreateFileSystem参数设置为 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
模式。类型:字符串
有效值:
generalPurpose | maxIO
必需:否
- ProvisionedThroughputInMibps
-
要为创建的文件系统预置的吞吐量(以 MiB/s 为单位)。有效值为 1-1024。如果将
ThroughputMode
设置为provisioned
,则是必需的。吞吐量上限为 1024 MiB/s。要提高此限制,请联系 Amazon Web Services Support。有关更多信息,请参阅《Amazon EFS 用户指南》中的您可以提高的 Amazon EFS 配额。类型:双精度
有效范围:最小值为 1.0。
必需:否
- Tags
-
用于创建与文件系统关联的一个或多个标签。每个标签均为一个用户定义的键值对。通过包含
"Key":"Name","Value":"{value}"
键值对来在创建时为文件系统命名。每个键必须是唯一的。有关标签的更多信息,请参阅《Amazon 一般参考指南》中的标记 Amazon 资源。类型: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",
"KmsKeyId": "string",
"LifeCycleState": "string",
"Name": "string",
"NumberOfMountTargets": number,
"OwnerId": "string",
"PerformanceMode": "string",
"ProvisionedThroughputInMibps": number,
"SizeInBytes": {
"Timestamp": number,
"Value": number,
"ValueInIA": number,
"ValueInStandard": number
},
"Tags": [
{
"Key": "string",
"Value": "string"
}
],
"ThroughputMode": "string"
}
响应元素
如果此操作成功,则该服务将会发送回 HTTP 201 响应。
服务以 JSON 格式返回的以下数据。
- AvailabilityZoneId
-
文件系统的 One Zone 存储类别所在的可用区的唯一且一致的标识符。例如,并映射
use1-az1
到useaz-east-east-的可用区Amazon Web Services 区域,并且在每个可用区 ID,并且在每个可用区 IDAmazon Web Services 账户。类型:字符串
- AvailabilityZoneName
-
描述文件系统所在的Amazon可用区,仅对使用 One Zone 存储类的文件系统有效。有关更多信息,请参阅 Amazon EFS 的使用 EFS 存储类。
类型:字符串
长度限制:最小长度为 1。最大长度为 64。
模式:
.+
- CreationTime
-
文件系统的创建时间,以秒为单位(自 1970-01-01T00:00:00 Z 起)。
类型: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 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})$
- KmsKeyId
-
Amazon KMS key用于保护加密文件系统的 ID。
类型:字符串
长度限制:最大长度为 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
-
创建Amazon Web Services 账户了文件系统的。如果文件系统由 IAM 用户创建,则用户所属的父账户是所有者。
类型:字符串
长度约束:最大长度为 14。
模式:
^(\d{12})|(\d{4}-\d{4}-\d{4})$
- PerformanceMode
-
文件系统的性能模式。
类型:字符串
有效值:
generalPurpose | maxIO
- ProvisionedThroughputInMibps
-
文件系统的预置吞吐量(以 Mib/s 为单位)。对于使用
ThroughputMode
设置为的文件系统有效provisioned
。类型:双精度
有效范围:最小值为 1.0。
- SizeInBytes
-
存储在文件系统及其
Value
字段中的数据的最新已知计量大小(以字节为单位),以及在其Timestamp
字段中确定该大小的时间。该Timestamp
值是自 1970-01-01T00:00:00 Z 以来的整数秒数。该SizeInBytes
值并不代表文件系统一致性快照的大小,但是当没有写入文件系统时,该值最终会保持一致。也就是说,仅当文件系统的修改时间不超过几个小时时,才SizeInBytes
表示实际大小。否则,该值不是文件系统在任何时间点的确切大小。类型:FileSystemSize 对象
- Tags
-
与文件系统相关的标签,以
Tag
对象数组的形式呈现。类型:Tag 对象数组
- ThroughputMode
-
显示文件系统的吞吐量模式。有关更多信息,请参阅 Amazon EFS 的吞吐量模式。
类型:字符串
有效值:
bursting | provisioned | elastic
错误
- BadRequest
-
如果请求格式错误或包含错误(例如参数值无效或缺少必需参数),则返回。
HTTP 状态代码:400
- FileSystemAlreadyExists
-
如果您尝试创建的文件系统已经存在,则使用您提供的创建令牌返回。
HTTP 状态代码:409
- FileSystemLimitExceeded
-
如果Amazon Web Services 账户已经创建了每个账户允许的最大文件系统数,则返回。
HTTP 状态代码:403
- InsufficientThroughputCapacity
-
如果没有足够的容量来预置额外的吞吐量,则返回。当您尝试在预置吞吐量模式下创建文件系统、尝试增加现有文件系统的预置吞吐量或尝试将现有文件系统从突增吞吐量更改为预置吞吐量模式时,可能会返回此值。请稍后重试。
HTTP 状态代码:503
- InternalServerError
-
如果服务器端发生错误,则返回。
HTTP 状态代码:500
- ThroughputLimitExceeded
-
如果由于已达到 1024 MiB/s 的吞吐量限制而无法更改吞吐量模式或预置吞吐量量,则返回。
HTTP 状态代码:400
- UnsupportedAvailabilityZone
-
如果请求的 Amazon EFS 功能在指定可用区不可用,则返回。
HTTP 状态代码:400
示例
创建加密 EFS Service
以下示例发送 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": 29313417216,
"ValueInIA": 675432,
"ValueInStandard": 29312741784
},
"Tags":[
{
"Key": "Name",
"Value": "Test Group1"
}
],
"ThroughputMode": "bursting"
}
创建使用单区存储类的加密 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": "provisioned",
"ProvisionedThroughputInMibps": 60,
"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,
"ProvisionedThroughputInMibps": 60,
"SizeInBytes":{
"Timestamp": 1403301078,
"Value": 29313417216,
"ValueInIA": 675432,
"ValueInStandard": 29312741784
},
"Tags":[
{
"Key": "Name",
"Value": "Test Group1"
}
],
"ThroughputMode": "provisioned"
}
另请参阅
有关在特定语言的 Amazon 软件开发工具包中使用此 API 的更多信息,请参阅以下内容: