CreateFileSystem - Amazon Elastic File System
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

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 指定可用区。有关单区存储类别的更多信息,请参阅使用 EFS 存储类中的Amazon EFS 用户指南.

注意

单区存储类在 Amazon Web Services 区域 Amazon EFS 提供的。

类型: 字符串

长度约束:最小长度为 1。最大长度为 64。

模式:.+

:必需 否

备份

指定是否在正在创建的文件系统上启用自动备份。将值设置为true启用自动备份。如果创建的文件系统使用 One Zone 存储类,则默认情况下会启用自动备份。有关更多信息,请参阅 。自动备份中的Amazon EFS 用户指南.

默认为 false。但是,如果您指定AvailabilityZoneName,默认值为true.

注意

Amazon Backup并未在所有 Amazon Web Services 区域 Amazon EFS 提供的。

类型: Boolean

:必需 否

CreationToken

最多不超过 64 个 ASCII 字符的字符的字符。Amazon EFS 使用此信息来确保幂等创建。

类型: 字符串

长度约束:最小长度为 1。最大长度为 64。

模式:.+

:必需 是

已加密

一个布尔值,如果为 true,则创建一个加密文件系统。当创建加密文件系统时,您可以选择指定创建文件系统:KMS键 ID适用于现有的Amazon Key Management Service(Amazon KMS客户主密钥 (CMK)。如果您不指定 CMK,则使用 Amazon EFS 的默认 CMK(即 /aws/elasticfilesystem)来保护加密文件系统。

类型: Boolean

:必需 否

KmsKeyId

的 IDAmazon KMS要用于保护加密文件系统的 CMK。仅当您想使用非默认 KMS 密钥时,此参数才是必需的。如果未指定此参数,则使用 Amazon EFS 的默认 CMK。此 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指定,创建文件系统:加密参数必须设置为 true。

重要

EFS 只接受对称 KMS 密钥。不能将非对称 KMS 密钥用于 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 模式。

类型: 字符串

有效值: generalPurpose | maxIO

:必需 否

ProvisionedThroughputInMibps

要为创建的文件系统预置的吞吐量(以 MiB/s 为单位)。有效值为 1-1024。如果将 ThroughputMode 设置为 provisioned,则是必需的。吞吐量上限为 1024 MiB/s。要提高此限制,请联系 Amazon Web Services Support。有关更多信息,请参阅 。您可以增加的亚马逊 EFS 配额中的Amazon EFS 用户指南.

类型: Double

有效范围:最小值为 1.0。

:必需 否

标签

用于创建与文件系统关联的一个或多个标签。每个标签均为一个用户定义的键值对。通过包含 "Key":"Name","Value":"{value}" 键值对来在创建时为文件系统命名。每个密钥必须是唯一的。有关更多信息,请参阅 。标记Amazonresources中的 Amazon一般参考指南.

类型: 数组Tagobjects

:必需 否

ThroughputMode

指定文件系统的吞吐量模式,burstingprovisioned。如果将 ThroughputMode 设置为 provisioned,则还必须设置 ProvisionedThroughputInMibps 的值。创建文件系统之后,您可以在预置吞吐量模式下降低文件系统的吞吐量,或者在吞吐量模式之间切换,但前提是距离上次降低或吞吐量模式切换超过 24 小时。有关更多信息,请参阅 。使用预配置模式指定吞吐量中的Amazon EFS 用户指南.

默认为 bursting

类型: 字符串

有效值: bursting | provisioned

:必需 否

响应语法

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 格式返回的以下数据。

可用性区域 ID

文件系统的 One Zone 存储类所在的可用区的唯一一致标识符。例如,use1-az1是 us-east-1 的可用区 ID Amazon Web Services 区域 ,它在每个 Amazon Web Services 账户 .

类型: 字符串

AvailabilityZoneName

描述Amazon文件系统所在的可用区,仅对使用 One Zone 存储类的文件系统有效。有关更多信息,请参阅 。使用 EFS 存储类中的Amazon EFS 用户指南.

类型: 字符串

长度约束:最小长度为 1。最大长度为 64。

模式:.+

CreationTime

创建文件系统的时间(以秒为单位)。

类型: 时间戳

CreationToken

请求中指定的不透明字符串。

类型: 字符串

长度约束:最小长度为 1。最大长度为 64。

模式:.+

已加密

一个布尔值,如果设为 true,则指示文件系统已加密。

类型: Boolean

文件系统

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

的 IDAmazon Key Management Service用于保护加密文件系统的客户主密钥 (CMK)。

类型: 字符串

长度约束:长度上限为 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/_-]+))))$

生命周期状态

文件系统的生命周期阶段。

类型: 字符串

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

名称

您可以将标签添加到文件系统,包括Name标签。有关更多信息,请参阅CreateFileSystem。如果文件系统具有一个Name标签时,亚马逊 EFS 将返回此字段中的值。

类型: 字符串

长度约束:长度上限为 256。

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

挂载数

文件系统具有的装载目标的当前数量。有关更多信息,请参阅CreateMountTarget

类型: 整数

有效范围:最小值为 0。

OwnerId

这些区域有: Amazon Web Services 账户 创建文件系统的。如果文件系统是由 IAM 用户创建的,则该用户所属的父账户是该用户的所有者。

类型: 字符串

长度约束:长度上限为 14。

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

PerformanceMode

文件系统的性能模式。

类型: 字符串

有效值: generalPurpose | maxIO

ProvisionedThroughputInMibps

文件系统的预配置吞吐量(以 MiB/s 为单位)。对于使用的文件系统有效ThroughputMode设置为provisioned.

类型: Double

有效范围:最小值为 1.0。

SizeInBytes

文件系统中存储的数据的最新已知计量大小(以字节为单位)Value字段,以及该大小在其Timestamp字段中返回的子位置类型。这些区域有:Timestamp值是自 1970-01-01T 00:00:00 Z 纪元到秒数。这些区域有:SizeInBytes值不表示文件系统的一致快照的大小,但是在没有向文件系统写入内容时,它最终是一致的。也就是说,SizeInBytes仅当文件系统的修改时间不超过几个小时时,才表示实际大小。否则,该值不是文件系统在任何时间点的确切大小。

类型:FileSystemSize 对象

标签

与文件系统关联的标签(以Tag对象。

类型: 数组Tagobjects

ThroughputMode

显示文件系统的吞吐量模式。有关更多信息,请参阅 。吞吐量模式中的Amazon EFS 用户指南.

类型: 字符串

有效值: bursting | provisioned

Errors

BadRequest

如果请求格式错误或包含错误(如无效参数值或缺少必需参数),则返回。

HTTP 状态代码:代码:2 400

文件永久性就绪存在

如果您尝试创建的文件系统已经存在,且带有您提供的创建令牌,则返回。

HTTP 状态代码:代码:2 409

文件系统受限

如果 Amazon Web Services 账户 已创建每个帐户允许的最大文件系统数。

HTTP 状态代码:代码:2 403

吞吐量不足

如果没有足够的容量来配置额外的吞吐量,则返回。当您尝试在预配置吞吐量模式下创建文件系统、尝试增加现有文件系统的预配置吞吐量或尝试将现有文件系统从拆分更改为预配置吞吐量模式时,可能会返回此值。请稍后重试。

HTTP 状态代码:代码:2 503

InternalServerError

如果服务器端发生错误,则返回。

HTTP 状态代码:代码:2 500

吞吐量有限

如果由于达到 1024 MIb/s 的吞吐量限制而无法更改吞吐量模式或预配置吞吐量,则返回。

HTTP 状态代码:代码:2 400

不受支持的可访问区

如果请求的 Amazon EFS 功能在指定的可用区中不可用,则返回。

HTTP 状态代码:代码:2 400

Examples

创建加密 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": 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开发工具包,请参阅以下内容: