Python调用PutMetricAlarm接口报Invalid metrics list错误如何解决

在Python环境中调用boto3的put_metric_alarm接口创建CloudWatch告警时，触发如下校验错误：

[ERROR] ClientError: An error occurred (ValidationError) when calling the PutMetricAlarm 
operation: Invalid metrics list
Traceback (most recent call last):
File "/var/task/manage_alarms.py", line 672, in handle_alarms
manage_alarms(cluster_name, sns, sections, namespace, None, None, None,None)
File "/var/task/manage_alarms.py", line 584, in manage_alarms
create_alarm(alarm_name, metric_json, alarm_json,sns)
File "/var/task/manage_alarms.py", line 262, in create_alarm
response = client.put_metric_alarm(AlarmName=alarm_name,
AlarmDescription=alarm_json['Description'],
File "/var/runtime/botocore/client.py", line 391, in _api_call
return self._make_api_call(operation_name, kwargs)
File "/var/runtime/botocore/client.py", line 719, in _make_api_call
raise error_class(parsed_response, operation_name)

构造传入的参数如下：

metric_stat_json = [{'Id': 'bytesdropcountblackhole_math', 'MetricStat': {'Metric': 
{'MetricName': 'bytesdropcountblackhole', 'Namespace': 'AWS/TransitGateway', 'Dimensions': 
[{'Name': 'TransitGateway', 'Value': 'tgw-09a7a181c16936efb'}]}, 'Period': 300, 'Stat': 
'Average', 'Unit': 'Count'}, 'ReturnData': False}, {'Id': 'bytesdropcountblackhole_expr', 
'Expression': 'DIFF(bytesdropcountblackhole_math)', 'ReturnData': True}]

response=client.put_metric_alarm(AlarmName=alarm_name, AlarmDescription=alarm_json['Description'],
                        ComparisonOperator=alarm_json['Comparison'], EvaluationPeriods=alarm_json['EvalPeriod'],AlarmActions=[sns],
                        InsufficientDataActions=[sns],OKActions=[sns],Threshold=set_val,Metrics=metric_stat_json,Tags=tags)

这个报错是CloudWatch API对Metrics参数做结构校验时抛出的，结合参数特征，常见触发原因如下：

1. DIFF表达式评估周期配置错误：DIFF()函数逻辑是计算当前数据点和前一个周期数据点的差值，至少需要2个连续有效数据点才能输出结果。如果代码中alarm_json['EvalPeriod']设为1，部分旧版SDK/API区域不会返回明确的周期错误，会直接抛出Invalid metrics list。
2. 实际运行代码存在笔误：贴出的示例参数结构本身合法，但实际运行代码常出现这类问题：
   • 指标ID包含横杠-、特殊字符，或者首字符不是字母（API要求ID只能包含字母、数字、下划线，首字符必须为字母）
   • 某个Metrics数组元素同时配置了MetricStat和Expression两个互斥字段
   • 表达式中引用的指标ID和实际定义的ID拼写不一致（少字符、大小写不匹配等）
3. 指标元数据配置错误：bytesdropcountblackhole不是AWS/TransitGateway命名空间下的合法指标名，TransitGateway的黑洞丢包字节数指标正确名称为BlackholeBytesDropped，单位为Bytes而非Count，部分旧版API会把指标不存在的错误统一归为Metrics列表不合法。
4. 运行环境SDK版本过旧：Lambda Python运行时内置的boto3/botocore版本通常比官方最新版落后6个月以上，对表达式语法、参数校验逻辑存在兼容问题。

按以下步骤调整即可正常创建告警：

1. 调整告警评估周期：将EvaluationPeriods设置为大于等于2的正整数，匹配DIFF函数对数据点数量的要求。
2. 修正指标配置：将MetricName改为合法的BlackholeBytesDropped，修正Unit字段为Bytes，修正后的基础指标配置参考：

   {'Id': 'bytesdropcountblackhole_math', 
    'MetricStat': {
        'Metric': {
            'MetricName': 'BlackholeBytesDropped', 
            'Namespace': 'AWS/TransitGateway', 
            'Dimensions': [{'Name': 'TransitGateway', 'Value': 'tgw-09a7a181c16936efb'}]
        }, 
        'Period': 300, 
        'Stat': 'Average',
        'Unit': 'Bytes'
    }, 
    'ReturnData': False
   }
   

3. 校验Metrics数组结构：
   • 检查所有ID字段，确保只包含字母、数字、下划线，首字符为字母，无重复ID
   • 检查每个数组元素，确保只配置MetricStat或Expression其中一个字段，不同时配置两个互斥字段
   • 检查表达式中引用的ID和上游定义的ID完全一致，无拼写错误
4. 升级依赖版本：如果是Lambda环境，不要使用内置的boto3，打包部署时将最新版boto3、botocore打包进函数包，避免旧版本兼容问题。

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