API Gateway 中的 API 私有 API 的自訂網域名稱 - Amazon API Gateway
保護自訂網域名稱的憑證私有金鑰私有自訂網域名稱的考量事項對於搭配其他 API Gateway 資源使用私有自訂網域名稱的考量事項私有自訂網域名稱與公有自訂網域名稱之間的差異對於私有 API 的自訂網域名稱的後續步驟

API Gateway 中的 API 私有 API 的自訂網域名稱

您也可以針對私有 API 建立自訂網域名稱。使用私有自訂網域名稱，為 API 呼叫者提供更簡單、更直覺的 URL。若使用私有自訂網域名稱，您就可以將複雜性降低，可以在 TLS 交握期間設定安全措施，並使用 AWS Certificate Manager(ACM) 控制網域名稱的憑證生命週期。如需更多詳細資訊，請參閱 保護自訂網域名稱的憑證私有金鑰。

私有 API 的自訂網域名稱在多個帳戶中不必是唯一的。您可以在帳戶 111122223333 和帳戶 555555555555 中建立 example.private.com，只要 ACM 憑證包含網域名稱即可。若要識別私有自訂網域名稱，請使用私有自訂網域名稱 ARN。此識別碼對私有自訂網域名稱是唯一的。

當您在 API Gateway 中建立私有自訂網域名稱時，您是 API 提供者。您可以使用 API Gateway 或 AWS Resource Access Manager (AWS RAM)，將您的私有自訂網域名稱提供給其他 AWS 帳戶。

當您調用私有自訂網域名稱時，您是 API 取用者。您可以從自己的 AWS 帳戶 或從其他 AWS 帳戶 取用私有自訂網域名稱。

當您取用私有自訂網域名稱時，您會在 VPC 端點與私有自訂網域名稱之間建立網域名稱存取關聯。有了網域名稱存取關聯，API 取用者就可以在與公有網際網路隔離時，調用您的私有自訂網域名稱。如需更多詳細資訊，請參閱 私有 API 之自訂網域名稱的 API 提供者和 API 取用者的任務。

保護自訂網域名稱的憑證私有金鑰

當您使用 ACM 請求 SSL/TLS 憑證來建立私有 API 的自訂網域名稱時，ACM 會產生公有/私有金鑰對。當您匯入憑證時，會產生金鑰對。公有金鑰會成為憑證的一部分。為了安全存放私有金鑰，ACM 會使用叫做 KMS 金鑰 (別名 aws/acm) 的 AWS KMS 來建立另一個金鑰。AWS KMS 會使用此金鑰來加密您的憑證的私有金鑰。如需詳細資訊，請參閱《 AWS Certificate Manager 使用者指南》中的 AWS Certificate Manager 中的資料保護。

API Gateway 使用的 AWS TLS Connection Manager 是一項只能存取 AWS 服務 的服務，可保護和使用憑證的私有金鑰。當您使用 ACM 憑證建立 API Gateway 自訂網域名稱時，API Gateway 會將您的憑證與 AWS TLS Connection Manager 相關聯。我們透過在 AWS KMS 中針對您的 AWS 受管金鑰建立授權來達此目的。此授權可讓 TLS Connection Manager 使用 AWS KMS 來解密憑證的私有金鑰。TLS Connection Manager 使用憑證和解密的 (純文字) 私有金鑰，建立與 API Gateway 服務用戶端的安全連線 (SSL/TLS 工作階段)。當憑證與 API Gateway 服務解除關聯時，授權便會失效。如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的授權。

如需更多詳細資訊，請參閱 Amazon API Gateway 的靜態資料加密。

私有自訂網域名稱的考量事項

下列考量事項可能會影響您使用私有自訂網域名稱：

  • API Gateway 需要約 15 分鐘來佈建您的私有自訂網域名稱。

  • 如果您更新 ACM 憑證，API Gateway 需要約 15 分鐘才能完成更新。在此期間，您的網域名稱處於 UPDATING 狀態，且您仍然可以存取它。

  • 若要調用私有自訂網域名稱，您必須建立網域名稱存取關聯。建立網域名稱存取關聯後，大約需要 15 分鐘才能準備就緒。

  • 私有自訂網域名稱 ARN 包含 account-id。當您建立網域名稱時，API Gateway 會使用 ARN 格式 arn:partition:apigateway:region::/domainnames。當您存取私有自訂網域名稱時，請使用 ARN 格式 arn:partition:apigateway:region:account-id:/domainnames/domain-name。

    您可能需要修改 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 來傳送流量，您可以使用 Amazon VPC 支援的所有 IP 位址類型。您可以在 VPC 端點上配置設定值，以傳送雙堆疊和 IPv6 流量。您無法使用 API Gateway 修改此項目。如需詳細資訊，請參閱新增 VPC 的 IPv6 支援。

  • 不支援多層基本路徑映射，例如將私有 API 映射至 /developers/feature，但您可以使用路由規則來建立多層路徑條件。如需更多詳細資訊，請參閱 在 API Gateway 中透過您的自訂網域名稱將流量傳送至 API。

  • 您無法為私有自訂網域名稱設定最低 TLS 版本。所有私有自訂網域名稱都有 TLS-1-2 的安全政策。

  • 您可以使用 VPC 端點政策來控制對私有自訂網域名稱的存取。如需詳細資訊，請參閱 在 API Gateway 中使用私有 API 的 VPC 端點政策 中的範例 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 取用者的任務。

如需有關建立可在您自己的 AWS 帳戶 中調用之私有自訂網域名稱的說明，請參閱 教學：建立和調用私有 API 的自訂網域名稱。

如需有關提供另一個私有自訂網域名稱的 AWS 帳戶 存取權說明，請參閱 API 提供者：使用 AWS RAM 分享您的私有自訂網域名稱。如需有關為 VPC 端點與另一個 AWS 帳戶 中的私有自訂網域名稱建立關聯的說明，請參閱 API 取用者：將 VPC 端點與和您分享的私有自訂網域名稱建立關聯。