本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 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)。
# 私有 API 之自訂網域名稱的 API 提供者和 API 取用者的任務
當您建立私有自訂網域名稱時，您是 *API 提供者*。當您調用私有自訂網域名稱時，您是 *API 取用者*。您可以從自己的 AWS 帳戶 或另一個 使用私有自訂網域名稱 AWS 帳戶。
下一節主要說明：API 提供者和 API 取用者使用私有自訂網域名稱所需的任務。如果您想要在自己的 中叫用私有自訂網域名稱 AWS 帳戶，您同時是 API 供應商和 API 取用者。如果您想要在另一個 中叫用私有自訂網域 AWS 帳戶，根據 API 提供者與 中的 API 取用者之間的信任關係 AWS Organizations， AWS RAM 可能會為您完成一些任務。
## API 提供者的任務
API 提供者會建立私有 API，並將其映射至自訂網域名稱。
API 提供者會管理兩個資源政策，以保護其私有自訂網域名稱。第一個政策用於 `execute-api` 服務，並控制哪些 VPC 端點可以調用您的私有自訂網域名稱。這在私有自訂網域名稱組態中，稱為 `policy`。
第二個政策適用於 Amazon API Gateway Management 服務，並控制其他 中的哪些 VPC 端點 AWS 帳戶 可與私有自訂網域名稱形成網域名稱存取關聯。VPC 端點需要與私有自訂網域名稱建立網域名稱存取關聯，才能調用該名稱。這在私有自訂網域名稱組態中就是 `managementPolicy`。您可以使用 AWS RAM 或 API Gateway 來更新此政策。如果您不打算允許其他 中的 VPC 端點 AWS 帳戶 叫用您的自訂網域名稱，則不會編輯 `managementPolicy`。
如果您是 API 提供者，您必須執行下列操作：
1. 建立私有 API。
1. 更新私有 API `policy` 以授予 VPC 端點存取私有 API 的權限。
1. 建立私有自訂網域名稱。
1. 更新您的私有自訂網域名稱的 `policy`，以授予 VPC 端點存取您的私有自訂網域名稱的權限。
1. 建立基本路徑映射或路由規則，將流量從私有 API 傳送至私有自訂網域名稱。如需詳細資訊，請參閱[在 API Gateway 中透過您的自訂網域名稱將流量傳送至 API](rest-api-routing-mode.md)。
如果您想要允許其他 中的 API 取用者 AWS 帳戶 存取您的私有自訂網域名稱，請執行下列動作：
1. 更新私有自訂網域名稱的 `managementPolicy`，以允許其他帳戶中的 API 取用者為其 VPC 端點與您的私有自訂網域名稱建立關聯。您可以使用下列方式執行這項操作：
**AWS RAM**
使用 時 AWS RAM，如果 API 提供者和 API 取用者位於相同的組織中 AWS Organizations，則會自動接受提供者和取用者之間的資源共用。否則，您應該等到 API 取用者接受資源分享。**我們建議您使用 AWS RAM 來共用私有自訂網域名稱。**
**API Gateway**
透過 API Gateway，僅支援 AWS CLI 。您必須利用修補程式的運作來更新私有自訂網域名稱，並為 `managementPolicy` 提供您自己的政策文件。
1. 更新私有自訂網域名稱的 `policy`，以及對其映射的任何私有 API，以授予對 API 取用者 VPC 端點的存取權。
如需如何將 API 提供給另一個 API 的說明 AWS 帳戶，請參閱 [API 提供者：使用 共用您的私有自訂網域名稱 AWS RAM](apigateway-private-custom-domains-provider-share.md)。
## API 取用者的任務
API 取用者會為其 VPC 端點與網域名稱 ARN 建立關聯，如此才能調用私有自訂網域名稱。API 取用者不需要建立 API Gateway API。
如果您是 API 取用者，請執行下列操作：
1. 在 Amazon VPC 中建立具有私有 DNS 的 VPC 端點。
1. （選用 - AWS RAM 如果使用 ) 在資源共用的 AWS RAM **12 小時內**接受 中的私有自訂網域資源共用。如果您和 API 提供者屬於同一個組織，便會自動接受資源分享。
1. 取得私有自訂網域名稱 ARN。由於私有自訂網域名稱 URL 不是唯一，您可以使用私有自訂網域名稱 ARN 來形成 VPC 端點與私有自訂網域名稱之間的存取關聯。您可以使用 AWS RAM 來擷取私有自訂網域名稱 ARN。
1. 建立私有自訂網域 ARN 與 API Gateway 中的 VPC 端點之間的關聯。這會在 VPC 端點和私有自訂網域名稱之間建立安全連線。流量不會離開 Amazon 網路。
1. 等待 API 提供者授予 VPC 端點對私有自訂網域名稱的存取權，以及映射到私有自訂網域名稱的任何私有 API。如果您同時是 API 提供者和 API 取用者，您可以授予自己的 VPC 端點調用存取權。
1. 建立 Route 53 私有託管區域和 Route 53 記錄，以解析 Route 53 中的私有自訂網域名稱。
如需如何在另一個 API 中使用 API 的說明 AWS 帳戶，請參閱 [API 取用者：將 VPC 端點與和您分享的私有自訂網域名稱建立關聯](apigateway-private-custom-domains-consumer-create.md)。
# 教學：建立和調用私有 API 的自訂網域名稱
在本教學課程中，您會建立一個可以在自己的帳戶中的 VPC 中調用的私有自訂網域名稱。為完成此操作，您既是 API 提供者，也是 API 取用者。您需要現有的私有 API 和 VPC 端點才能完成本教學課程。如果您有用於存取公有自訂網域名稱的 VPC 端點，請勿將其用於本教學課程或建立任何網域名稱存取關聯。
## 步驟 1：建立私有自訂網域名稱
您可以透過指定網域名稱、ACM 憑證和 `execute-api` 服務的政策來建立私有自訂網域名稱，以控制哪些 VPC 端點可以調用該名稱。
------
#### [ AWS 管理主控台 ]
**建立私有自訂網域名稱**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 在主要導覽窗格中，選擇**自訂網域名稱**。
1. 選擇**新增網域名稱**。
1. 在 **Domain name (網域名稱)** 中，輸入網域名稱。
您的 ACM 憑證必須包含此網域名稱，但網域名稱不必是唯一的。
1. 選取**私有**。
1. 針對**路由模式**，選擇**僅 API 映射**。
1. 針對 **ACM 憑證**，選取憑證。
1. 選擇**新增網域名稱**。
API Gateway 會使用 `deny` 所有資源政策佈建網域名稱。這是 `execute-api` 服務的資源政策。您需要更新此資源政策以授予對 VPC 端點的存取權，如此才能調用您的私有自訂網域名稱。
**更新您的資源政策**
1. 選擇**資源政策**標籤，然後選擇**編輯資源政策**。
1. 在程式碼編輯器中輸入下列資源政策。將 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-abcd1234"
}
}
}
]
}
```
1. 選擇**儲存變更**。
------
#### [ AWS CLI ]
當您使用 建立私有自訂網域名稱時 AWS CLI，您會為`execute-api`服務提供資源政策，以授予對 VPC 端點的存取權，以使用 `--policy file://policy.json` 參數叫用私有自訂網域名稱。之後您可以修改此政策。
在此範例中，您將從檔案載入參數，以附加下列資源政策作為 `policy`。複製此檔案並儲存為 `policy.json`。此政策僅允許從 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-abcd1234"
}
}
}
]
}
```
下列 [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-domain-name.html) 命令會建立私有自訂網域名稱：
```
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 file://policy.json
```
輸出如下所示：
```
{
"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",
"routingMode" : "API_MAPPING_ONLY",
"policy": "..."
}
```
------
## 步驟 2：建立基本路徑映射，將私有 API 映射至私有自訂網域名稱
建立私有自訂網域名稱後，您可以將私有 API 映射至該名稱。基本路徑映射可以透過私有自訂網域名稱與相關聯基本路徑的組合來存取 API。建議您將單一私有自訂網域用作多個私有 API 的主機名稱。
所有 API 提供者都需要建立基本路徑映射，即使您不打算調用自己的 API。您也需要授予對 VPC 端點的存取權，如此才能調用映射至私有自訂網域名稱的任何私有 API。
------
#### [ AWS 管理主控台 ]
**建立基本路徑映射**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 在主要導覽窗格中，選擇**自訂網域名稱**。
1. 選擇私有自訂網域名稱。
1. 在 **API 映射**標籤上，選擇**設定映射**。
1. 選擇 **Add new mapping (新增映射)**。
1. 輸入 **API**、**Stage** (階段)，以及選擇性地輸入 **Path** (路徑)。
1. 選擇**儲存**。
------
#### [ AWS CLI ]
下列 [create-base-path-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-base-path-mapping.html) 命令會在私有 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"
}
```
------
如要以更有彈性的方式將流量路由至 API，您可以將路由模式變更為 `ROUTING_RULE_ONLY` 或 `ROUTING_RULE_THEN_API_MAPPING`，並建立路由規則。如需詳細資訊，請參閱[在 API Gateway 中透過您的自訂網域名稱將流量傳送至 API](rest-api-routing-mode.md)。
**注意**
如果您希望其他人 AWS 帳戶 叫用您的私有自訂網域名稱，在完成本教學課程後，請遵循中的步驟[API 提供者：使用 共用您的私有自訂網域名稱 AWS RAM](apigateway-private-custom-domains-provider-share.md)。
## 步驟 3：在您的自訂網域名稱和 VPC 端點之間建立網域名稱存取關聯
接著，您可以在私有自訂網域名稱和 VPC 端點之間建立網域名稱存取關聯。您的 VPC 端點會利用網域名稱存取關聯，在與公有網際網路隔離時調用您的私有自訂網域名稱。
------
#### [ AWS 管理主控台 ]
**建立網域名稱存取關聯**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 在主要導覽窗格中，選擇**自訂網域名稱**。
1. 選擇私有自訂網域名稱。
1. 在**資源共用**標籤中，針對**網域名稱存取關聯**選擇**建立網域名稱存取關聯**。
1. 針對**網域名稱 ARN**，選取您的網域名稱。
1. 針對 **VPC 端點 ID**，選取您在步驟 1 中提供存取權的 VPC 端點 ID。
1. 選擇**網域名稱存取關聯**。
您也可以使用主控台的**網域名稱存取關聯**頁面建立網域名稱存取關聯。
------
#### [ 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"
}
```
------
建立您的網域名稱存取關聯後，大約需要 15 分鐘才能準備就緒。您在等待時，可以繼續執行下列步驟。
## 步驟 4：建立 Route 53 託管區域
在您更新資源政策，並為私有自訂網域名稱與 VPC 端點建立關聯後，可以在 Route 53 中建立私有託管區域以解析自訂網域名稱。託管區域是一種容器，其中包含的資訊說明您可以如何在一或多個 VPC 中路由某個網域的流量，而不用將資源公開至網際網路。如需詳細資訊，請參閱[使用私有託管區域](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html)。
------
#### [ AWS 管理主控台 ]
若要使用 AWS 管理主控台，請參閱《*Amazon Route 53 開發人員指南*》中的[建立私有託管區域](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zone-private-creating.html)。
對於**名稱**，請使用私有自訂網域名稱的名稱。對於 **VPC ID**，請使用包含您在先前步驟中使用的 VPC 端點的 VPC。
------
#### [ AWS CLI ]
下列 [create-hosted-zone](https://docs.aws.amazon.com/cli/latest/reference/route53/create-hosted-zone.html) 命令會建立私有託管區域：
```
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。
------
## 步驟 5：建立 Route 53 DNS 記錄
建立託管區域後，建立記錄來解析私有自訂網域名稱。使用您在上一個步驟中建立的託管區域 ID。在此範例中，您會建立 A 記錄類型。如果您針對 VPC 端點使用 IPv6，請建立 AAAA 記錄類型。如果您為 VPC 端點使用雙堆疊，請同時建立 AAAA 和 A 記錄類型。
------
#### [ AWS 管理主控台 ]
若要使用 AWS 管理主控台，請參閱[使用您的網域名稱將流量路由到 Amazon API Gateway API](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)。
使用**快速建立**並開啟**別名**。對於端點，請使用 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](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html) 命令會為您的私有自訂網域名稱建立 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 檔案。
------
如果您不打算調用自己的私有自訂網域名稱，可在確認私有自訂網域名稱正常運作後刪除這些資源。
## 步驟 6：調用您的私有自訂網域名稱
您現在可以在自己的 AWS 帳戶中調用私有自訂網域名稱。在您的 VPC 中，使用以下 curl 命令來存取您的私有自訂網域名稱。
```
curl https://private.example.com/v1
```
如需有關調用私有 API 的其他方式的詳細資訊，請參閱 [使用自訂網域名稱調用私有 API](apigateway-private-api-test-invoke-url.md#apigateway-private-custom-domains-provider-invoke)。
## 步驟 7：清除
若要避免不必要的成本，請刪除 VPC 端點與私有自訂網域名稱之間的關聯，然後刪除私有自訂網域名稱。
------
#### [ AWS 管理主控台 ]
**刪除網域名稱存取關聯**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 在主要導覽窗格中，選擇**網域名稱存取關聯**。
1. 選取您的網域名稱存取關聯，然後選擇**刪除**。
1. 確認您的選擇，然後選擇**刪除**。
刪除網域名稱存取關聯後，您可以刪除私有自訂網域名稱。
**刪除您的私有自訂網域名稱**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 在主要導覽窗格中，選擇**自訂網域名稱**。
1. 選擇您的自訂網域名稱。
1. 選擇 **刪除**。
1. 確認您的選擇，然後選擇**刪除**。
如有必要，您也可以刪除 VPC 端點。如需詳細資訊，請參閱[建立介面端點](https://docs.aws.amazon.com/vpc/latest/privatelink/delete-interface-endpoint.html)。
------
#### [ 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
```
1. 下列 `delete-domain-name` 命令會刪除您的私有自訂網域名稱。此命令也會移除所有基本路徑映射。
```
aws apigateway delete-domain-name \
--domain-name test.private.com \
--domain-name-id abcd1234
```
如有必要，您也可以刪除 VPC 端點。如需詳細資訊，請參閱[建立介面端點](https://docs.aws.amazon.com/vpc/latest/privatelink/delete-interface-endpoint.html)。
------
## 最佳實務
我們建議您在建立私有自訂網域名稱時使用下列最佳實務：
+ 使用基本路徑映射或路由規則，將流量從一個私有自訂網域名稱傳送至多個私有 API。
+ 當 VPC 端點不再需要存取私有自訂網域名稱時，請刪除關聯。此外，從私有自訂網域的 `execute-api` 服務的 `policy` 中移除 VPC 端點。
+ 為每個 VPC 端點設定至少兩個可用區域。
+ 停用預設端點。建議您停用預設端點，以允許您的 API 取用者只從自訂網域名稱呼叫您的 API。如需詳細資訊，請參閱[停用 REST API 的預設端點](rest-api-disable-default-endpoint.md)。
+ 建議您在設定私有自訂網域名稱時，佈建 Route 53 私有託管區域和 A 型記錄。如果您不打算調用自己的私有自訂網域名稱，您可以稍後刪除這些資源。
# 使用跨帳戶私有自訂網域名稱
本節說明如何使用跨帳戶私有自訂網域名稱。您可以將私有自訂網域名稱提供給另一個 AWS 帳戶 ，並使用另一個 AWS 帳戶 來叫用私有自訂網域名稱。
您可以使用 AWS 帳戶 AWS Resource Access Manager 或 API Gateway 將您的私有自訂網域名稱分享給另一個 。 AWS Resource Access Manager (AWS RAM) 可協助您在組織或組織單位 (OUs) 之間 AWS 帳戶 和內部安全地共用資源。如需詳細資訊，請參閱[什麼是 AWS Resource Access Manager](https://docs.aws.amazon.com/ram/latest/userguide/what-is.html) 。
如需如何使用 與另一個 共用私有自訂網域名稱的說明 AWS 帳戶 AWS RAM，請參閱 [API 提供者：使用 共用您的私有自訂網域名稱 AWS RAM](apigateway-private-custom-domains-provider-share.md)。
如需如何使用 AWS 帳戶 API Gateway 與另一個 共用私有自訂網域名稱的說明，請參閱 [API 提供者：使用 API Gateway 共用您的私有自訂網域名稱 AWS CLI](apigateway-private-custom-domains-provider-share-cli.md)。
如需如何在另一個 中使用私有自訂網域名稱的指示 AWS 帳戶，請參閱 [API 取用者：將 VPC 端點與和您分享的私有自訂網域名稱建立關聯](apigateway-private-custom-domains-consumer-create.md)。
## 使用跨帳戶私有自訂網域名稱的最佳實務
我們建議使用以下跨帳戶私有自訂網域名稱的最佳實務：
+ 使用 AWS RAM 來共用私有自訂網域名稱。使用 時 AWS RAM，您可以降低營運開銷，而且不需要`managementPolicy`為 Amazon API Gateway Management 服務建立 。
+ 當您列出私有自訂網域名稱或網域名稱存取關聯時，請使用 `resource-owner` 參數。使用 `resource-owner` 參數僅列出您或其他 AWS 帳戶擁有的資源。
下列範例顯示如何取得您擁有的所有網域名稱存取關聯：
```
aws apigateway get-domain-name-access-associations --resource-owner SELF
```
使用 `--resource-owner OTHER_ACCOUNTS` 列出其他帳戶已與您的私有自訂網域名稱形成的所有網域名稱存取關聯。
# API 提供者：使用 共用您的私有自訂網域名稱 AWS RAM
您可以在其他 AWS 帳戶 存取中為 API 取用者提供私有自訂網域名稱。在本節中，您將了解如何使用 共用私有自訂網域名稱， AWS RAM 以及如何控制對私有自訂網域名稱的存取。
## 共用私有自訂網域名稱的考量事項
下列考量可能會影響您使用 AWS RAM提供私有自訂網域名稱之存取權的方式。若要了解如何共用私有自訂網域名稱而不使用 AWS RAM，請參閱 [API 提供者：使用 API Gateway 共用您的私有自訂網域名稱 AWS CLI](apigateway-private-custom-domains-provider-share-cli.md)。
+ 私有自訂網域名稱會在 AWS 區域 層級共用。私有自訂網域名稱和 VPC 端點必須位於相同的 AWS 區域中。
+ 您可以與多個主體使用一個資源分享，並在建立資源分享後，為其新增更多主體。建議您盡可能重複使用資源分享。
+ 您始終需要授予 API 取用者的 VPC 端點存取權，才能調用您的私有自訂網域名稱，以及任何與其映射的私有 API。
+ 如果 API 取用者和 API 提供者位於使用 的相同組織中 AWS Organizations，則會自動接受資源共用。您仍然需要使用 AWS RAM建立資源分享。
+ 如果 API 取用者和 API 提供者位於使用 的相同組織中， AWS Organizations 且組織內的資源共用已啟用，則與您共用的組織中的任何主體都會自動獲得資源共用的存取權。不需要邀請函的，可以略過資源分享。
+ 如果 API 取用者在 **12 小時內**不接受資源分享，API 提供者必須再次分享資源。
+ 在您建立資源共享後， 會 AWS RAM 更新私有自訂網域名稱`managementPolicy`的 Amazon API Gateway Management 服務的 ，以防止在沒有明確存取的情況下`allow`存取主體。如需詳細資訊，請參閱《IAM 使用者指南》中的[判斷帳戶中的請求獲得允許或遭到拒絕。](https://docs.aws.amazon.com//IAM/latest/UserGuide/reference_policies_evaluation-logic.html#policy-eval-denyallow)
更新的 `managementPolicy` 如下所示：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "abcd1234-1234-abcd-abcd-1234abcdefg",
"Statement": [
{
"Sid": "APIGatewayPrivateDomainNameManagementPolicyDefaultPermission-org",
"Effect": "Allow",
"Principal": "*",
"Action": "apigateway:CreateAccessAssociation",
"Resource": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234",
"Condition": {
"StringEquals": {
"aws:PrincipalOrgID": "o-1234abcd"
},
"StringNotEquals": {
"aws:PrincipalAccount": "111122223333"
}
}
}
]
}
```
------
AWS RAM 已透過新增下列項目，防止主體沒有明確`allow`存取來建立與私有自訂網域名稱的存取關聯：
```
"StringNotEquals": {
"aws:PrincipalAccount": "111122223333"
}
```
您仍然可以在建立私有自訂網域名稱 AWS 帳戶 的 中使用主體來建立網域名稱存取關聯。
## 允許其他帳戶與您的私有自訂網域名稱建立網域名稱存取關聯
首先，您將存取權授予另一個 ， AWS 帳戶 以建立與私有自訂網域名稱的網域名稱存取關聯。
------
#### [ AWS 管理主控台 ]
若要使用 AWS 管理主控台，請參閱*AWS RAM 《 使用者指南*》中的[在 中建立資源共享 AWS RAM](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing-create.html)。
針對**選取資源類型**，選擇 **API Gateway 私有自訂網域**。
------
#### [ AWS CLI ]
下列 [create-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) 會為您的私有自訂網域名稱建立資源分享。資源和委託人可能需要幾分鐘的時間才能完成關聯。對於主體，請提供帳戶 ID 或 Organizations ID，例如 `arn:aws:organizations::123456789012:organization/o-1234abcd`。您可以為資源分享提供多個主體。
```
aws ram create-resource-share \
--region us-west-2 \
--name privateCustomDomain-resource-share \
--permission-arns arn:aws:ram::aws:permission/APIGatewayPrivateDomainNameManagementPolicyDefaultPermission \
--resource-arns arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234 \
--principals 222222222222
```
------
在您提供對另一個 的存取權之後 AWS 帳戶，該帳戶中的 API 取用者必須在其 VPC 端點與您的私有自訂網域名稱之間建立網域名稱存取關聯。您無法為其建立網域名稱存取關聯。如需詳細資訊，請參閱[為您的 VPC 端點與分享的私有自訂網域名稱建立關聯](apigateway-private-custom-domains-consumer-create.md#apigateway-private-custom-domains-consumer-associate)。
## 允許其他帳戶調用您的私有自訂網域名稱
接下來，您會授予 API 取用者之 VPC 端點的存取權，以調用私有自訂網域名稱和任何與其映射的私有 API。
------
#### [ AWS 管理主控台 ]
**允許其他帳戶中的 VPC 端點調用您的私有自訂網域名稱**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 在主要導覽窗格中，選擇**自訂網域名稱**。
1. 選擇您與其他 共用的私有自訂網域名稱 AWS 帳戶。
1. 在**資源政策**標籤上，選擇**編輯資源政策**。
1. 將 API 取用者的 VPC 端點 ID 新增至您的資源政策。
您可以在私有自訂網域名稱的**網域詳細資訊**頁面上的**資源分享**標籤的**網域名稱存取關聯**區段中，找到 API 取用者的 VPC 端點 ID。
1. 選擇**儲存變更**。
------
#### [ AWS CLI ]
下列的 `execute-api` 服務 `policy`，允許從 VPC 端點 `vpce-abcd1234efg` 和 `vpce-xyz000abc` 二者傳入私有自訂網域名稱的流量。
****
```
{
"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-abcd1234",
"vpce-xyzz0000"
]
}
}
}
]
}
```
下列 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令使用修補程式作業來更新私有自訂網域名稱的 `policy`：
```
aws apigateway update-domain-name
--domain-name private.example.com \
--domain-name-id abcd1234 \
--patch-operations op=replace,path=/policy,value='"{\"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\":[\"vpce-abcd1234efg\", \"vpce-xyz000abc\"]}}}]}"
```
------
# API 提供者：使用 停止共用私有自訂網域名稱 AWS RAM
若要停止分享您的私有自訂網域名稱，請先取消資源分享的關聯，以停止 API 取用者建立更多網域名稱存取關聯。然後，您拒絕網域名稱存取關聯，並從 `execute-api` 服務的 `policy` 中移除 API 取用者的 VPC 端點。API 取用者接著可以刪除其網域名稱存取關聯。
## 停止分享您的私有自訂網域名稱
首先，您使用 停止資源共享 AWS RAM。
------
#### [ AWS 管理主控台 ]
若要使用 AWS 管理主控台，請參閱[在 中更新資源共用 AWS RAM](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing-update.html)。
------
#### [ AWS CLI ]
下列 [disassociate-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html) 會取消您的私有自訂網域名稱的資源分享的關聯。
```
aws ram disassociate-resource-share \
--region us-west-2 \
--resource-arns arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234 \
--principals 222222222222
```
------
## 拒絕網域名稱存取關聯
停止使用 共用資源後 AWS RAM，您會拒絕另一個帳戶中的 VPC 端點與私有自訂網域名稱之間的網域名稱存取關聯。
**注意**
您無法拒絕自己帳戶中的網域名稱存取關聯。若要停止資源分享，請刪除網域名稱存取關聯。如需詳細資訊，請參閱[刪除網域名稱存取關聯](apigateway-private-custom-domains-tutorial.md#apigateway-private-custom-domains-cleanup)。
當您拒絕網域名稱與 VPC 端點的存取關聯時，如果 API 取用者嘗試呼叫您的私有自訂網域名稱，API Gateway 會拒絕呼叫，並傳回 `403` 狀態碼。
------
#### [ AWS 管理主控台 ]
**拒絕網域名稱存取關聯**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 在主要導覽窗格中，選擇**自訂網域名稱**。
1. 選擇您與其他 共用的私有自訂網域名稱 AWS 帳戶。
1. 在**資源分享**上，選擇您要拒絕的網域名稱存取關聯。
1. 選擇**拒絕關聯**。
1. 確認您的選擇，然後選擇**拒絕**。
------
#### [ AWS CLI ]
下列 `reject-domain-name-access-association` 命令會拒絕 VPC 端點與私有自訂網域名稱之間的網域名稱存取關聯：
```
aws apigateway reject-domain-name-access-association \
--domain-name-access-association-arn arn:aws:apigateway:us-west-2:444455556666:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg \
--domain-name-arn arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234
```
------
## 拒絕 API 提供者存取，以調用您的私有自訂網域名稱
拒絕網域名稱存取關聯後，您可以從 `execute-api` 服務的 `policy` 中移除 API 取用者 VPC 端點。
------
#### [ AWS 管理主控台 ]
**從資源政策中移除 API 取用者的 VPC 端點**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 在主要導覽窗格中，選擇**自訂網域名稱**。
1. 選擇您與其他 共用的私有自訂網域名稱 AWS 帳戶。
1. 在**資源政策**標籤上，選擇**編輯**。
1. 從政策中移除 VPC 端點。
1. 選擇**儲存變更**。
------
#### [ AWS CLI ]
下列 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令使用修補程式作業來更新私有自訂網域名稱之 `execute-api` 服務的 `policy`。此新的 `policy` 會移除 [允許其他帳戶調用您的私有自訂網域名稱](apigateway-private-custom-domains-provider-share.md#apigateway-private-custom-domains-provider-policy-update) 中新增的其他 VPC 端點 ID：
```
aws apigateway update-domain-name
--domain-name private.example.com \
--domain-name-id abcd1234 \
--patch-operations op=replace,path=/policy,value='"{\"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\"}}}]}"
```
------
API 取用者接著應該刪除網域名稱存取關聯。您無法為他們刪除存取關聯。如需詳細資訊，請參閱[API 取用者：刪除與私有自訂網域名稱的網域名稱存取關聯](apigateway-private-custom-domains-consumer-delete-domain-name-access-association.md)。
# API 提供者：使用 API Gateway 共用您的私有自訂網域名稱 AWS CLI
您可以使用 API Gateway 共用私有自訂網域名稱 AWS CLI，但我們建議您使用 AWS RAM 來降低營運開銷。如需如何使用 AWS RAM 來共用私有自訂網域名稱的指示，請參閱 [API 提供者：使用 共用您的私有自訂網域名稱 AWS RAM](apigateway-private-custom-domains-provider-share.md)。
若要使用 API Gateway 共用私有自訂網域名稱 AWS CLI，您可以授予其他 AWS 帳戶 存取權來建立網域名稱存取關聯，並叫用私有自訂網域名稱。您可以藉由更新 API Gateway Management 服務的 `managementPolicy` 和私有自訂網域名稱的 `execute-api` 服務的 `policy` 來執行此操作。您也需要在資源政策中授予 API 取用者 VPC 端點的存取權，以用於映射到私有自訂網域名稱的任何私有 API。
API 取用者仍需在其 VPC 端點和您的私有自訂網域名稱之間，在其自己的帳戶中建立網域名稱存取關聯。您無法為他們執行此操作。
## 授予私有自訂網域名稱的存取權
**授予私有自訂網域名稱的存取權**
1. 若要更新 API Gateway Management 服務的 `managementPolicy`，您可以建立包含修補程式作業的 JSON 檔案來更新政策。以下內容會將目前的 `patch-managementPolicy.json`取代`managementPolicy`為範例政策，授予 AWS 帳戶 111122223333 和 444455556666 的存取權，以建立與私有自訂網域名稱 的網域名稱存取關聯`private.example.com`。
```
[{
"op": "replace",
"path": "/managementPolicy",
"value": "{\"Version\":\"2012-10-17\", \"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":[\"arn:aws:iam::111122223333:root\", \"arn:aws:iam::444455556666:root\"]},\"Action\":\"apigateway:CreateAccessAssociation\",\"Resource\":\"arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234\"}]}"
}]
```
下列 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令會使用 `patch-managementPolicy.json` 更新 `managementPolicy`。
```
aws apigateway update-domain-name \
--domain-name private.example.com \
--domain-name-id abcd1234 \
--patch-operations file://patch-managementPolicy.json
```
授予存取權後，您需要通知 API 取用者，他們可以形成網域名稱存取關聯。如果您使用 AWS RAM， AWS RAM 會為您執行此步驟。
1. 若要更新 `execute-api` 服務的 `policy`，您可以建立包含修補程式作業的 JSON 檔案來更新政策。以下 `patch-policy.json` 會將目前的 `policy` 取代為範例政策，而此政策會授予兩個 VPC 端點來調用私有自訂網域名稱 `private.example.com`。
```
[{
"op": "replace",
"path": "/policy",
"value": "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\",\"Principal\": \"*\",\"Action\": \"execute-api:Invoke\",\"Resource\": \"arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.example.com+abcd1234\"},{\"Effect\": \"Deny\",\"Principal\": \"*\",\"Action\": \"execute-api:Invoke\",\"Resource\": \"arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.example.com+abcd1234\",\"Condition\": {\"StringNotEquals\": {\"aws:SourceVpce\": [\"vpce-abcd1234\",\"vpce-xyzz0000\"]}}}]}"
}]
```
使用下列 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令，並使用 `patch-policy.json` 來更新 `policy`。
```
aws apigateway update-domain-name \
--domain-name private.example.com \
--domain-name-id abcd1234 \
--patch-operations file://patch-policy.json
```
## 拒絕對您的私有自訂網域名稱的存取
若要停止分享私有自訂網域名稱，您需要拒絕私有自訂網域名稱與 API 取用者之 VPC 端點之間的網域名稱存取關聯。
**拒絕對私有自訂網域名稱的存取**
1. 下列 `reject-domain-name-access-association` 命令會拒絕網域名稱存取關聯。
```
aws apigateway reject-domain-name-access-association \
--domain-name-access-association-arn arn:aws:apigateway:us-west-2:444455556666:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234 \
--domain-name-arn arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234
```
1. 修改 `patch-managementPolicy.json` 即可移除 API 提供者帳戶的存取權，以與您的私有自訂網域名稱建立網域名稱存取關聯。下列 `patch-managementPolicy.json` 會從 `managementPolicy` 移除一個帳戶：
```
[{
"op": "replace",
"path": "/managementPolicy",
"value": "{\"Version\":\"2012-10-17\", \"Statement\":[{\"Effect\":\"Allow\",\"Principal\":\"*\",\"Action\":\"apigateway:CreateAccessAssociation\",\"Resource\":\"arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234\"}]}"
}]
```
下列 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令使用 `patch-managementPolicy.json` 更新 `managementPolicy`。
```
aws apigateway update-domain-name \
--domain-name private.example.com \
--domain-name-id abcd1234 \
--patch-operations file://patch-managementPolicy.json
```
1. 修改 `patch-policy.json` 以移除用於讓 API 提供者 VPC 端點調用您的私有自訂網域名稱的存取權。以下 `patch-policy.json` 會從 `policy` 移除 VPC 端點 ID：
```
[{
"op": "replace",
"path": "/policy",
"value": "{\"Version\":\"2012-10-17\", \"Statement\":[{\"Effect\":\"Allow\",\"Principal\":\"*\",\"Action\":\"execute-api:Invoke\",\"Resource\":\"arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.example.com+abcd1234\"},{\"Effect\":\"Deny\",\"Principal\":\"*\",\"Action\":\"execute-api:Invoke\",\"Resource\":\"arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.example.com+abcd1234\",\"Condition\":{\"StringNotEquals\":{\"aws:SourceVpce\":\"vpce-abcd1234\"}}}]}"
}]
```
下列 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 命令會使用 `patch-policy.json` 更新 `policy`。
```
aws apigateway update-domain-name \
--domain-name private.example.com \
--domain-name-id abcd1234 \
--patch-operations file://patch-policy.json
```
## 此程序中使用的範例政策
下一節說明先前程序中使用的範例政策。
下列範例政策適用於 Amazon API Gateway Management 服務的 `managementPolicy`。此政策授予 AWS 帳戶 111122223333 和 444455556666 存取權，以建立與私有自訂網域名稱 的網域名稱存取關聯`private.example.com`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"111122223333",
"444455556666"
]
},
"Action": "apigateway:CreateAccessAssociation",
"Resource": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+a1b2c3"
}
]
}
```
------
下列範例政策是 `execute-api` 服務的 `policy` 的政策。此政策會授予 VPC 端點 `vpce-abcd1234` 和 `vpce-xyzz0000` 存取權，用以調用私有自訂網域名稱。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.example.com+abcd1234"
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.example.com+abcd1234",
"Condition": {
"StringNotEquals": {
"aws:SourceVpce": [
"vpce-abcd1234",
"vpce-xyzz0000"
]
}
}
}
]
}
```
------
# API 取用者：將 VPC 端點與和您分享的私有自訂網域名稱建立關聯
下列程序顯示如何在另一個 中使用私有網域名稱 AWS 帳戶。視您與 API 提供者的信任關係而定， AWS RAM 可能會為您完成一些任務。
當您位於 AWS 帳戶 與私有自訂網域名稱不同的 時，您只能將 VPC 端點與私有自訂網域名稱建立關聯並叫用它。您無法檢視私有自訂網域名稱的 `policy` 或其他任何參數。
## 先決條件
在另一個 中使用私有自訂網域名稱時，需要下列先決條件 AWS 帳戶：
+ `execute-api` 服務的 VPC 和 VPC 端點。您的 VPC 必須將 `enableDnsHostnames` 和 `enableDnsSupport` 設為 `true`。
+ 建議您為每個 VPC 端點設定至少兩個可用區域。
## (選用) 接受私有自訂網域資源分享
如果您的 API 提供者 AWS RAM 用來建立資源共享，您有 **12 小時**的時間可以接受它。如果您使用 AWS Organizations 與 API 提供者位於相同的組織中，則會自動接受共用。如果您所在的組織已啟用自動分享資源，則會自動與您分享資源。
------
#### [ AWS 管理主控台 ]
若要使用 AWS 管理主控台，請參閱*AWS RAM 《 使用者指南*》中的[接受和拒絕資源共用邀請](https://docs.aws.amazon.com/ram/latest/userguide/working-with-shared-invitations.html)。
------
#### [ AWS CLI ]
若要尋找與您分享的所有資源，請使用下列 [get-resource-share-invitations](https://docs.aws.amazon.com/cli/latest/reference/ram/get-resource-share-invitations.html) 命令：
```
aws ram get-resource-share-invitations \
--region us-west-2
```
使用產生的資源分享 ARN，接受資源分享邀請。下列 [accept-resource-share-invitation](https://docs.aws.amazon.com/cli/latest/reference/ram/accept-resource-share-invitation.html) 命令接受資源分享。
```
aws ram accept-resource-share-invitation \
--resource-share-invitation-arn arn:aws:ram:us-west-2:123456789012:resource-share-invitation/1e3477be-4a95-46b4-bbe0-c4001EXAMPLE \
--region us-west-2
```
------
## 為您的 VPC 端點與分享的私有自訂網域名稱建立關聯
由於私有自訂網域名稱不是唯一的，因此您可以為 VPC 端點與唯一的自訂網域名稱 ARN 建立關聯。建立網域名稱存取關聯後，VPC 端點最多可能需要 15 分鐘才能成功調用您的私有自訂網域名稱。如果您有用於存取公有自訂網域名稱的 VPC 端點，請勿使用該端點建立任何網域名稱存取關聯。
------
#### [ AWS 管理主控台 ]
**為您的 VPC 端點與分享的私有自訂網域名稱建立關聯**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 在主要導覽窗格中，選擇**網域名稱存取關聯**。
1. 選擇**建立網域名稱存取關聯**。
1. 針對**網域名稱 ARN**，選取 API 提供者與您共用的網域名稱 ARN。
網域名稱 ARN 可能不會出現在下拉式清單中。您可以使用 AWS RAM 主控台來檢視與您共用的網域名稱，然後複製網域名稱 ARN 並將其輸入此欄位。
1. 針對 **VPC 端點 ID**，選取您要與之形成網域名稱存取關聯的 VPC 端點 ID。
1. 選擇**建立網域名稱存取關聯**。
------
#### [ AWS CLI ]
由於私有自訂網域名稱不是唯一的，因此您可以為 VPC 端點與唯一的自訂網域名稱 ARN 建立關聯。若要尋找網域名稱 ARN，請使用下列其中一個命令。
1.
**AWS RAM**
下列 [list-resources](https://docs.aws.amazon.com/cli/latest/reference/ram/list-resources.html) 命令會列出與您分享的資源。API 提供者必須使用 AWS RAM 與您共用其私有自訂網域，才能使用此命令。
```
aws ram list-resources \
--resource-owner OTHER-ACCOUNTS \
--region us-west-2
--resource-type apigateway:Domainnames
```
**API Gateway**
下列`get-domain-names`命令會列出其他 擁有的所有私有自訂網域名稱 AWS 帳戶 ，您可以與其建立網域名稱存取關聯。
```
aws apigateway get-domain-names \
--resource-owner OTHER_ACCOUNTS \
--region us-west-2
```
1. 擷取 ARN 之後，使用 API Gateway 在您的 VPC 端點與共用私有自訂網域名稱之間建立網域名稱存取關聯。使用下列 `create-domain-name-access-association` 命令：
```
aws apigateway create-domain-name-access-association \
--access-association-source-type VPCE \
--access-association-source 'vpce-1a2b3c4d5e6f1a2b3' \
--domain-name-arn arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234"
```
輸出將如下所示：
```
{
"domainNameAccessAssociationARN": "arn:aws:apigateway:us-west-2:444455556666:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg",
"accessAssociationSource": "vpce-1a2b3c4d5e6f1a2b3",
"accessAssociationSourceType": "VPCE",
"domainNameARN" : "arn:aws:apigateway:us-west-1:111122223333:/domainnames/private.example.com+a1b2c3"
}
```
------
為您的 VPC 端點與私有自訂網域名稱建立關聯後，請確認您的 API 提供者已更新其私有自訂網域名稱的政策，以允許您的 VPC 端點調用其網域名稱。如需詳細資訊，請參閱[允許其他帳戶調用您的私有自訂網域名稱](apigateway-private-custom-domains-provider-share.md#apigateway-private-custom-domains-provider-policy-update)。
## 建立 Route 53 託管區域
若要解析私有自訂網域名稱，您需要建立 Route 53 私有託管區域。託管區域是一種容器，其中包含的資訊說明您可以如何在一或多個 VPC 中路由某個網域的流量，而不用將資源公開至網際網路。如需詳細資訊，請參閱[使用私有託管區域](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html)。
------
#### [ AWS 管理主控台 ]
若要使用 AWS 管理主控台，請參閱《*Amazon Route 53 開發人員指南*》中的[建立私有託管區域](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zone-private-creating.html)。
對於**名稱**，請使用私有自訂網域名稱的名稱。對於 **VPC ID**，請使用包含您用於網域名稱存取關聯的 VPC 端點的 VPC。
------
#### [ AWS CLI ]
下列 [create-hosted-zone](https://docs.aws.amazon.com/cli/latest/reference/route53/create-hosted-zone.html) 命令會建立私有託管區域：
```
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。
------
## 建立 Route 53 DNS 記錄
建立託管區域後，您可以建立記錄來解析私有自訂網域。在此範例中，您會建立 A 記錄類型。如果您針對 VPC 端點使用 IPv6，請建立 AAAA 記錄類型。如果您為 VPC 端點使用雙堆疊，請同時建立 AAAA 和 A 記錄類型。
------
#### [ AWS 管理主控台 ]
若要使用 AWS 管理主控台，請參閱[使用您的網域名稱將流量路由到 Amazon API Gateway API](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)。
使用**快速建立**並開啟**別名**。對於端點，請使用 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](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html) 命令會為私有自訂網域名稱建立 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 檔案。
------
## API 取用者的後續步驟
您現在可以在自己的 AWS 帳戶中調用私有 API。在您的 VPC 中，您可以使用下列 curl 命令來存取您的私有自訂網域名稱。
```
curl https://private.example.com/v1
```
如需有關調用私有 API 的其他方式的詳細資訊，請參閱 [使用自訂網域名稱調用私有 API](apigateway-private-api-test-invoke-url.md#apigateway-private-custom-domains-provider-invoke)。
# API 取用者：刪除與私有自訂網域名稱的網域名稱存取關聯
如果您是 API 取用者，您可以隨時刪除存取關聯資源。API 提供者無法刪除您的網域名稱存取關聯。
當您不再使用網域名稱存取關聯時，建議您一律刪除該網域名稱存取關聯。
------
#### [ AWS 管理主控台 ]
**刪除網域名稱存取關聯**
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 在主要導覽窗格中，選擇**網域名稱存取關聯**。
1. 選取您的網域名稱存取關聯，然後選擇**刪除**。
1. 確認您的選擇，然後選擇**刪除**。
------
#### [ AWS CLI ]
下列 `delete-access-association` 命令會刪除存取關聯：
```
aws apigateway delete-domain-name-access-association \
--domain-name-access-association-arn 'arn:aws:apigateway:us-west-2:444455556666:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg'
```
------
# 使用 建立私有 APIs的自訂網域名稱 CloudFormation
下列範例 CloudFormation 範本會建立私有 API 和私有自訂網域名稱、將私有 API 對應至自訂網域名稱，然後建立網域名稱存取關聯。您需要提供自己的 VPC 端點、網域名稱和憑證 ARN。
下列考量事項可能會影響您使用 CloudFormation 來建立私有自訂網域名稱：
+ 您無法使用 拒絕網域名稱存取關聯 CloudFormation。若要拒絕網域名稱存取關聯，請使用 AWS CLI。
+ 使用 `AWS::ApiGateway::DomainNameV2` CloudFormation 屬性建立私有自訂網域名稱。
+ 使用 `AWS::ApiGateway:BasePathMappingV2` CloudFormation 屬性建立基本路徑映射。
```
AWSTemplateFormatVersion: 2010-09-09
Parameters:
EndpointID:
Type: String
Default: vpce-abcd1234567efg
Description: A VPC endpoint with enableDnsHostnames and enableDnsSupport set to true.
DomainName:
Type: String
Default: private.example.com
Description: A domain name that you own.
CertificateArn:
Type: String
Default: arn:aws:acm:us-west-2:123456789:certificate/abcd-000-1234-0000-000000abcd
Description: An ACM certificate that covers the domain name.
Resources:
PrivateApi:
Type: 'AWS::ApiGateway::RestApi'
Properties:
EndpointConfiguration:
Types:
- PRIVATE
VpcEndpointIds:
- !Ref EndpointID
Name: private-api
Policy:
Statement:
- Action: 'execute-api:Invoke'
Effect: Allow
Principal: '*'
Resource: 'execute-api:/*'
- Action: 'execute-api:Invoke'
Condition:
StringNotEquals:
'aws:SourceVpce': !Ref EndpointID
Effect: Deny
Principal: '*'
Resource: 'execute-api:/*'
Version: 2012-10-17
PrivateApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
Properties:
RestApiId: !Ref PrivateApi
Description: Private API deployment
DependsOn:
- PrivateApiMethod
PrivateApiStage:
Type: 'AWS::ApiGateway::Stage'
Properties:
RestApiId: !Ref PrivateApi
DeploymentId: !Ref PrivateApiDeployment
StageName: prod
PrivateApiMethod:
Type: 'AWS::ApiGateway::Method'
Properties:
HttpMethod: ANY
ResourceId: !GetAtt PrivateApi.RootResourceId
RestApiId: !Ref PrivateApi
AuthorizationType: NONE
Integration:
Type: MOCK
RequestTemplates:
application/json: "{\"statusCode\": 200}"
IntegrationResponses:
- StatusCode: '200'
MethodResponses:
- StatusCode: '200'
PrivateDomainName:
Type: AWS::ApiGateway::DomainNameV2
Properties:
DomainName: !Ref DomainName
CertificateArn: !Ref CertificateArn
EndpointConfiguration:
Types:
- PRIVATE
SecurityPolicy: TLS_1_2
Policy:
Statement:
- Action: 'execute-api:Invoke'
Effect: Allow
Principal: '*'
Resource: 'execute-api:/*'
- Action: 'execute-api:Invoke'
Condition:
StringNotEquals:
'aws:SourceVpce': !Ref EndpointID
Effect: Deny
Principal: '*'
Resource: 'execute-api:/*'
Version: 2012-10-17
PrivateBasePathMapping:
Type: AWS::ApiGateway::BasePathMappingV2
DependsOn:
- PrivateApiStage
Properties:
BasePath: prod
DomainNameArn: !GetAtt PrivateDomainName.DomainNameArn
RestApiId: !Ref PrivateApi
Stage: prod
DomainNameAccessAssociation:
Type: AWS::ApiGateway::DomainNameAccessAssociation
Properties:
DomainNameArn: !GetAtt PrivateDomainName.DomainNameArn
AccessAssociationSource: !Ref EndpointID
AccessAssociationSourceType: VPCE
```