如何對 API Gateway 公有自訂網域名稱組態問題進行疑難排解？

解決方法

若要對 API Gateway 公有自訂網域名稱組態問題進行疑難排解，請使用 AWSSupport-TroubleshootAPIGatewayCustomDomainConfig 執行手冊。此執行手冊會檢查公有自訂網域名稱是否已在 API Gateway 中設定，並確認 DNS 記錄和 API 映射的組態是否正確。如果執行手冊檢查失敗，請檢閱執行手冊輸出中的疑難排解建議。

**注意：**此執行手冊僅支援以預設路由模式 API 映射設定的公有自訂網域，不支援以路由規則的路由模式設定的自訂網域，也不支援私有自訂網域。

先決條件

在啟動 AWSSupport-TroubleshootAPIGatewayCustomDomainConfig 執行手冊之前，請確保您的 AWS Identity and Access Management (IAM) 使用者或角色具有下列權限：

• apigateway:GET
• iam:ListRoles
• iam:PassRole
• route53:ListResourceRecordSets
• ssm:DescribeAutomationExecutions
• ssm:GetAutomationExecution
• ssm:DescribeAutomationStepExecutions
• ssm:StartAutomationExecution
• ssm:DescribeDocument
• ssm:GetDocument
• ssm:ListDocuments

執行 AWSSupport-TroubleshootAPIGatewayCustomDomainConfig 執行手冊

請完成下列步驟：

1. 在 AWS 區域中開啟 AWSSupport-TroubleshootAPIGatewayCustomDomainConfig 執行手冊。
2. 選擇 Execute automation (執行自動化)。
3. 請輸入下列值作為輸入參數：
   **AutomationAssumeRole (選填)：**允許自動化以您的身分執行動作之 IAM 角色的 Amazon Resource Name (ARN)。如果您未指定角色，自動化將會使用啟動執行手冊之使用者的權限。
   **DomainName：**API 的自訂網域名稱。
   **ApiId：**API 的 ID。
   **DNSServerIp (選填)：**解析自訂網域名稱的 DNS 伺服器。如果您未指定值，則執行手冊會使用 AWS DNS Server。
   **HostedZoneId (選填)：**公有託管區域的 ID，其中包含自訂網域名稱的 DNS 記錄。如果您不是使用 DNS 適用的 Amazon Route 53，HostedZoneId 請留空。
4. 選擇 Execute (執行)。自動化隨即啟動。
5. 請檢閱 Outputs (輸出) 區段以取得詳細結果。

執行手冊會驗證下列組態：

• 自訂網域名稱存在於 API Gateway 中。
• 自訂網域名稱與任何 API 之間存在映射。
• 自訂網域名稱存在 DNS 記錄。
• DNS 記錄指向正確的目標。

如果執行手冊檢查成功執行，則輸出會顯示自訂網域名稱的組態詳細資訊。如果執行手冊檢查失敗，請檢閱疑難排解建議。

AWSSupport-TroubleshootAPIGatewayCustomDomainConfig 執行手冊的輸出範例

成功組態檢查的輸出範例：

{  "Result": "The custom domain name is configured correctly",
  "DomainDetails": {
    "DomainName": "CUSTOM DOMAIN NAME",
    "APIGatewayDomainName": "d-XXXXXXXX.execute-api.REGION.amazonaws.com",
    "Status": "XXXXXX",
    "EndpointType": "XXXXXX"
  },
  "MappingDetails": [
    {
      "API": "XXXXXX",
      "MappingId": "XXXXXX",
      "MappingKey": "XXXXXX",
      "Stage": "XXXXXX",
      "Status": "ApiHasMappings"
    }
  ],
  "DNSDetails": {
    "RECORD TYPE": [
      "XXX.XXX.XXX.XXX",
      "XXX.XXX.XXX.XXX",
      "XXX.XXX.XXX.XXX"
    ]
  }
}

自訂網域名稱不在 API Gateway 中時的輸出範例：

" Check (1/5): Check custom domain name exists.  Status: Failed.

  Troubleshooting Recommendations:
    - Custom domain name: CUSTOM DOMAIN NAME is not configured in API gateway.
    - Please see the link below for information on how to setup a custom domain for API Gateway:
      > https://aws.amazon.com/tw/premiumsupport/knowledge-center/custom-domain-name-amazon-api-gateway/

    - The remaining checks have not been run at this point hence there may be other errors in the current configuration.
    - After resolving the error above, please check that your custom domain name has:
      > A mapping to the API you are trying to reach
      > A DNS record pointing to the generated API Gateway domain name.

    - You can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details.

  Check (2/5): List mappings.
  Status: Skipped

  Check (3/5): Check mapping exists to API Id: API ID.
  Status: Skipped

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Skipped

  Check (5/5): Validate DNS record.
  Status: Skipped "

不存在自訂網域名稱映射時的輸出範例：

" Check (1/5): Check custom domain name exists.  Status: Complete

  Check (2/5): List mappings.
  Status: Failed

  Troubleshooting Recommendations:
    - CUSTOM DOMAIN NAME does not contain any mappings.
    - Please see the documentation to create one here:
      > https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-mappings.html

    - The remaining checks have not been run at this point hence there may be other errors in the current configuration.
    - After resolving the error above, please check that your custom domain name has:
      > A mapping to the API you are trying to reach
      > A DNS record pointing to the generated API Gateway domain name.

    - You can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details.

  Check (3/5): Check mapping exists to API Id: API ID.
  Status: Skipped

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Skipped

  Check (5/5): Validate DNS record.
  Status: Skipped "

自訂網域名稱沒有映射至指定 API ID 時的輸出範例：

" Check (1/5): Check custom domain name exists.  Status: Complete

  Check (2/5): List mappings.
  Status: Complete

  Check (3/5): Check mapping exists to API Id: API ID.
  Status: Failed

    Troubleshooting Recommendations:
    - A base path mapping does not exist between API Id: API ID and custom domain name: <<CUSTOM DOMAIN NAME>>.
    - Please see the documentation to create one here:
      > https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-mappings.html

    - The remaining checks have not been run at this point hence there may be other errors in the current configuration.
    - After resolving the error above, please check that your custom domain name has:
      > A mapping to the API you are trying to reach
      > A DNS record pointing to the generated API Gateway domain name.

    - You can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details.

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Not Run

  Check (5/5): Validate DNS record.
  Status: Skipped "

自訂網域名稱沒有 DNS 記錄時的輸出範例：

" Check (1/5): Check custom domain name exists.  Status: Complete

  Check (2/5): List mappings.
  Status: Complete

  Check (3/5): Check mapping exists to API Id: API ID.
  Status: Complete

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Failed

  Troubleshooting Recommendations:
    - There is no DNS record for the custom domain name: CUSTOM DOMAIN NAME or the domain could not be resolved.
    - Please check your DNS server for a record for this domain and ensure it can be resolved.

    - The remaining checks have not been run at this point hence there may be other errors in the current configuration.
    - After resolving the error above, please check that your custom domain name has:
      > A DNS record pointing to the generated API Gateway domain name.

    - You can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details.


  Check (5/5): Validate DNS record.
  Status: Skipped "

DNS 記錄未指向正確目標時的輸出範例：

" Check (1/5): Check custom domain name exists.  Status: Complete

  Check (2/5): List mappings.
  Status: Complete

  Check (3/5): Check mapping exists to API Id: <<API ID>>.
  Status: Complete

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Complete

  Check (5/5): Validate DNS record.
  Status: Failed

  Troubleshooting Recommendations:
    - The DNS record for the custom domain name: CUSTOM DOMAIN NAME may not be pointing to the correct target.
    - The API Gateway domain name generated for this custom domain name is: <<API GATEWAY DOMAIN NAME>> which should be the target of the DNS record created for the custom domain name.
    - Please check your DNS record for this domain and ensure it is pointing to the API Gateway domain name: <<API GATEWAY DOMAIN NAME>>.

    - After resolving the error above, you can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details."

相關資訊

AWS Support Automation Workflows (SAW)

Custom domain name for public REST APIs in API Gateway (API Gateway 中公有 REST API 的自訂網域名稱)

Tutorial: Create and invoke a custom domain name for private APIs (教學課程：為私有 API 建立和調用自訂網域名稱)

如何為 API Gateway API 設定公有自訂網域名稱？