本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# API Gateway 中的 API 私有 API 的自訂網域名稱
您也可以針對私有 API 建立自訂網域名稱。使用私有自訂網域名稱，為 API 呼叫者提供更簡單、更直覺的 URL。使用私有自訂網域名稱，您可以降低複雜性、在 TLS 交握期間設定安全措施，以及使用 AWS Certificate Manager (ACM) 控制網域名稱的憑證生命週期。如需詳細資訊，請參閱[保護自訂網域名稱的憑證私有金鑰](#apigateway-private-custom-domains-secure-certificate-private-key)。
私有 API 的自訂網域名稱在多個帳戶中不必是唯一的。您可以在帳戶 111122223333 和帳戶 555555555555 中建立 `example.private.com`，只要 ACM 憑證包含網域名稱即可。若要識別私有自訂網域名稱，請使用私有自訂網域名稱 ARN。此識別碼對私有自訂網域名稱是唯一的。
當您在 API Gateway 中建立私有自訂網域名稱時，您是 *API 提供者*。您可以使用 AWS 帳戶 API Gateway 或 AWS Resource Access Manager () 將您的私有自訂網域名稱提供給其他AWS RAM。
當您調用私有自訂網域名稱時，您是 *API 取用者*。您可以從自己的 AWS 帳戶 或另一個 使用私有自訂網域名稱 AWS 帳戶。
當您取用私有自訂網域名稱時，您會在 VPC 端點與私有自訂網域名稱之間建立網域名稱存取關聯。有了網域名稱存取關聯，API 取用者就可以在與公有網際網路隔離時，調用您的私有自訂網域名稱。如需詳細資訊，請參閱[私有 API 之自訂網域名稱的 API 提供者和 API 取用者的任務](apigateway-private-custom-domains-associations.md)。
## 保護自訂網域名稱的憑證私有金鑰
當您使用 ACM 請求 SSL/TLS 憑證來建立私有 API 的自訂網域名稱時，ACM 會產生公有/私有金鑰對。當您匯入憑證時，會產生金鑰對。公有金鑰會成為憑證的一部分。為了安全地存放私有金鑰，ACM 會使用 AWS KMS名為 KMS 金鑰的另一個金鑰，別名為 **aws/acm**。 AWS KMS 使用此金鑰來加密憑證的私有金鑰。如需詳細資訊，請參閱《 *AWS Certificate Manager 使用者指南*》中的 [AWS Certificate Manager中的資料保護](https://docs.aws.amazon.com/acm/latest/userguide/data-protection.html)。
API Gateway AWS 使用 TLS Connection Manager，這是只能存取的服務 AWS 服務，用於保護和使用憑證的私有金鑰。當您使用 ACM 憑證建立 API Gateway 自訂網域名稱時，API Gateway 會將您的憑證與 AWS TLS Connection Manager 建立關聯。我們會針對您的 AWS 受 AWS KMS 管金鑰在 中建立授予，藉此達成此目的。此授權允許 TLS Connection Manager 使用 AWS KMS 解密憑證的私有金鑰。TLS Connection Manager 使用憑證和解密的 (純文字) 私有金鑰，建立與 API Gateway 服務用戶端的安全連線 (SSL/TLS 工作階段)。當憑證與 API Gateway 服務解除關聯時，授權便會失效。如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》**中的[授權](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html)。
如需詳細資訊，請參閱[Amazon API Gateway 的靜態資料加密](data-protection-encryption.md#data-protection-at-rest)。
## 私有自訂網域名稱的考量事項
下列考量事項可能會影響您使用私有自訂網域名稱：
+ API Gateway 需要約 15 分鐘來佈建您的私有自訂網域名稱。
+ 如果您更新 ACM 憑證，API Gateway 需要約 15 分鐘才能完成更新。在此期間，您的網域名稱處於 `UPDATING` 狀態，且您仍然可以存取它。
+ 若要調用私有自訂網域名稱，您必須建立網域名稱存取關聯。建立網域名稱存取關聯後，大約需要 15 分鐘才能準備就緒。
+ 私有自訂網域名稱 ARN 包含 *account-id* 和 *domain-name-id*。當您建立網域名稱時，API Gateway 會使用 ARN 格式 `arn:partition:apigateway:region::/domainnames/domain-name`。當您存取私有自訂網域名稱時，請使用 ARN 格式 `arn:partition:apigateway:region:account-id:/domainnames/domain-name+domain-name-id`。
您可能需要修改 IAM 許可，以便在建立私有網域名稱之後允許存取。
+ 您無法從相同的 VPC 端點調用具有相同名稱的私有自訂網域名稱。例如，若您想要調用 `arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234` 和 `arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+xyz000`，請為每個私有自訂網域名稱與不同的 VPC 端點建立關聯。
+ 支援萬用字元憑證，例如 `*.private.example.com` 的憑證。
+ 不支援萬用字元自訂網域名稱。
+ 僅支援具 2048 位元金鑰長度的 RSA 憑證，以及具 256 位元和 384 位元金鑰長度的 ECDSA 憑證。
+ 您無法將私有 API 的 IP 位址類型設定為僅允許 IPv4 位址調用您的私有 API。僅支援雙堆疊。如需詳細資訊，請參閱[API Gateway 中 REST API 的 IP 位址類型](api-gateway-ip-address-type.md)。
+ 若要使用私有 API 來傳送流量，您可以使用 Amazon VPC 支援的所有 IP 位址類型。您可以在 VPC 端點上配置設定值，以傳送雙堆疊和 IPv6 流量。您無法使用 API Gateway 修改此項目。如需詳細資訊，請參閱[新增 VPC 的 IPv6 支援](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6-add.html)。
+ 不支援多層基本路徑映射，例如將私有 API 映射至 `/developers/feature`，但您可以使用路由規則來建立多層路徑條件。如需詳細資訊，請參閱[在 API Gateway 中透過您的自訂網域名稱將流量傳送至 API](rest-api-routing-mode.md)。
+ 您無法為私有自訂網域名稱設定最低 TLS 版本。所有私有自訂網域名稱都有 `TLS-1-2` 的安全政策。
+ 您可以使用 VPC 端點政策來控制對私有自訂網域名稱的存取。如需詳細資訊，請參閱 [在 API Gateway 中使用私有 API 的 VPC 端點政策](apigateway-vpc-endpoint-policies.md) 中的範例 4 和 5。
+ 您必須為私有 API 和私有自訂網域名稱建立不同的資源政策。若要調用私有自訂網域名稱，API 取用者需要存取私有自訂網域名稱資源政策、私有 API 資源政策，以及私有 API 上的任何 VPC 端點政策或授權。
## 對於搭配其他 API Gateway 資源使用私有自訂網域名稱的考量事項
下列考量可能會影響您如何搭配其他 API Gateway 資源使用私有自訂網域名稱：
+ 您無法將流量從私有自訂網域名稱傳送至公有 API。
+ 當私有 API 映射至私有自訂網域名稱時，您無法變更 API 的端點類型。
+ 您無法將公有自訂網域名稱遷移至私有自訂網域名稱。
+ 如果您具有用於存取公有自訂網域名稱的 VPC 端點，請勿使用該端點來建立與私有自訂網域名稱的網域名稱存取關聯。
## 私有自訂網域名稱與公有自訂網域名稱之間的差異
以下說明私有和公有自訂網域名稱之間的差異：
+ 私有自訂網域名稱在多個帳戶中不必是唯一的。
+ 私有網域名稱有網域名稱 ID。此 ID 可作為唯一識別私有自訂網域名稱的方式，而公有自訂網域名稱不會產生此 ID。
+ 當您使用 AWS CLI 更新或刪除私有自訂網域名稱時，必須提供網域名稱 ID。如果您具有名為 `example.com` 的私有自訂網域名稱，以及名為 `example.com` 的公有自訂網域名稱，而且您沒有提供網域名稱 ID，則 API Gateway 會修改或刪除您的公有自訂網域名稱。
## 對於私有 API 的自訂網域名稱的後續步驟
如需 API 提供者和 API 取用者的任務相關資訊，請參閱 [私有 API 之自訂網域名稱的 API 提供者和 API 取用者的任務](apigateway-private-custom-domains-associations.md)。
如需建立可在自己的私有自訂網域名稱的說明 AWS 帳戶，請參閱 [教學：建立和調用私有 API 的自訂網域名稱](apigateway-private-custom-domains-tutorial.md)。
如需提供另一個私有自訂網域名稱 AWS 帳戶 存取權的說明，請參閱 [API 提供者：使用 共用您的私有自訂網域名稱 AWS RAM](apigateway-private-custom-domains-provider-share.md)。如需將您的 VPC 端點與另一個私有自訂網域名稱建立關聯的說明 AWS 帳戶，請參閱 [API 取用者：將 VPC 端點與和您分享的私有自訂網域名稱建立關聯](apigateway-private-custom-domains-consumer-create.md)。