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

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

CreateFileSystem

创建新的空文件系统。该操作在 Amazon EFS 用于确保幂等创建的请求中需要一个创建令牌(使用相同的创建令牌调用该操作没有效果)。如果发起人的 Amazon Web Services 账户拥有指定的创建令牌,而该账户目前不存在文件系统,则此操作将执行以下任务:

  • 创建新的空文件系统。该文件系统将具有 Amazon EFS 分配的 ID,并且初始生命周期状态为 creating

  • 返回所创建文件系统的描述。

否则,此操作将返回 FileSystemAlreadyExists 错误,其中包含现有文件系统的 ID。

注意

对于基本使用案例,您可以对创建令牌使用随机生成的 UUID。

幂等操作允许您重试 CreateFileSystem 调用,而不会有创建额外文件系统的风险。当初始调用以某种方式失败时,可能会发生这种情况,使其无法确定是否已实际创建文件系统。例如,可能发生了传输级别超时或重置了连接。只要使用相同的创建令牌,如果初始调用已成功创建文件系统,则客户端可以从 FileSystemAlreadyExists 错误中了解文件系统的存在。

有关更多信息,请参阅《Amazon EFS 用户指南》中的创建文件系统

注意

当文件系统的生命周期状态仍为 creating 时,CreateFileSystem 调用将返回。可以通过调用 DescribeFileSystems 操作来检查文件系统创建状态,此操作将返回文件系统状态以及其他方面的信息。

此操作接受为文件系统选择的可选 PerformanceMode 参数。我们建议对所有文件系统使用 generalPurpose PerformanceModemaxIO 模式是上一代性能类型,专为高度并行化的工作负载而设计,可以比 generalPurpose 模式容忍更高的延迟。单区文件系统或使用弹性吞吐量的文件系统不支持 MaxIO 模式。

创建文件系统后,将无法更改 PerformanceMode。有关更多信息,请参阅 Amazon EFS 性能模式

可以使用 ThroughputMode 参数设置文件系统的吞吐量模式。

在完全创建文件系统之后,Amazon EFS 将其生命周期状态设置为 available,此时您可以在 VPC 中为文件系统创建一个或多个挂载目标。有关更多信息,请参阅CreateMountTarget。通过使用挂载目标,可以将 Amazon EFS 文件系统挂载到 VPC 中的 EC2 实例上。有关更多信息,请参阅 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

对于单区文件系统,指定要在其中创建文件系统的 Amazon 可用区。使用格式 us-east-1a 指定可用区。有关单区文件系统的更多信息,请参阅《Amazon EFS 用户指南》中的 EFS 文件系统类型

注意

在提供 Amazon EFS 的 Amazon Web Services 区域中,并非所有可用区都提供单区文件系统。

类型:字符串

长度限制:长度下限为 1。长度上限为 64。

模式:.+

必需:否

Backup

指定是否在正在创建的文件系统上启用自动备份。将此值设置为 true 以启用自动备份。如果您创建单区文件系统,则默认情况下会启用自动备份。有关更多信息,请参阅《Amazon EFS 用户指南》中的自动备份

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

注意

并非所有提供 Amazon EFS 的 Amazon Web Services 区域都提供 Amazon Backup。

类型:布尔值

必需:否

CreationToken

长度最多为 64 个 ASCII 字符的字符串。Amazon EFS 使用它来确保幂等性创建。

类型:字符串

长度限制:长度下限为 1。长度上限为 64。

模式:.+

必需:是

Encrypted

一个布尔值,如果为 true,则创建一个加密文件系统。创建加密文件系统时,可以选择指定现有 Amazon 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 资源名称(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 模式。

重要

由于最大 I/O 的每次操作延迟较高,因此我们建议对所有文件系统使用通用性能模式。

默认值为 generalPurpose

类型:字符串

有效值:generalPurpose | maxIO

必需:否

ProvisionedThroughputInMibps

您要为正在创建的文件系统预配置的吞吐量,以兆字节每秒 (MiBps) 为单位。如果将 ThroughputMode 设置为 provisioned,则是必需的。有效值为 1-3414 MiBps,上限取决于区域。要提高此限制,请联系 Amazon Web Services Support。有关更多信息,请参阅《Amazon EFS 用户指南》中的您可以提高的 Amazon EFS 配额

类型:双精度

有效范围:最小值为 1.0。

必需:否

Tags

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

类型: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 Amazon Web Services 区域的可用区 ID,它在每个 Amazon Web Services 账户中的位置均相同。

类型:字符串

AvailabilityZoneName

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

类型:字符串

长度限制:长度下限为 1。长度上限为 64。

模式:.+

CreationTime

文件系统的创建时间,以秒为单位(自 1970-01-01T00:00:00Z 起)。

类型:时间戳

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

文件系统 ID,由 Amazon 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

用于保护加密文件系统的 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 账户。

类型:字符串

长度限制:最大长度为 14。

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

PerformanceMode

文件系统的性能模式。

类型:字符串

有效值:generalPurpose | maxIO

ProvisionedThroughputInMibps

文件系统的预配置吞吐量(以 MiBps衡量单位)。对使用将 ThroughputMode 设置为 provisioned 的文件系统有效。

类型:双精度

有效范围:最小值为 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

如果 Amazon Web Services 账户已经创建了每个账户允许的最大文件系统数,则返回此内容。

HTTP 状态代码:403

InsufficientThroughputCapacity

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

HTTP 状态代码:503

InternalServerError

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

HTTP 状态代码:500

ThroughputLimitExceeded

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

HTTP 状态代码:400

UnsupportedAvailabilityZone

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

HTTP 状态代码:400

示例

创建加密 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" }

另请参阅

有关在特定语言的 Amazon SDK 中使用此 API 的更多信息,请参阅以下内容: