# 将 API 阶段映射到 WebSocket API 的自定义域名
<a name="websocket-api-mappings"></a>

您可以使用 API 映射将 API 阶段连接到自定义域名。创建域名并配置 DNS 记录后，您可以使用 API 映射通过自定义域名向 API 发送流量。

API 映射指定了用于映射的 API、阶段以及可选的路径。例如，您可以将 API 的 `production` 阶段映射到 `wss://api.example.com/orders`。

在创建 API 映射之前，您必须拥有 API、阶段和自定义域名。要了解有关创建自定义域名的更多信息，请参阅 [在 API Gateway 中设置区域自定义域名](apigateway-regional-api-custom-domain-create.md)。

## 限制
<a name="websocket-api-mappings-restrictions"></a>
+ 在 API 映射中，自定义域名和映射的 API 必须位于同一个Amazon账户中。
+ API 映射必须仅包含字母、数字和以下字符：`$-_.+!*'()`。
+ API 映射中路径的最大长度为 300 个字符。
+ 您不能将 WebSocket API 映射到与 HTTP API 或 REST API 相同的自定义域名。
+ 如果您创建具有多个级别的 API 映射，API Gateway 会将所有标头名称转换为小写。

## 创建 API 映射
<a name="websocket-api-mappings-examples"></a>

要创建 API 映射，您必须首先创建自定义域名、API 和阶段。有关使用自定义域名的更多信息，请参阅 [在 API Gateway 中设置区域自定义域名](apigateway-regional-api-custom-domain-create.md)。

------
#### [ Amazon Web Services 管理控制台 ]

**创建 API 映射**

1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.amazonaws.cn/apigateway)。

1. 选择**自定义域名**。

1. 选择您已经创建的自定义域名。

1. 选择 **API 映射**。

1. 选择 **Configure API mappings (配置 API 映射)**。

1. 选择 **Add new mapping (添加新映射)**。

1. 输入 **API**、**阶段**以及可选的**路径**。

1. 选择**保存**。

------
#### [ Amazon CLI ]

使用以下 [create-api-mapping](https://docs.amazonaws.cn/cli/latest/reference/apigatewayv2/create-api-mapping.html) 命令创建 API 映射。在此示例中，API Gateway 将请求发送到 `api.example.com/v1`，到指定的 API 和阶段。

```
aws apigatewayv2 create-api-mapping \
    --domain-name api.example.com \
    --api-mapping-key v1 \
    --api-id a1b2c3d4 \
    --stage test
```

------
#### [ Amazon CloudFormation ]

以下 Amazon CloudFormation 示例会创建一个 API 映射。

```
MyApiMapping:
  Type: 'AWS::ApiGatewayV2::ApiMapping'
  Properties:
    DomainName: api.example.com
    ApiMappingKey: 'v1'
    ApiId: !Ref MyApi
    Stage: !Ref MyStage
```

------