555      阿里云

UpdateRow__API 概览_API 参考_表格存储-阿里云

行为：

更新指定行的数据。如果该行不存在，则新增一行；若该行存在，则根据请求的内容在这一行中新增、修改或者删除指定列的值。

请求消息结构：

message UpdateRowRequest {
    required string table_name = 1;
    required Condition condition = 2;
    repeated Column primary_key = 3;
    repeated ColumnUpdate attribute_columns = 4;
}

table_name：

• 类型： string。

• 是否必要参数： 是。

• 请求更新数据的表名。

condition：

• 类型： Condition。

• 是否必要参数： 是。

• 在数据更新前是否进行存在性检查，可以取下面两个值：

  • IGNORE 表示不做行存在性检查。

  • EXPECT_EXIST 表示期望行存在。

• 若期待该行存在但该行不存在，则本次更新操作会失败, 返回错误；若忽视该行是否存在，则无论该行是否存在，都不会因此导致本次操作失败。

primary_key：

• 类型： repeated Column。

• 是否必要参数： 是。

• 请求更新的行全部的主键列。

attribute_columns：

• 类型： repeated ColumnUpdate。

• 是否必要参数： 是。

• 该行本次想要更新的全部属性列，表格存储会根据 attribute_columns 中每个 ColumnUpdate 的内容在这一行中新增、修改或者删除指定列的值。

• 该行已经存在的不在 attribute_columns 列表中的列将不受影响。

• attribute_columns 中应至少含有一个 ColumnUpdate 对象，否则请求失败，返回错误。

• 若 attribute_columns 中出现了相同列名的列，则请求失败，返回错误。

• attribute_columns 中 ColumnUpdate 的个数不能超过 1024 个；更新完成后，每行的属性列亦不能超过 1024 个。

• ColumnUpdate 的 type 可以取下面两个值：

  • PUT：此时该 ColumnUpdate 的 value 必须为有效的属性列值。语意为如果该列不存在，则新增一列；如果该列存在，则覆盖该列。

  • DELETE：此时该 ColumnUpdate 的 value 必须为空。语意为删除该列。

• 如果该行不存在，且 attribute_columns 中只含有 type 为 DELETE的ColumnUpdate，则 UpdateRow 操作完成后该行仍然不存在。

注意：删除本行的全部属性列不等同于删除本行，若想删除本行，请使用 DeleteRow 操作。

响应消息结构：

message UpdateRowResponse {
    required ConsumedCapacity consumed = 1;
}

consumed：

• 类型 ConsumedCapacity。

• 本次操作消耗的服务能力单元。

服务能力单元消耗：

• 如果该行不存在：

  • 若指定条件检查为 IGNORE，消耗写服务能力单元的数值为本行的主键数据大小与要更新的属性列数据大小之和除以 4 KB 向上取整。如果 UpdateRow 中包含有需要删除的属性列，只有其列名长度计入该属性列数据大小。

  • 若指定条件检查为 EXPECT_EXIST，本次插入失败并且消耗 1 单位写 CU 和 1 单位读 CU。

• 如果该行存在：

  • 若指定条件检查为 IGNORE，消耗写服务能力单元的数值为本行的主键数据大小与要更新的属性列数据大小之和除以 4 KB 向上取整。如果 UpdateRow 中包含有需要删除的属性列，只有其列名长度计入该属性列数据大小。

  • 若指定条件检查为 EXPECT_EXIST，除了需要消耗在条件检查为 IGNORE 情况下的写 CU，还需消耗该行主键数据大小除以 4 KB 向上取整的读 CU。

关于数据大小的计算请参见购买指导。

• 如果请求超时，结果未定义，服务能力单元有可能被消耗，也可能未被消耗。

• 如果返回内部错误（HTTP 状态码：5XX），则此次操作不消耗服务能力单元；其他错误情况消耗 1 个写服务能力单元和 1 个读服务能力单元。

请求示例：

UpdateRowRequest {
  table_name: "consume_history"
  condition {
    row_existence: EXPECT_EXIST
  }
  primary_key {
    name: "CardID"
    value {
      type: STRING
      v_string: "2007035023"
    }
  }
  primary_key {
    name: "SellerID"
    value {
      type: STRING
      v_string: "00022"
    }
  }
  primary_key {
    name: "DeviceID"
    value {
      type: STRING
      v_string: "061104"
    }
  }
  primary_key {
    name: "OrderNumber"
    value {
      type: INTEGER
      v_int: 142857
    }
  }
  attribute_columns {
    type: PUT
    name: "Amount"
    value {
      type: DOUBLE
      v_double: 3.5
    }
  }
  attribute_columns {
    type: DELETE
    name: "Remarks"
  }
}

响应示例：

UpdateRowResponse {
  consumed {
    capacity_unit {
      write: 1
    }
  }
}

最后更新：2016-11-23 16:03:56

  上一篇： PutRow__API 概览_API 参考_表格存储-阿里云

  下一篇： DeleteRow__API 概览_API 参考_表格存储-阿里云