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。

模式:.+

:必需 否

Backup

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

默认为 false。但是,如果你指定了AvailabilityZoneName,默认为true.

注意

Amazon Backup并未完全提供Amazon Web Services 区域提供 Amazon EFS 的区域。

类型: Boolean

:必需 否

CreationToken

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

类型: 字符串

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

模式:.+

:必需 是

Encrypted

一个布尔值,如果为 true,则创建一个加密文件系统。在创建加密文件系统时,可以选择指定现有文件系统。Amazon Key Management Service密钥(KMS 密钥)。如果未指定 KMS 密钥,则 Amazon EFS 的默认 KMS 密钥,/aws/elasticfilesystem,用于保护加密文件系统。

类型: Boolean

:必需 否

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,您必须将创建文件系统:加密参数为 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 模式。

类型: 字符串

有效值: generalPurpose | maxIO

:必需 否

ProvisionedThroughputInMibps

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

类型: Double

有效范围:最小值为 1.0。

:必需 否

Tags

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

类型: 数组Tag对象

:必需 否

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

AvailabilityZoneId

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

类型: 字符串

AvailabilityZoneName

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

类型: 字符串

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

模式:.+

CreationTime

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

类型: 时间戳

CreationToken

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

类型: 字符串

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

模式:.+

Encrypted

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

类型: Boolean

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

一个 IDAmazon 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

这些区域有: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-01T00:00:00 Z 以来的秒数。这些区域有:SizeInBytes值不表示文件系统的一致快照的大小,但在没有向文件系统中写入内容时,它最终保持一致。也就是说,SizeInBytes只有在文件系统的修改时间超过几个小时时才表示实际大小。否则,该值不是文件系统在任何时间点的确切大小。

类型:FileSystemSize 对象

Tags

与文件系统关联的标签,作为数组呈现的Tag对象。

类型: 数组Tag对象

ThroughputMode

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

类型: 字符串

有效值: bursting | provisioned

错误

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": 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 的更多信息,请参阅以下内容: