批量处理批处理解决方案 REST API

如何进行批量操作（Bulk Operations）

Vano

2023-04-09

原文标题：BULK OPERATIONS
原文链接：http://apostolidis.me/bulk-operations/
作者：John Apostolidis

介绍

Restful API

本文不涉及如何创建一个强大的 Restful API。我们将重点介绍如何在 Restful API 上应用批量操作。我们基于 Restful API 的直接方法。假设，我们想要单独对一个集合进行操作，我们将使用以下路由（Route）:

URL	类型	描述
/user	POST	创建用户
/user	GET	获取所有用户
/user/:id	GET	获取具有特定 id 的用户
/user/:id	PATCH/PUT	更新具有特定 id 的用户
/user/:id	DELETE	删除具有特定 id 的用户

例如，如果我们想更新一个用户，我们可以对/user/:id进行 PATCH 请求，在请求 body 中提供我们想更新的字段作为 JSON 对象。

PATCH /user/:id
Content-Type: application/json
{
    "firstName": "my first name"
}

批量操作

当我们必须在多个条目中应用相同的功能时，就需要批量操作。

一个简单的方法是为每个条目发送一个请求。不过显然这是对资源的浪费，而且速度太慢。我们寻找的是一种对一组条目使用一个请求的方法。

有很多关于如何实施批量操作的文章。我们将从不同的方面来探讨批量架构。

与批处理（Batch）操作的区别

我们不希望与批处理操作混淆。批量操作是在一个请求中捆绑了不同的行动和路由，这些路由没有任何连贯性，甚至有可能，每条路由都与其他路由完全不同。批量请求通常是希望在一个请求中应用相同功能的一组条目。

真实案例

Facebook:graph-api

Facebook 不支持批处理操作，它只支持批量操作。

curl \
    -F ‘access_token=…’ \
    -F ‘batch=[{“method”:”GET”, “relative_url”:”me”},{“method”:”GET”, “relative_url”:”me/friends?limit=50”}]’ \
    https://graph.facebook.com

Jira:create-issues

路由:使用附加链接/rest/api/2/issue/bulk。
请求参数:该请求提供一个条目数组。

{
    "issueUpdates": [
        {
            "update": {
                "worklog": ...
            }
        }
    ]
}

Zendesk:new bulk api

路由:URL 上以逗号分隔的 ID。
请求参数:一个条目作为 body 参数，将应用于 ID。

curl https://{subdomain}.zendesk.com/api/v2/organizations/update_many.json?external_ids=external_1,external_2 \  
-H "Content-Type: application/json" -X PUT\  
-v -u {email_address}:{password} \  
-d '{"organization": {"notes": "Something interesting"\}\}'

Gmail:Mark as unread

路由:使用特殊参数设置批量操作。
请求参数:请求 body 中的 ID 作为表单数据。

https://mail.google.com/mail/u/0/?ui=2&ik=3g4f2h34j23&rid=mail%3Amau.4ef1.1.0&at=sdfgasfsdvfsdvfasd&view=up&act=ur&_reqid=2344&pcd=1&mb=0&rt=j&search=inbox

form data:
t:3452524524534
t:3453453453454

Workable:all bulk activities

路由:提交所有批量操作的单一路由。
请求参数:批量操作由 JSON 对象描述。

https://encodegroup.workable.com/backend/api/activities/bulk

{
  "bulk_action": "read",
  "activity_ids": [
    41928042,
    41886730
  ],
  "include_archived": true
}

Gitlab:issues bulk update

路由:批量操作的附加路由。
请求参数:ID 通过表单数据提供。

https://gitlab.encode.local/enorasys-sa/enorasys-sa-webui/issues/bulk_update

update[issuable_ids]:2330,2327
update[add_label_ids][]:41

灵活性

关于批量灵活性，有两种方法。

严格：对多个 ID 仅应用一项操作。因为我们只发送要更新的字段和要应用的 ID，请求的有效载荷减少。

2. 灵活：对多个 ID 应用不同的操作。因为我们为每个 ID 发送一个要更新的字段数组，请求的有效载荷增加。

重复使用

对于单个操作（使用不同的参数）可以重复使用相同的路由，也可以创建一个完全不同的路由。

相同路由

重复使用我们用于单个操作的相同路由，并使用其他参数来单独分离。这些参数可能是:

请求 body 上的对象数组（对于批量操作）、单个对象的实例（对于单次操作）
请求 header 上的参数。例如，使用一个 header 参数来定义批量或单一性。

不同路由

为每个单一路由创建一个额外的路由，以便应用批量操作。

提议

我的建议是在批量操作中重复使用相同的路由。与单个操作相比，唯一的区别是路由的 URL 将不包含/:id后缀。/:id是没有用的，因为该操作将被应用于多个请求。

这些请求将标有X-Action: bulk header。该 header 提供了一个额外的理解，即该请求涉及一个批量操作。

请求的 body 将包含一个 JSON 格式的对象数组。每个对象都在一个条目中，格式相同，只有一个操作。该条目将包含:

操作	类型	输入参数
创建	POST	要创建的条目字段
更新	PATCH	每个条目的更新字段，包括 id。
删除	DELETE	仅条目 id。

批量更新示例

按 ID 选择多个条目应用更新

PATCH /user
X-Action: bulk
[
    {
        "firstName": "my first name (1)",
        "Id": "id1"
    },
    {
        "firstName": "my first name (2)",
        "Id": "id2"
    }    
]

对一组条目应用更新

PATCH /user?optionallyFilter1=value1
X-Action: bulk
{
    "firstName": "my first name (1)"
}

其他

关于批处理请求可以查看：

介绍