使用ArcGIS API for Python执行upsert操作时遇未知错误（500）

核心排查方向： #

• 严格校验唯一字段匹配：确认an_unique_field在要素图层与GeoJSON中的一致性——字段名大小写完全匹配、数据类型统一（比如图层是字符串类型，GeoJSON中对应字段不能是数字）、无空值。ArcGIS的upsert_matching_field对字段匹配的要求极高，细微差异都可能触发服务器内部错误。
• 跳过中间Item上传步骤：直接将GeoJSON文件路径传入append的data参数，无需先通过gis.content.add上传成Item。示例代码：

  my_layer.append(
      data="myfile.geojson",
      upload_format='geojson', 
      upsert=True,
      upsert_matching_field='an_unique_field',
      update_geometry=True,
  )
  

  手动上传能成功说明文件本身无问题，中间的Item上传可能引入额外元数据处理，导致append读取时出错。
• 检查权限与权限范围：确保当前GIS用户拥有该要素图层的编辑权限，且API调用的token覆盖了append操作的所有权限要求（比如托管图层需具备「要素图层编辑」的具体权限）。
• 排查GeoJSON细节兼容性：虽然geojson.io验证有效，但ArcGIS对GeoJSON有特定要求：
  • 属性字段名避免特殊字符（空格、斜杠、中文等），尽量用下划线分隔
  • 多边形坐标遵循WGS84（经纬度）顺序，且首尾坐标闭合
  • 属性值不含换行符、HTML标签等特殊格式内容
• 查看服务器端日志：若使用ArcGIS Online托管图层，登录后台进入要素图层的「设置」-「查看日志」，定位对应时间的500错误条目，日志会提供具体的错误原因（比如某字段或要素引发的问题）。
• 添加skip_related参数：如果图层关联了其他表或图层，追加skip_related=True参数，避免关联数据处理引发的错误。
• 调整API版本：部分版本的ArcGIS API for Python在处理GeoJSON upsert时存在bug，尝试切换到稳定版本（如2.2.0或最新稳定版）测试。

简化替代方案（若append暂时无法修复）： #

封装edit_features的逻辑，减少手动操作：

from arcgis.features import FeatureLayer
import json

def batch_upsert(layer, geojson_path, unique_field):
    # 读取GeoJSON要素
    with open(geojson_path, encoding="utf-8") as f:
        features = json.load(f)["features"]
    
    # 构建现有图层的唯一字段与OBJECTID映射
    existing_records = layer.query(where="1=1", out_fields=[unique_field, "OBJECTID"]).features
    id_mapping = {feat.attributes[unique_field]: feat.attributes["OBJECTID"] for feat in existing_records}
    
    adds = []
    updates = []
    for feat in features:
        attr = feat["properties"]
        if attr[unique_field] in id_mapping:
            # 补充OBJECTID用于更新
            feat["attributes"]["OBJECTID"] = id_mapping[attr[unique_field]]
            updates.append(feat)
        else:
            adds.append(feat)
    
    # 按250要素拆分批量提交
    def split_chunks(lst, size):
        for i in range(0, len(lst), size):
            yield lst[i:i+size]
    
    for chunk in split_chunks(adds, 250):
        layer.edit_features(adds=chunk)
    for chunk in split_chunks(updates, 250):
        layer.edit_features(updates=chunk)

调用时只需传入图层对象、GeoJSON路径和唯一字段，无需手动处理拆分与映射。

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