GCP Datastore Python报InvalidArgument:400 非事务提交不可含同一实体多变更

• 报错的核心原因是同一个非事务提交请求中包含了多条针对同一实体（相同key）的修改操作，Cloud Datastore 的非事务提交规则明确禁止单批次内重复修改同一个实体，因此直接抛出 InvalidArgument 错误。
• 现有代码未对传入的 records 列表做去重处理：如果同一批次的 records 中存在多条 name 取值相同的记录，循环生成实体时就会向 entities 列表中加入多个 key 完全一致的实体，调用 put_multi 时就会触发该错误。
• 自动扩缩容场景下该问题高发，通常是因为流量高峰时上游数据生成/消费逻辑出现重复投递（比如队列重试、请求重复触发等），导致单批次 records 出现重复 key 的概率大幅升高。

注意：该错误并非跨实例并发写入同一个 key 导致，跨实例并发修改单 key 会抛出并发冲突异常，和当前报错信息完全不同。

方案1：单批次去重（最简方案，适配绝大多数场景） #

如果业务逻辑允许同批次内后写入的记录覆盖先写入的同 key 记录，只需要在生成实体前按 key 对 records 做去重即可，修改后代码如下：

def datastore_upload(records: list):
    client = datastore.Client()
    kind = "some_kind"
    entities = []
    # 按name去重，保留同name最后出现的记录
    unique_records = {}
    for record in records:
        unique_records[record['name']] = record
    for record in unique_records.values():
        key = client.key(kind, record['name'])
        task = datastore.Entity(key=key)
        task['x'] = record['x']
        task['y'] = record['y']
        entities.append(task)
    client.put_multi(entities)

方案2：事务提交（适配有强一致性要求的场景） #

如果业务需要严格保证写入的顺序正确性，或者需要额外处理跨实例并发修改的冲突问题，可以改用事务提交，配合重试逻辑保证写入成功：

from google.cloud import datastore
from google.api_core import retry

def datastore_upload(records: list):
    client = datastore.Client()
    kind = "some_kind"
    # 先做去重减少无效事务操作
    unique_records = {record['name']: record for record in records}
    for name, record in unique_records.items():
        key = client.key(kind, name)
        # 配置重试逻辑处理并发冲突
        @retry.Retry()
        def update_entity():
            with client.transaction():
                entity = client.get(key)
                if not entity:
                    entity = datastore.Entity(key=key)
                entity['x'] = record['x']
                entity['y'] = record['y']
                client.put(entity)
        update_entity()

方案3：分批次提交（适配大批次高性能写入场景） #

如果批次写入性能要求很高，可以先将全量 records 按 key 拆分，保证每个子批次内不存在重复 key，再分批调用 put_multi，兼顾写入性能和正确性。

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