選取您的 Cookie 偏好設定

我們使用提供自身網站和服務所需的基本 Cookie 和類似工具。我們使用效能 Cookie 收集匿名統計資料,以便了解客戶如何使用我們的網站並進行改進。基本 Cookie 無法停用,但可以按一下「自訂」或「拒絕」以拒絕效能 Cookie。

如果您同意,AWS 與經核准的第三方也會使用 Cookie 提供實用的網站功能、記住您的偏好設定,並顯示相關內容,包括相關廣告。若要接受或拒絕所有非必要 Cookie,請按一下「接受」或「拒絕」。若要進行更詳細的選擇,請按一下「自訂」。

教學:建立和調用私有 API 的自訂網域名稱

焦點模式
教學:建立和調用私有 API 的自訂網域名稱 - Amazon API Gateway

在本教學課程中,您會建立一個可以在自己的帳戶中的 VPC 中調用的私有自訂網域名稱。為完成此操作,您既是 API 提供者,也是 API 取用者。您需要現有的私有 API 和 VPC 端點才能完成本教學課程。如果您有用於存取公有自訂網域名稱的 VPC 端點,請勿將其用於本教學課程或建立任何網域名稱存取關聯。

步驟 1:建立私有自訂網域名稱

您可以透過指定網域名稱、ACM 憑證和 execute-api 服務的政策來建立私有自訂網域名稱,以控制哪些 VPC 端點可以調用該名稱。

AWS Management Console
建立私有自訂網域名稱
  1. 在以下網址登入 API Gateway 主控台:https://console.aws.amazon.com/apigateway

  2. 在主要導覽窗格中,選擇自訂網域名稱

  3. 選擇新增網域名稱

  4. Domain name (網域名稱) 中,輸入網域名稱。

    您的 ACM 憑證必須包含此網域名稱,但網域名稱不必是唯一的。

  5. 選取私有 - 新建

  6. 針對 ACM 憑證,選取憑證。

  7. 選擇新增網域名稱

API Gateway 會使用 deny 所有資源政策佈建網域名稱。這是 execute-api 服務的資源政策。您需要更新此資源政策以授予對 VPC 端點的存取權,如此才能調用您的私有自訂網域名稱。

更新您的資源政策
  1. 選擇資源政策標籤,然後選擇編輯資源政策

  2. 在程式碼編輯器中輸入下列資源政策。將 VPC 端點 vpce-abcd1234efg 取代為您自己的 VPC 端點 ID。

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-abcd1234efg" } } } ] }
  3. 選擇儲存變更

AWS CLI

當您使用 AWS CLI 建立私有自訂網域名稱時,您會提供資源政策給 execute-api 服務,以使用 --policy "{\"jsonEscapedPolicyDocument\"}" 參數授予對 VPC 端點存取權,並用於調用私有自訂網域名稱。之後您可以修改此政策。

針對此範例,您附加下列資源政策以做為 policy。此政策僅允許從 VPC 端點 vpce-abcd1234efg 傳入至私有自訂網域名稱的流量:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-abcd1234efg" } } } ] }

在此範例中,您可以使用逸出字串來定義您的 policy。您也可以從檔案載入參數來定義您的 policy

下列 create-domain-name 命令會建立私有自訂網域名稱:

aws apigateway create-domain-name \ --domain-name 'private.example.com' \ --certificate-arn 'arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef' \ --security-policy 'TLS_1_2' \ --endpoint-configuration '{"types":["PRIVATE"]}' \ --policy "{\"Version\": \"2012-10-17\",\"Statement\": [{\"Effect\": \"Allow\",\"Principal\": \"*\",\"Action\": \"execute-api:Invoke\",\"Resource\":[\"execute-api:/*\"]},{\"Effect\": \"Deny\",\"Principal\": \"*\",\"Action\": \"execute-api:Invoke\",\"Resource\":[\"execute-api:/*\"],\"Condition\":{\"StringNotEquals\":{\"aws:SourceVpce\": \"vpce-abcd1234efg\"}}}]}"

輸出如下所示:

{ "domainName": "private.example.com", "domainNameId": "abcd1234", "domainNameArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234", "certificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef", "certificateUploadDate": "2024-09-10T10:31:20-07:00", "endpointConfiguration": { "types": [ "PRIVATE" ] }, "domainNameStatus": "AVAILABLE", "securityPolicy": "TLS_1_2", "policy": "{\\\"Version\\\":\\\"2012-10-17\\\",\\\"Statement\\\":[{\\\"Effect\\\":\\\"Allow\\\",\\\"Principal\\\":\\\"*\\\",\\\"Action\\\":\\\"execute-api:Invoke\\\",\\\"Resource\\\":\\\"execute-api:\\/*\\\"},{\\\"Effect\\\":\\\"Deny\\\",\\\"Principal\\\":\\\"*\\\",\\\"Action\\\":\\\"execute-api:Invoke\\\",\\\"Resource\\\":\\\""execute-api:\\/*\\\",\\\"Condition\\\":{\\\"StringNotEquals\\\":{\\\"aws:SourceVpce\\\":\\\"vpce-abcd1234efg\\\"}}}]}" }
建立私有自訂網域名稱
  1. 在以下網址登入 API Gateway 主控台:https://console.aws.amazon.com/apigateway

  2. 在主要導覽窗格中,選擇自訂網域名稱

  3. 選擇新增網域名稱

  4. Domain name (網域名稱) 中,輸入網域名稱。

    您的 ACM 憑證必須包含此網域名稱,但網域名稱不必是唯一的。

  5. 選取私有 - 新建

  6. 針對 ACM 憑證,選取憑證。

  7. 選擇新增網域名稱

API Gateway 會使用 deny 所有資源政策佈建網域名稱。這是 execute-api 服務的資源政策。您需要更新此資源政策以授予對 VPC 端點的存取權,如此才能調用您的私有自訂網域名稱。

更新您的資源政策
  1. 選擇資源政策標籤,然後選擇編輯資源政策

  2. 在程式碼編輯器中輸入下列資源政策。將 VPC 端點 vpce-abcd1234efg 取代為您自己的 VPC 端點 ID。

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-abcd1234efg" } } } ] }
  3. 選擇儲存變更

步驟 2:建立基本路徑映射,將私有 API 映射至私有自訂網域名稱

建立私有自訂網域名稱後,您可以將私有 API 映射至該名稱。基本路徑映射可以透過私有自訂網域名稱與相關聯基本路徑的組合來存取 API。建議您將單一私有自訂網域用作多個私有 API 的主機名稱。

所有 API 提供者都需要建立基本路徑映射,即使您不打算調用自己的 API。您也需要授予對 VPC 端點的存取權,如此才能調用映射至私有自訂網域名稱的任何私有 API。

AWS Management Console
建立基本路徑映射
  1. 在以下網址登入 API Gateway 主控台:https://console.aws.amazon.com/apigateway

  2. 在主要導覽窗格中,選擇自訂網域名稱

  3. 選擇私有自訂網域名稱。

  4. API 映射標籤上,選擇設定映射

  5. 選擇 Add new mapping (新增映射)

  6. 輸入 APIStage (階段),以及選擇性地輸入 Path (路徑)。

  7. 選擇儲存

AWS CLI

下列 create-base-path-mapping 命令會在私有 API 和私有自訂網域名稱之間建立映射:

aws apigateway create-base-path-mapping \ --domain-name-id abcd1234 \ --domain-name 'private.example.com' \ --rest-api-id a1b2c3 \ --stage prod \ --base-path v1

輸出將如下所示:

{ "basePath": "v1", "restApiId": "a1b2c3", "stage": "prod" }
建立基本路徑映射
  1. 在以下網址登入 API Gateway 主控台:https://console.aws.amazon.com/apigateway

  2. 在主要導覽窗格中,選擇自訂網域名稱

  3. 選擇私有自訂網域名稱。

  4. API 映射標籤上,選擇設定映射

  5. 選擇 Add new mapping (新增映射)

  6. 輸入 APIStage (階段),以及選擇性地輸入 Path (路徑)。

  7. 選擇儲存

注意

如果您希望其他 AWS 帳戶 調用您的私有自訂網域名稱,在完成本教學課程後,請遵循 API 提供者:使用 AWS RAM 分享您的私有自訂網域名稱 中的步驟。

步驟 3:在您的自訂網域名稱和 VPC 端點之間建立網域名稱存取關聯

接著,您可以在私有自訂網域名稱和 VPC 端點之間建立網域名稱存取關聯。您的 VPC 端點會利用網域名稱存取關聯,在與公有網際網路隔離時調用您的私有自訂網域名稱。

AWS Management Console
建立網域名稱存取關聯
  1. 在以下網址登入 API Gateway 主控台:https://console.aws.amazon.com/apigateway

  2. 在主要導覽窗格中,選擇自訂網域名稱

  3. 選擇私有自訂網域名稱。

  4. 資源共用標籤中,針對網域名稱存取關聯選擇建立網域名稱存取關聯

  5. 針對網域名稱 ARN,選取您的網域名稱。

  6. 針對 VPC 端點 ID,選取您在步驟 1 中提供存取權的 VPC 端點 ID。

  7. 選擇網域名稱存取關聯

您也可以使用主控台的網域名稱存取關聯頁面建立網域名稱存取關聯。

AWS CLI

下列 create-domain-name-access-association 命令會在您的私有自訂網域名稱和 VPC 端點之間建立網域名稱存取關聯。

aws apigateway create-domain-name-access-association \ --domain-name-arn arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234 \ --access-association-source vpce-abcd1234efg \ --access-association-source-type VPCE \ --region us-west-2

輸出將如下所示:

{ "domainNameAccessAssociationARN": "arn:aws:apigateway:us-west-2:111122223333:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg", "accessAssociationSource": "vpce-abcd1234efg", "accessAssociationSourceType": "VPCE", "domainNameARN" : "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234" }
建立網域名稱存取關聯
  1. 在以下網址登入 API Gateway 主控台:https://console.aws.amazon.com/apigateway

  2. 在主要導覽窗格中,選擇自訂網域名稱

  3. 選擇私有自訂網域名稱。

  4. 資源共用標籤中,針對網域名稱存取關聯選擇建立網域名稱存取關聯

  5. 針對網域名稱 ARN,選取您的網域名稱。

  6. 針對 VPC 端點 ID,選取您在步驟 1 中提供存取權的 VPC 端點 ID。

  7. 選擇網域名稱存取關聯

您也可以使用主控台的網域名稱存取關聯頁面建立網域名稱存取關聯。

建立您的網域名稱存取關聯後,大約需要 15 分鐘才能準備就緒。您在等待時,可以繼續執行下列步驟。

步驟 4:建立 Route 53 託管區域

在您更新資源政策,並為私有自訂網域名稱與 VPC 端點建立關聯後,可以在 Route 53 中建立私有託管區域以解析自訂網域名稱。託管區域是一種容器,其中包含的資訊說明您可以如何在一或多個 VPC 中路由某個網域的流量,而不用將資源公開至網際網路。如需詳細資訊,請參閱使用私有託管區域

AWS Management Console

若要使用 AWS Management Console,請參閱《Amazon Route 53 開發人員指南》中的建立私有託管區域

對於名稱,請使用私有自訂網域名稱的名稱。對於 VPC ID,請使用包含您在先前步驟中使用的 VPC 端點的 VPC。

AWS CLI

下列 create-hosted-zone 命令會建立私有託管區域:

aws route53 create-hosted-zone --name private.example.com \ --caller-reference 2014-04-01-18:47 \ --hosted-zone-config Comment="command-line version", PrivateZone=true \ --vpc VPCRegion=us-west-2,VPCId=vpc-abcd1234

輸出內容包含託管區域 ID。您可以在下列步驟中使用託管區域 ID。

若要使用 AWS Management Console,請參閱《Amazon Route 53 開發人員指南》中的建立私有託管區域

對於名稱,請使用私有自訂網域名稱的名稱。對於 VPC ID,請使用包含您在先前步驟中使用的 VPC 端點的 VPC。

步驟 5:建立 Route 53 DNS 記錄

建立託管區域後,建立記錄來解析私有自訂網域名稱。使用您在上一個步驟中建立的託管區域 ID。在此範例中,您會建立 A 記錄類型。如果您針對 VPC 端點使用 IPv6,請建立 AAAA 記錄類型。如果您為 VPC 端點使用雙堆疊,請同時建立 AAAA 和 A 記錄類型。

AWS Management Console

若要使用 AWS Management Console,請參閱使用網域名稱將流量路由到 Amazon API Gateway API

使用快速建立並開啟別名。對於端點,請使用 VPC 端點 DNS 名稱。

AWS CLI

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

以下 setup-dns-record.json 顯示如何建立 DNS A 記錄,將私有自訂網域名稱映射至其私有主機名稱。您提供 VPC DNS ID 的 DNSName,以及您在上一個步驟中建立的託管區域 ID。

{ "Changes": [ { "Action": "UPSERT", "ResourceRecordSet": { "Name": "private.example.com", "Type": "A", "AliasTarget": { "DNSName": "vpce-abcd1234.execute-api.us-west-2.vpce.amazonaws.com", "HostedZoneId": "Z2OJLYMUO9EFXC", "EvaluateTargetHealth": false } } } ] }

下列 change-resource-record-sets 命令會為您的私有自訂網域名稱建立 DNS 記錄:

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

hosted-zone-id 取代為您帳戶中所設定之 DNS 記錄的 Route 53 託管區域 ID。change-batch 參數值指向 JSON 檔案。

若要使用 AWS Management Console,請參閱使用網域名稱將流量路由到 Amazon API Gateway API

使用快速建立並開啟別名。對於端點,請使用 VPC 端點 DNS 名稱。

如果您不打算調用自己的私有自訂網域名稱,可在確認私有自訂網域名稱正常運作後刪除這些資源。

步驟 6:調用您的私有自訂網域名稱

您現在可以在自己的 AWS 帳戶 中調用私有自訂網域名稱。在您的 VPC 中,使用以下 curl 命令來存取您的私有自訂網域名稱。

curl https://private.example.com/v1

如需有關調用私有 API 的其他方式的詳細資訊,請參閱 使用自訂網域名稱調用私有 API

步驟 7:清理

若要避免不必要的成本,請刪除 VPC 端點與私有自訂網域名稱之間的關聯,然後刪除私有自訂網域名稱。

AWS Management Console
刪除網域名稱存取關聯
  1. 在以下網址登入 API Gateway 主控台:https://console.aws.amazon.com/apigateway

  2. 在主要導覽窗格中,選擇網域名稱存取關聯

  3. 選取您的網域名稱存取關聯,然後選擇刪除

  4. 確認您的選擇,然後選擇刪除

刪除網域名稱存取關聯後,您可以刪除私有自訂網域名稱。

刪除您的私有自訂網域名稱
  1. 在以下網址登入 API Gateway 主控台:https://console.aws.amazon.com/apigateway

  2. 在主要導覽窗格中,選擇自訂網域名稱

  3. 選擇您的自訂網域名稱。

  4. 選擇 Delete (刪除)。

  5. 確認您的選擇,然後選擇刪除

如有必要,您也可以刪除 VPC 端點。如需詳細資訊,請參閱建立介面端點

AWS CLI
清理方式
  1. 下列 delete-access-association 命令會刪除網域名稱存取關聯:

    aws apigateway delete-domain-name-access-association \ --domain-name-access-association-arn 'arn:aws:apigateway:us-west-2:111122223333:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg' \ --region us-west-2
  2. 下列 delete-domain-name 命令會刪除您的私有自訂網域名稱。此命令也會移除所有基本路徑映射。

    aws apigateway delete-domain-name \ --domain-name test.private.com \ --domain-name-id abcd1234

如有必要,您也可以刪除 VPC 端點。如需詳細資訊,請參閱建立介面端點

刪除網域名稱存取關聯
  1. 在以下網址登入 API Gateway 主控台:https://console.aws.amazon.com/apigateway

  2. 在主要導覽窗格中,選擇網域名稱存取關聯

  3. 選取您的網域名稱存取關聯,然後選擇刪除

  4. 確認您的選擇,然後選擇刪除

刪除網域名稱存取關聯後,您可以刪除私有自訂網域名稱。

刪除您的私有自訂網域名稱
  1. 在以下網址登入 API Gateway 主控台:https://console.aws.amazon.com/apigateway

  2. 在主要導覽窗格中,選擇自訂網域名稱

  3. 選擇您的自訂網域名稱。

  4. 選擇 Delete (刪除)。

  5. 確認您的選擇,然後選擇刪除

如有必要,您也可以刪除 VPC 端點。如需詳細資訊,請參閱建立介面端點

最佳實務

我們建議您在建立私有自訂網域名稱時使用下列最佳實務。

  • 使用基本路徑映射,將多個私有 API 映射至相同的私有自訂網域名稱。

  • 當 VPC 端點不再需要存取私有自訂網域名稱時,請刪除關聯。此外,從私有自訂網域的 execute-api 服務的 policy 中移除 VPC 端點。

  • 為每個 VPC 端點設定至少兩個可用區域。

  • 停用預設端點。建議您停用預設端點,以允許您的 API 取用者只從自訂網域名稱呼叫您的 API。如需更多詳細資訊,請參閱 停用 REST API 的預設端點

  • 建議您在設定私有自訂網域名稱時,佈建 Route 53 私有託管區域和 A 型記錄。如果您不打算調用自己的私有自訂網域名稱,您可以稍後刪除這些資源。

隱私權網站條款Cookie 偏好設定
© 2025, Amazon Web Services, Inc.或其附屬公司。保留所有權利。