如何通过Python SDK/脚本上传Google Ads API的Conversion Value Rules？

前置准备 #

• 安装Google Ads Python客户端库：pip install google-ads
• 配置认证文件google-ads.yaml，确保包含客户ID、开发者令牌、OAuth2凭据等必要信息
• 确认使用的API版本≥v15（Conversion Value Rules在该版本及以上可用）

核心代码示例 #

以下示例展示如何批量创建基于国家/地区和设备维度的Conversion Value Rules：

from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
from google.ads.googleads.v15.enums.types import (
    ConversionValueRuleConditionEnum,
    DeviceEnum,
    ConversionValueRuleActionEnum,
)

def create_conversion_value_rules(client, customer_id, rule_configs):
    """批量创建转化价值规则"""
    conversion_value_rule_service = client.get_service("ConversionValueRuleService")
    operation_service = client.get_service("ConversionValueRuleOperation")
    
    operations = []
    for config in rule_configs:
        # 创建国家/地区条件
        country_condition = client.get_type("ConversionValueRuleCondition")
        country_condition.condition_type = ConversionValueRuleConditionEnum.ConversionValueRuleConditionType.COUNTRY_CODE
        country_condition.country_code = config["country_code"]
        
        # 创建设备条件
        device_condition = client.get_type("ConversionValueRuleCondition")
        device_condition.condition_type = ConversionValueRuleConditionEnum.ConversionValueRuleConditionType.DEVICE
        device_condition.device = config["device"]
        
        # 创建转化值调整动作（百分比调整示例）
        action = client.get_type("ConversionValueRuleAction")
        action.action_type = ConversionValueRuleActionEnum.ConversionValueRuleActionType.CONVERSION_VALUE_ADJUSTMENT
        action.conversion_value_adjustment.percent_micros = config["adjustment_percent"] * 1000000  # 百分比转微值
        
        # 构建转化价值规则对象
        rule = client.get_type("ConversionValueRule")
        rule.customer = customer_id
        rule.name = f"CV Rule - {config['country_code']} - {config['device'].name}"
        rule.conditions.extend([country_condition, device_condition])
        rule.actions.append(action)
        rule.status = client.get_type("ConversionValueRuleStatusEnum").ConversionValueRuleStatus.ENABLED
        
        # 组装操作请求
        operation = operation_service.create(rule)
        operations.append(operation)
    
    # 批量提交请求
    try:
        response = conversion_value_rule_service.mutate_conversion_value_rules(
            customer_id=customer_id, operations=operations
        )
        print(f"成功创建 {len(response.results)} 条转化价值规则：")
        for result in response.results:
            print(f"- 规则ID：{result.resource_name.split('/')[-1]}")
    except GoogleAdsException as e:
        print(f"请求失败：{e.error.message}")
        for error in e.failure.errors:
            print(f"错误代码：{error.error_code}, 详情：{error.message}")

if __name__ == "__main__":
    # 初始化客户端
    client = GoogleAdsClient.load_from_storage("google-ads.yaml")
    customer_id = "YOUR_CUSTOMER_ID"  # 替换为你的客户ID（不带横杠）
    
    # 定义批量规则配置：国家代码、设备类型、调整百分比
    rule_configs = [
        {"country_code": "US", "device": DeviceEnum.Device.MOBILE, "adjustment_percent": 10},
        {"country_code": "US", "device": DeviceEnum.Device.DESKTOP, "adjustment_percent": 5},
        {"country_code": "CA", "device": DeviceEnum.Device.MOBILE, "adjustment_percent": 8},
        {"country_code": "CA", "device": DeviceEnum.Device.TABLET, "adjustment_percent": 3},
        # 可继续添加更多国家/设备组合
    ]
    
    create_conversion_value_rules(client, customer_id, rule_configs)

批量处理关键要点 #

• 条件枚举值正确性：国家代码必须使用ISO 3166-1 alpha-2格式（如US、CA），设备类型需从DeviceEnum中选择，避免手动输入字符串
• 批量操作限制：单次mutate_conversion_value_rules请求最多支持200条操作，若需创建数百条，建议拆分请求（比如每150条一批）
• 转化值调整类型：支持percent_micros（百分比，需乘以1e6转微值）和fixed_value（固定金额，单位为目标货币的最小单位，如美元的分）
• 规则命名：建议包含维度信息（如国家、设备），便于后续管理和排查
• 错误处理：添加异常捕获，针对API返回的错误（如重复规则、无效条件）进行针对性处理

实用扩展 #

• 可从CSV/Excel文件读取规则配置，实现更灵活的批量导入
• 添加规则更新逻辑：若规则已存在（通过名称或ID匹配），则执行更新操作而非创建
• 结合Google Ads API的查询功能，先获取现有规则，避免重复创建

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