本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 API Gateway 中設定區域性自訂網域名稱
設定區域性自訂網域名稱

使用區域性自訂網域名稱來建立易於使用的 API 基礎 URL。有了區域性自訂網域名稱，您就可以將 HTTP 和 REST API 階段映射至相同的自訂網域名稱，並使用相互 TLS 驗證。

## 考量事項


以下是區域自訂網域名稱的考量事項：
+ 您必須提供區域特定的 ACM 憑證。此憑證必須與您的 API 位於相同的區域。如需建立或上傳自訂網域名稱憑證的詳細資訊，請參閱「[在 中備妥憑證 AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md)」。
+ 當您使用 ACM 憑證建立 (或遷移) 區域性自訂網域名稱，API Gateway 會在您的帳戶中建立服務連結角色。需要此服務連結角色，才能將您的 ACM 憑證附加至您的區域性端點。角色名為 **AWSServiceRoleForAPIGateway**，並會將 **APIGatewayServiceRolePolicy** 受管政策附加到該角色。如需使用服務連結角色的詳細資訊，請參閱[使用服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)。
+ 建立區域自訂網域名稱之後，您必須建立 DNS 記錄，以便將自訂網域名稱指向區域網域。如此可讓繫結至自訂網域名稱的流量路由至 API 的區域性主機名稱。

  DNS 記錄可以是 CNAME 或 A Alias 記錄。如果您使用 Route 53 作為 DNS 供應商，請建立 A Alias 記錄。如果您使用第三方 DNS 供應商，請使用 CNAME 記錄。如果您使用 CNAME 記錄，並建立 API Gateway 介面 VPC 端點且為私有 API 啟用私有 DNS，則無法在託管您私有 API 的 VPC 內解析自訂網域名稱。

## 建立區域性自訂網域名稱


下列程序顯示如何建立區域性自訂網域名稱。完成此程序後，您會建立路由規則來將 API 的階段路由傳送至自訂網域名稱。

------
#### [ AWS 管理主控台 ]

1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 從主要導覽窗格中，選擇 **Custom Domain Names (自訂網域名稱)**。

1. 選擇 **Create** (建立)。

1. 在 **Domain name (網域名稱)** 中，輸入網域名稱。

1. 對於**路由模式**，選擇**僅限路由規則**。

   在此路由模式中，您只能使用路由規則將流量從自訂網域名稱傳送至 API。如需詳細資訊，請參閱[在 API Gateway 中透過您的自訂網域名稱將流量傳送至 API](rest-api-routing-mode.md)。

1. 針對**最低 TLS 版本**，選取版本。

1. 在**端點組態**下，針對 **API 端點類型**，選擇**區域性**。

1. 選擇 ACM 憑證。憑證必須與 API 位於相同的區域。

1. 選擇 **Create** (建立)。

------
#### [ AWS CLI ]

以下 [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html) 命令會建立自訂網域名稱：

```
aws apigatewayv2 create-domain-name \ 
    --domain-name 'regional.example.com' \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --routing-mode ROUTING_RULE_ONLY
```

輸出將如下所示：

```
{
    "ApiMappingSelectionExpression": "$request.basepath",
    "DomainName": "regional.example.com",
    "DomainNameConfigurations": [
        {
            "ApiGatewayDomainName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
            "CertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678",
            "DomainNameStatus": "AVAILABLE",
            "EndpointType": "REGIONAL",
            "HostedZoneId": "Z2OJLYMUO9EFXC",
            "SecurityPolicy": "TLS_1_2"
        }
        "RoutingMode": "ROUTING_RULE_ONLY"
    ]
}
```

`DomainNameConfigurations` 屬性值會傳回區域性 API 的主機名稱。您必須建立 DNS 記錄，將您的自訂網域名稱指向此區域性網域名稱。如此可讓繫結至自訂網域名稱的流量路由至此區域性 API 的主機名稱。

------

## 為您的區域自訂網域名稱建立路由規則


建立自訂網域名稱後，您可以設定將流量從自訂網域名稱路由傳送至 API 的方式。由於您將路由模式設定為 `ROUTING_RULE_ONLY`，因此您會使用路由規則將自訂網域名稱的傳入請求路由傳送至您的 API。

在此範例中，您會建立全部擷取規則，以便將自訂網域名稱的所有傳入請求路由傳送至 API 的某一個階段。您也可以根據不同的標頭和路徑條件設定路由規則。如需詳細資訊，請參閱[將 API 階段連線至 REST API 自訂網域名稱的路由規則](rest-api-routing-rules.md)。

------
#### [ AWS 管理主控台 ]

1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 選擇自訂網域名稱。

1. 在**路由詳細資訊**索引標籤上，選擇**新增路由規則**。

1. 選擇**新增條件**以新增條件。

1. 保留此規則且不設任何條件。這會將自訂網域名稱的所有請求路由傳送至您的目標 API 和目標階段。

1. 針對**動作**，使用下拉式清單選取您的目標 API 和目標階段。

1. 選擇**下一步**。

1. 在優先順序欄位中，輸入 **100**。

   API Gateway 會依優先順序評估規則，從最低值到最高值。由於這是全部擷取規則，因此您會使用高優先順序讓 API Gateway 能夠比對您先建立的任何其他規則。

1. 選擇**建立路由規則**。

------
#### [ AWS CLI ]

以下 `create-routing-rule` 命令會建立全部擷取路由規則：

```
aws apigatewayv2 create-routing-rule \
  --domain-name 'regional.example.com' \
  --priority 100 \
  --conditions  \
  --actions '[{
    "InvokeApi": {
      "ApiId": "a1b2c3",
      "Stage": "prod"
    }
  }]'
```

------

您隨時可以變更路由模式並建立新規則。如需詳細資訊，請參閱[在 API Gateway 中透過您的自訂網域名稱將流量傳送至 API](rest-api-routing-mode.md)。

## 為您的區域性自訂網域名稱建立 DNS 記錄


建立自訂網域名稱和建立基本路徑映射後，您可以建立 DNS 記錄，將自訂網域名稱指向新建立的區域性網域名稱。

------
#### [ AWS 管理主控台 ]

若要使用 AWS 管理主控台，請遵循 Route 53 文件[設定 Route 53 將流量路由到 API Gateway](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)。

------
#### [ AWS CLI ]

若要設定您的 DNS 記錄，將區域性自訂網域名稱映射至指定託管區域 ID 的主機名稱，請先建立 JSON 檔案，其中包含設定區域性網域名稱 DNS 記錄的組態。

下列 `setup-dns-record.json` 顯示如何建立 DNS `A` 記錄，以將區域性自訂網域名稱 (`regional.example.com`) 映射至建立自訂網域名稱時所佈建的區域性主機名稱 (`d-numh1z56v6.execute-api.us-west-2.amazonaws.com`)。`DNSName` 的 `HostedZoneId` 與 `AliasTarget` 屬性可分別接受自訂網域名稱的 `regionalDomainName` 與 `regionalHostedZoneId` 值。您也可以在 [Amazon API Gateway 端點和配額](https://docs.aws.amazon.com/general/latest/gr/apigateway.html)中取得區域性 Route 53 託管區域 ID。

```
{
  "Changes": [
    {
      "Action": "CREATE",
      "ResourceRecordSet": {
        "Name": "regional.example.com",
        "Type": "A",
        "AliasTarget": {
          "DNSName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
          "HostedZoneId": "Z2OJLYMUO9EFXC",
          "EvaluateTargetHealth": false
        }
      }
    }
  ]
}
```

以下 [change-resource-record-sets](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html) 會為您的區域自訂網域名稱建立 DNS 記錄：

```
aws route53 change-resource-record-sets \
    --hosted-zone-id Z2OJLYMUO9EFXC \
    --change-batch file://path/to/your/setup-dns-record.json
```

將 `hosted-zone-id` 取代為您帳戶中所設定之 DNS 記錄的 Route 53 託管區域 ID。`change-batch` 參數值會指向資料夾 (*path/to/your*) 中的 JSON 檔案 (*setup-dns-record.json*)。

------