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

# Amazon EFS API
<a name="api-reference"></a>

Amazon EFS API 是基于 [HTTP（RFC 2616）](https://www.ietf.org/rfc/rfc2616.txt)的网络协议。对于每个 API 调用，您针对要在其中管理文件系统的 AWS 区域，向特定于区域的 Amazon EFS API 端点发出 HTTP 请求。API 会对 HTTP 请求/响应正文使用 JSON (RFC 4627) 文档。

Amazon EFS API 是一种 RPC 模型。在该模型中具有一套固定的操作，客户端已知每个操作的语法，而无需事先进行任何交互。在以下部分中，您可以找到使用抽象 RPC 表示法描述每个 API 操作的信息。不会在线显示每个操作的名称。对于每个操作，该主题指定了指向 HTTP 请求要素的映射。

给定请求映射到的特定 Amazon EFS 操作由请求的方法（GET、PUT、POST 或 DELETE）和其请求 URI 所匹配的各种模式共同确定。如果操作为 PUT 或 POST，则 Amazon EFS 将从请求 URI 路径分段、查询参数和请求正文内的 JSON 对象中提取调用参数。

**注意**  
虽然不会在线显示操作名称（如 `CreateFileSystem`），但这些名称在 AWS Identity and Access Management (IAM) 策略中是有意义的。有关更多信息，请参阅 [Amazon EFS 的身份和访问管理](security-iam.md)。  
操作名称还可用于为命令行工具中的命令和 AWS SDK API 的元素命名。例如，名为 AWS CLI 的 `create-file-system` 命令映射到 `CreateFileSystem` 操作。  
操作名称还会显示在 Amazon EFS API 调用的 AWS CloudTrail 日志中。

## API 终端节点
<a name="api-reference-endpoint"></a>

端点是作为 AWS Web 服务入口点的 URL。Amazon EFS 支持以下端点类型：
+ IPv4 端点
+ 双栈（IPv4 和 IPv6）端点
+ [FIPS 端点](https://docs.aws.amazon.com/general/latest/gr/rande.html#FIPS-endpoints)

当您发出请求时，您可以指定要使用的端点。如果不指定端点，则默认使用 IPv4 端点。要使用不同的端点类型，您必须在请求中指定。有关如何执行此操作的示例，请参阅[指定端点](#endpoints-specifying)。有关可用端点的表，请参阅 [Amazon EFS 端点和配额](https://docs.aws.amazon.com/general/latest/gr/elasticfilesystem.html)。

### IPv4 端点
<a name="ipv4-endpoints"></a>

IPv4 端点仅支持 IPv4 流量。IPv4 端点适用于所有区域。IPv4 端点的格式取决于区域。
+ 对于 AWS 商业区域中的 IPv4 端点，格式为 `elasticfilesystem.{{region}}.amazonaws.com`。

  例如，如果您指定 `elasticfilesystem.us-west-2.amazonaws.com` 为端点，我们会将您的请求定向到美国西部（俄勒冈州）区域（us-west-2）端点。
+ 对于中国区域的 IPv4 端点，格式为 `elasticfilesystem.{{region}}.amazonaws.com.rproxy.govskope.us.cn`。

  例如，在中国（北京）区域，Amazon EFS API 的端点为 `elasticfilesystem---cn-north-1.amazonaws.com.rproxy.govskope.us.cn`。

### 双栈（IPv4 和 IPv6）端点
<a name="dualstack-endpoints"></a>

同时支持 IPv4 和 IPv6 流量的双堆栈端点。当您向双堆栈端点发出请求时，端点 URL 解析为 IPv6 或 IPv4 地址，具体取决于您的网络和客户端使用的协议。双栈端点的格式取决于区域。
+ 对于 AWS 商业区域中的双栈端点，格式为 `efs.{{aws-region}}.api.aws`。

  例如，对于美国西部（俄勒冈州）区域（us-west-2），双栈端点是 `efs.eu-west-2.api.aws`。
+ 对于中国区域的双栈端点，格式为 `efs.{{region}}.api.amazonwebservices.com.rproxy.govskope.us.cn`。

  例如，中国（北京）区域的双堆栈端点是 `efs---cn-north-1---api.amazonwebservices.com.rproxy.govskope.us.cn`。

### 指定端点
<a name="endpoints-specifying"></a>

以下示例说明了如何使用 Amazon EFS 的 AWS CLI 为美国西部（北加利福尼亚）区域（us-west-1）指定端点。

IPv4

```
aws efs get-rest-apis --region us-west-1 --endpoint-url https://{{elasticfilesystem.us-west-1.amazonaws.com}}
```

双堆栈

```
aws efs get-rest-apis --region us-west-1 --endpoint-url https://{{efs.us-west-1.api.aws}}
```

## API 版本
<a name="api-reference-version"></a>

用于调用的 API 版本是由请求 URI 的第一个路径分段确定的，并且其格式为 ISO 8601 日期。有关示例，请查看 [CreateFileSystem](API_CreateFileSystem.md)。

本文档中所描述的版本为 API 版本 2015-02-01。

## 相关主题
<a name="api-reference-related-topics"></a>

以下各节描述了 API 操作，以及如何创建签名以便进行请求身份验证和如何使用 IAM 策略为这些 API 操作授权。
+ [Amazon EFS 的身份和访问管理](security-iam.md)
+ [操作](API_Operations.md)
+ [数据类型](API_Types.md)

## 使用 Amazon EFS 的查询 API 请求速率
<a name="api-throttling"></a>

针对每个区域限制每个 AWS 账户的 Amazon EFS API 请求可帮助提高服务性能。无论是来自于应用程序、AWS CLI，还是 Amazon EFS 控制台，所有 Amazon EFS API 调用都不能超过允许的最大 API 请求速率。对于不同的 AWS 区域，最大 API 请求速率可能会有所不同。发出 API 请求是由于底层 AWS 账户。

如果 API 请求超过其类别的 API 请求速率，请求将返回 `ThrottlingException` 错误代码。为防止出现该错误，请确保您的应用程序不会在高速率下重试 API 请求。您可以执行该操作，但前提是在轮询时格外小心并使用指数回退重试。

### 轮询
<a name="efs-polling"></a>

您的应用程序可能需要反复调用 API 操作以检查状态更新。在开始轮询之前，请为请求留出完成所需的估算时间。在开始轮询时，请在连续的请求之间添加相应的睡眠间隔。为了获得最佳的效果，请使用递增的睡眠间隔。

### 重试或批处理
<a name="efs-retries"></a>

您的应用程序可能需要在失败后重试 API 请求，或处理多个资源（例如，所有 Amazon EFS 文件系统）。要降低 API 请求的速率，请在连续的请求之间添加相应的睡眠间隔。为了获得最佳的效果，请使用递增或可变的睡眠间隔。

### 计算睡眠间隔
<a name="efs-sleep-interval-calculation"></a>

在需要轮询或重试 API 请求时，我们建议您使用指数回退算法计算 API 调用之间的睡眠间隔。指数回退的原理是对于连续错误响应，重试等待间隔越来越长。有关更多信息以及该算法的实施示例，请参阅《Amazon Web Services 一般参考**》中的[重试行为](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)。