新增数据

通过 HTTP RESTful API 对 MySQL 数据库进行新增操作。具体接口详情请参考 HTTP API/MySQL数据库

基础语法

POST https://your-envId.api.tcloudbasegateway.com/v1/rdb/rest/:table
Authorization: Bearer <access_token>
Content-Type: application/json

💡 提示：access_token 请参考 获取AccessToken

基础新增

# 新增单条数据到 film表
curl -X POST 'https://{{host}}/v1/rdb/rest/film' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "title": "Inception",
  "release_year": 2010,
  "director": "Christopher Nolan",
  "duration": 148
}'

💡 注意：默认情况下新增操作不返回数据，仅返回状态码和受影响行数

Response

• content-range: */1，表示受影响行数，此时标表示插入了 1 条数据
• preference-applied: return=minimal，表示执行写数据时，采用了 return=minimal 的返回策略（写操作默认行为，即不产生返回体）

请求返回示例

HTTP/1.1 201 Created
Header:
    content-length: 0
    content-range: */1
    preference-applied: return=minimal
Body: (Empty)

新增并返回数据

# 新增数据并返回插入的完整记录
curl -X POST 'https://{{host}}/v1/rdb/rest/film?select=*' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-H 'Prefer: return=representation' \
-d '{
    "title": "The Shawshank Redemption",
    "release_year": 1994,
    "director": "Frank Darabont",
    "duration": 142
}'

Request

• 请求中指定 Header Prefer: return=representation，表示执行新增时，返回新增后的数据，不会额外产生一次查询，默认返回所有字段数据

Response

• 如果表中存在自增字段，则返回值中会包含自增字段的值

请求返回示例

HTTP/1.1 201 Created
Header:
    content-length: 266
    content-range: */1
    preference-applied: return=representation
Body:
[
    {
        "_openid": "1977683311217119233",
        "director": "Frank Darabont",
        "duration": 142,
        "id": 2,
        "release_year": 1994,
        "title": "The Shawshank Redemption"
    }
]

指定返回字段

# 新增数据并返回指定字段
curl -X POST 'https://{{host}}/v1/rdb/rest/film?select=title,director' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-H 'Prefer: return=representation' \
-d '{
    "title": "The Godfather",
    "release_year": 1972,
    "director": "Francis Ford Coppola",
    "duration": 175
}'

Request

• 请求中指定 Header Prefer: return=representation，表示执行新增时，返回新增后的数据，不会额外产生一次查询，默认返回所有字段数据
• 指定/table?select=*时，默认返回插入的所有字段数据；指定/table?select=id,title,director时，返回插入的指定字段数据

请求返回示例

HTTP/1.1 201 Created
Header:
    content-length: 78
    content-range: */1
    preference-applied: return=representation
Body:
[
    {
        "id": 1,
        "director": "Francis Ford Coppola",
        "title": "The Godfather"
    }
]

批量新增

# 批量新增多条数据
curl -X POST 'https://{{host}}/v1/rdb/rest/film?select=id,title,director,duration' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-H 'Prefer: return=representation' \
-d '[
    {
        "title": "The Godfather: Part II",
        "release_year": 1974,
        "director": "Francis Ford Coppola",
        "duration": 202
    },
    {
        "title": "The Godfather: Part III",
        "release_year": 1990,
        "director": "Francis Ford Coppola",
        "duration": 194
    }
]'

Response

• content-range: */2 表示本次请求创建了2条数据
• 批量创建数据时，整体在一个事务中，如果有失败，则整体回滚

请求返回示例

HTTP/1.1 201 Created
Header:
    content-length: 312
    content-range: */2
    preference-applied: return=representation
Body:
[
    {
        "director": "Francis Ford Coppola",
        "duration": 202,
        "id": 4,
        "title": "The Godfather: Part II"
    },
    {
        "director": "Francis Ford Coppola",
        "duration": 194,
        "id": 5,
        "title": "The Godfather: Part III"
    }
]

注意

注意： 在执行批量创建时，自增字段回填可能不准确，请不要依赖批量创建时返回的自增字段！

原因：受 MySQL 数据库特性影响，创建数据时 MySQL 仅能知道受影响行数，以及最终插入的自增值是多少，从而推算出这一批数据的自增值。但是自增值分配并非连续的，可能遇到"手动指定"、"INSERT IGNORE"、"INSERT ON DUPLICATE KEY UPDATE"等情况，导致自增值分配不连续。

新增冲突时执行更新

# 新增或更新数据
curl -X POST 'https://{{host}}/v1/rdb/rest/film?select=*' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-H 'Prefer: return=representation, resolution=merge-duplicates' \
-d '{
    "title": "The Godfather",
    "release_year": 1972,
    "director": "Francis Ford Coppola",
    "duration": 175
}'

Request

• return=representation 表示执行写数据时，返回写入后的数据，配合 select 一起使用，默认返回所有字段数据
• resolution=merge-duplicates 表示当创建冲突时，进行更新处理。冲突依据：当主键或唯一索引存在创建冲突时，进行更新处理
• content-range: */2 表示受影响行数，此时表示本次请求创建 1 条数据时发生冲突，从而进行更新处理，所以受影响行数为 2

注意

• 由于 MySQL 数据库特性限制，resolution=merge-duplicates 在 高并发 场景下存在 死锁 风险，请谨慎使用。
• 当使用 resolution=merge-duplicates 时，请确保请求体中包含主键或唯一索引字段。
• 当使用 resolution=merge-duplicates 时， MySQL 将这种情况视为 ​先尝试插入再更新，因此：
  • ​插入尝试​：计为 1 行受影响（即使未实际插入）。
  • ​更新操作​：计为 1 行受影响。
  • ​总计 content-range 返回 2

请求返回示例

HTTP/1.1 201 Created

Header:
    content-length: 116
    content-range: */2
    content-type: application/json; charset=utf-8
    preference-applied: return=representation, resolution=merge-duplicates

Body:
[
    {
        "_openid": "1977683311217119233",
        "director": "Nolan",
        "duration": 150,
        "id": 1,
        "release_year": 2010,
        "title": "Inception"
    }
]

新增冲突时执行忽略

# 新增或更新数据
curl -X POST 'https://{{host}}/v1/rdb/rest/film?select=*' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-H 'Prefer: return=representation, resolution=ignore-duplicates' \
-d '{
    "title": "The Godfather",
    "release_year": 1972,
    "director": "Francis Ford Coppola",
    "duration": 175
}'

Request

• return=representation 表示执行写数据时，返回写入后的数据，配合 select 一起使用，默认返回所有字段数据
• resolution=ignore-duplicates 表示当创建冲突时，进行忽略处理。冲突依据：当主键或唯一索引存在创建冲突
• content-range: */0 当创建冲突时，进行忽略，此时受影响行数为 0， content-range: */0 。

注意

• 当使用 resolution=ignore-duplicates 时， MySQL 将这种情况视为 ​静默忽略​（不插入也不更新），所以受影响行数是 0。 即使忽略了冲突，仍会消耗一个自增值

Response

HTTP/1.1 201 Created

Header:
    content-length: 125
    content-range: */0
    content-type: application/json; charset=utf-8
    preference-applied: return=representation, resolution=ignore-duplicates

Body: 
[
    {
        "_openid": "1977683311217119233",
        "director": "Sidney Lumet",
        "duration": 96,
        "id": 2,
        "release_year": 1957,
        "title": "12 Angry Men"
    }
]