AWS CLI调用apigateway put-rest-api遇504超时问题求助

针对使用aws apigateway put-rest-api部署大型OpenAPI规范时遇到的105秒504超时、CLI重试导致冲突的问题，提供以下实用解决方案：

• 禁用CLI自动重试
  AWS CLIv2默认会对失败请求进行自动重试，这正是导致冲突的核心原因。可以通过设置环境变量强制关闭重试，确保即使收到504超时，也不会触发重复请求：

  AWS_MAX_ATTEMPTS=1 aws apigateway put-rest-api --rest-api-id <你的API_ID> --mode overwrite --body file://你的openapi-spec.json
  

  执行后，手动通过aws apigateway get-rest-api --rest-api-id <你的API_ID>或AWS控制台检查API是否完成部署。

• 拆分OpenAPI规范分批导入
  将大型OpenAPI文件拆分为多个小模块，使用merge模式分批导入，减少单次请求的处理时间，从根源上避免触发105秒超时：

  # 先导入基础框架（如通用模型、根路径）
  aws apigateway put-rest-api --rest-api-id <你的API_ID> --mode merge --body file://base-api-spec.json
  # 再分批导入业务模块
  aws apigateway put-rest-api --rest-api-id <你的API_ID> --mode merge --body file://user-service-spec.json
  aws apigateway put-rest-api --rest-api-id <你的API_ID> --mode merge --body file://order-service-spec.json
  

• 自定义SDK脚本控制部署流程
  使用AWS SDK（如Python Boto3、Node.js AWS SDK）编写部署脚本，自定义超时处理和状态轮询逻辑，替代CLI的默认行为：

  import boto3
  import time
  
  api_client = boto3.client('apigateway')
  target_api_id = "你的API_ID"
  spec_file_path = "openapi-spec.json"
  
  try:
      # 发起导入请求
      api_client.put_rest_api(
          restApiId=target_api_id,
          mode="overwrite",
          body=open(spec_file_path, "rb").read()
      )
  except api_client.exceptions.GatewayTimeoutException:
      # 收到504后，轮询检查API更新状态
      print("请求超时，开始后台状态检查...")
      for _ in range(12):  # 最多检查6分钟（每30秒一次）
          time.sleep(30)
          try:
              api_details = api_client.get_rest_api(restApiId=target_api_id)
              print(f"API最后更新时间: {api_details['updatedDate']}")
              # 可根据实际业务逻辑判断是否部署完成，比如对比更新时间或检查部署记录
              break
          except Exception as e:
              print(f"状态检查失败: {str(e)}")
  

• 改用CloudFormation/SAM部署
  使用AWS CloudFormation或Serverless Application Model（SAM）定义API部署，这类工具内置了更健壮的状态检查和重试机制，会自动等待后台部署完成，避免手动CLI的重试冲突。例如在SAM模板中定义API：

  AWSTemplateFormatVersion: '2010-09-09'
  Transform: AWS::Serverless-2016-10-31
  Resources:
    MyApi:
      Type: AWS::Serverless::Api
      Properties:
        DefinitionBody:
          'Fn::Transform':
            Name: AWS::Include
            Parameters:
              Location: openapi-spec.json
        StageName: prod
  

  执行sam deploy即可完成部署，SAM会自动处理后台进程的等待逻辑。

内容的提问来源于stack exchange，提问作者Jordan