如何基于Google Ads API v11实现转化调整的批量请求？

批量请求的核心是复用UploadConversionAdjustmentsRequest的conversion_adjustments列表参数，将多条转化调整的ConversionAdjustment对象一次性传入，替代循环调用单条接口的方式，大幅减少API请求次数，提升处理效率。

修改后的批量处理代码 #

from datetime import datetime, timedelta
import pandas as pd

# 生成单个转化调整对象（仅做数据组装，不发送请求）
def build_conversion_adjustment(
    client,
    customer_id,
    conversion_action_id,
    gclid,
    conversion_date_time,
    adjustment_date_time,
    restatement_value,
    adjustment_type='RESTATEMENT'
):
    # 校验GCLID格式
    if not isinstance(gclid, str):
        return None
    
    # 处理转化时间格式
    if isinstance(conversion_date_time, str):
        conversion_date_time = datetime.strptime(conversion_date_time, '%Y-%m-%d %H:%M:%S')
    
    # 调整转化时间以规避Google API的时间校验错误
    to_datetime_plus_one = conversion_date_time + timedelta(days=1)
    if to_datetime_plus_one > datetime.utcnow():
        to_datetime_plus_one = datetime.utcnow()
    adjusted_string_date = to_datetime_plus_one.strftime('%Y-%m-%d %H:%M:%S') + "+00:00"

    # 初始化调整对象
    conversion_adjustment_type_enum = client.enums.ConversionAdjustmentTypeEnum
    conversion_adjustment_type = conversion_adjustment_type_enum[adjustment_type].value

    conversion_adjustment = client.get_type("ConversionAdjustment")
    conversion_action_service = client.get_service("ConversionActionService")
    conversion_adjustment.conversion_action = conversion_action_service.conversion_action_path(
        customer_id, conversion_action_id
    )
    conversion_adjustment.adjustment_type = conversion_adjustment_type
    conversion_adjustment.adjustment_date_time = adjustment_date_time.strftime('%Y-%m-%d %H:%M:%S') + "+00:00"

    # 设置GCLID与转化时间对
    conversion_adjustment.gclid_date_time_pair.gclid = gclid
    conversion_adjustment.gclid_date_time_pair.conversion_date_time = adjusted_string_date

    # 设置重述值（仅当调整类型为RESTATEMENT时生效）
    if conversion_adjustment_type == conversion_adjustment_type_enum.RESTATEMENT.value:
        conversion_adjustment.restatement_value.adjusted_value = float(restatement_value)
    
    return conversion_adjustment

# 批量上传转化调整
def batch_adjust_offline_conversions(
    client,
    customer_id,
    conversion_action_id,
    df,
    adjustment_date_time=None,
    adjustment_type='RESTATEMENT'
):
    if adjustment_date_time is None:
        adjustment_date_time = datetime.utcnow()
    
    # 批量生成转化调整对象列表
    conversion_adjustments = []
    for _, row in df.iterrows():
        adj_obj = build_conversion_adjustment(
            client=client,
            customer_id=customer_id,
            conversion_action_id=conversion_action_id,
            gclid=row['click_id'],
            conversion_date_time=row['subscription_time'],
            adjustment_date_time=adjustment_date_time,
            restatement_value=row['revenue'],
            adjustment_type=adjustment_type
        )
        if adj_obj:
            conversion_adjustments.append(adj_obj)
    
    if not conversion_adjustments:
        print("无有效转化调整数据，跳过上传")
        return
    
    # 组装批量请求并发送
    conversion_adjustment_upload_service = client.get_service("ConversionAdjustmentUploadService")
    request = client.get_type("UploadConversionAdjustmentsRequest")
    request.customer_id = customer_id
    request.conversion_adjustments = conversion_adjustments
    request.partial_failure = True  # 开启部分失败模式，单个条目失败不影响整体
    
    response = conversion_adjustment_upload_service.upload_conversion_adjustments(request=request)
    
    # 遍历输出结果
    for idx, result in enumerate(response.results):
        print(
            f"第{idx+1}条转化调整上传完成："
            f"调整时间={result.adjustment_date_time}，"
            f"GCLID={result.gclid_date_time_pair.gclid}，"
            f"转化动作={result.conversion_action}"
        )
    
    # 处理部分失败（如果开启）
    if response.partial_failure_error:
        print("部分转化调整上传失败，错误信息：")
        print(response.partial_failure_error)

# 调用示例
batch_adjust_offline_conversions(
    client=client,
    customer_id=customer_id,
    conversion_action_id='xxxxxxx',
    df=df
)

关键说明 #

• 批量组装逻辑：将原单条请求拆分为「生成单个调整对象」和「批量提交请求」两部分，避免循环调用API的网络开销。
• 部分失败模式：request.partial_failure = True 是批量请求的核心配置，开启后即使部分条目校验失败，其他有效条目仍会被正常处理，不会导致整个请求失败。
• 数据量限制：Google Ads API建议单次批量请求条目数不超过1000条，若每日数据量超过阈值，可将DataFrame拆分为多个批次分批上传。
• 时间处理逻辑：保留了原代码中对转化时间的调整逻辑，避免出现「转化时间早于点击时间」或「未来时间」的API错误。

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