您最多选择25个主题
主题必须以字母或数字开头，可以包含连字符 (-)，并且长度不得超过35个字符
202 行
14 KiB
202 行
14 KiB
-module(agTransactions).
|
|
-include("eArango.hrl").
|
|
|
|
-compile(inline).
|
|
-compile({inline_size, 128}).
|
|
-compile([export_all, nowarn_export_all]).
|
|
|
|
% doc_address:https://www.arangodb.com/docs/stable/http/transaction.html
|
|
|
|
% 交易的HTTP接口
|
|
% 交易次数
|
|
% ArangoDB的事务在服务器上执行。交易可以由客户以两种不同的方式执行：
|
|
%
|
|
% 通过流事务 API
|
|
% 通过JavaScript交易 API
|
|
% 两者之间的区别不难理解，下面列出了一个简短的入门。有关ArangoDB中事务如何工作以及ArangoDB可以提供哪些保证的详细说明，请参阅Transactions。
|
|
%
|
|
% 流交易
|
|
% 流事务使您可以使用单独的开始和提交/中止命令执行多文档事务。这类似于传统RDBMS使用BEGIN，COMMIT和ROLLBACK操作的方式。
|
|
%
|
|
% 这是大型交易的推荐API。但是，客户端负责确保不再需要事务时提交或中止事务，以避免占用资源。
|
|
%
|
|
% JavaScript交易
|
|
% JS-Transactions允许您向服务器发送一段专用的JavaScript代码（即一个函数），该代码将以事务方式执行。
|
|
%
|
|
% 在该功能结束时，将自动提交事务，并且该事务完成的所有更改都将保留。除了初始启动请求之外，客户端不需要任何交互。
|
|
|
|
% 局限性固定链接
|
|
% 在协调器上强制执行流事务的最大生命周期和事务大小，以确保事务不会阻止群集正常运行：
|
|
%
|
|
% 两次操作之间的最大闲置超时时间为10秒
|
|
% 每个数据库服务器的最大事务大小为128 MB
|
|
% 这些限制也适用于单个服务器上的流事务。
|
|
%
|
|
% 强制执行限制对于释放被放弃的事务使用的资源很有用，例如，从由于编程错误而被客户端应用程序放弃的事务中，或者从由于客户端连接中断而留下的事务中释放资源。
|
|
|
|
% 流事务的HTTP接口
|
|
% 在v3.5.0中引入
|
|
% 流事务使您可以使用单独的开始和提交/中止命令执行多文档事务。这类似于传统RDBMS使用BEGIN，COMMIT和ROLLBACK操作的方式。
|
|
% 要使用流事务，客户端首先将 事务的配置发送到ArangoDB服务器。
|
|
% 与JS-Transaction相反，此事务的定义必须仅包含将要使用的集合以及（可选）ArangoDB支持的各种事务选项。不支持任何动作属性。
|
|
% 流事务API 与ArangoDB中的其他API 结合使用。要将事务用于支持的操作，客户端需要在每个请求的x-arango-trx-id标头中指定事务标识符。这将自动使这些操作使用指定的事务。
|
|
% 支持的事务性API操作包括：
|
|
% Document API中的所有操作
|
|
% 通过Collection API的文档数
|
|
% 通过Collection API截断集合
|
|
% 通过Cursor API创建AQL游标
|
|
% 处理 托管图的顶点和边（通用图 / Gharial API，从v3.5.1开始）
|
|
% 请注意，客户端始终需要首先启动事务，并且需要显式指定用于写访问的集合。客户端负责确保不再需要事务时提交或中止事务。这样可以避免占用ArangoDB服务器上的资源。
|
|
% 事务将获取集合锁，用于MMFiles存储引擎中的读写操作以及RocksDB中的写操作。因此，建议尽量缩短交易时间。
|
|
% 有关ArangoDB中事务如何工作的更详细描述，请参阅Transactions。
|
|
% 另请参阅：
|
|
% 局限性
|
|
% 已知的问题
|
|
|
|
% 开始服务器端事务
|
|
% POST /_api/transaction/begin
|
|
% 具有以下属性的JSON对象是必需的：
|
|
% collections：collections必须是一个JSON对象，可以具有一个或所有子属性read，write或Exclusive，每个子属性 都是collection名称的数组或单个collection name作为字符串。必须使用write或Exclusive属性声明将在事务中写入的集合，否则它将失败，而仅从中读取的未声明集合将被延迟添加。有关 更多信息，请参见锁定和隔离。
|
|
% waitForSync：一个可选的布尔标志，如果设置了该标志，将强制事务在返回之前将所有数据写入磁盘。
|
|
% allowImplicit：允许从未声明的集合中读取。
|
|
% lockTimeout：一个可选的数值，可用于设置等待收集锁的超时时间。如果未指定，将使用默认值。将lockTimeout设置为0将使ArangoDB不会在等待锁定时超时。
|
|
% maxTransactionSize：事务大小限制（以字节为单位）。仅受RocksDB存储引擎的尊敬。
|
|
% 事务描述必须在POST请求的正文中传递。如果可以在服务器上启动事务，则将返回HTTP 201。
|
|
% 对于成功启动的事务，返回的JSON对象具有以下属性：
|
|
% error：布尔值标志，指示是否发生错误（ 在这种情况下为false）
|
|
% code：HTTP状态码
|
|
% 结果：结果包含
|
|
% id：交易的标识符
|
|
% status：包含字符串“ running”
|
|
% 如果缺少交易规范或格式错误，则服务器将使用HTTP 400或HTTP 404进行响应。
|
|
% 然后，响应的主体将包含带有其他错误详细信息的JSON对象。该对象具有以下属性：
|
|
% error：布尔值标志，指示发生错误（在这种情况下为true）
|
|
% code：HTTP状态码
|
|
% errorNum：服务器错误号
|
|
% errorMessage：描述性错误消息
|
|
% 返回码
|
|
% 201：如果事务正在服务器上运行， 则将返回HTTP 201。
|
|
% 400：如果事务规范丢失或格式不正确，则服务器将使用HTTP 400进行响应。
|
|
% 404：如果事务规范包含未知集合，则服务器将使用HTTP 404进行响应。
|
|
beginTransaction(PoolNameOrSocket, MapData) ->
|
|
agVstCli:callAgency(PoolNameOrSocket, ?AgPost, <<"/_api/transaction/begin">>, ?AgDefQuery, ?AgDefHeader, eVPack:encode(MapData)).
|
|
|
|
% 提取服务器端事务的状态
|
|
% GET /_api/transaction/{transaction-id}
|
|
% 路径参数
|
|
% transaction-id（必填）：交易标识符。
|
|
% 结果是一个描述事务状态的对象。它至少具有以下属性：
|
|
% id：交易的标识符
|
|
% status：交易的状态。“运行”，“承诺”或“中止”之一。
|
|
% 返回码
|
|
% 200：如果事务已在服务器上完全执行并提交， 则将返回HTTP 200。
|
|
% 400：如果指定的事务标识符丢失或格式错误，则服务器将使用HTTP 400进行响应。
|
|
% 404：如果找不到具有指定标识符的交易，则服务器将使用HTTP 404进行响应。
|
|
getTransactionStatus(PoolNameOrSocket, TransactionId) ->
|
|
Path = <<"/_api/transaction/", (agMiscUtils:toBinary(TransactionId))/binary>>,
|
|
agVstCli:callAgency(PoolNameOrSocket, ?AgGet, Path).
|
|
|
|
% 提交或中止正在运行的事务必须由客户端完成。在完成使用事务后，不要提交或中止事务是一个坏习惯。这将迫使服务器保留资源和收集锁，直到整个事务超时为止。
|
|
% 提交交易
|
|
% 提交服务器端事务
|
|
% PUT /_api/transaction/{transaction-id}
|
|
% 路径参数
|
|
% transaction-id（必填）：交易标识符，
|
|
% 提交正在运行的服务器端事务。提交是幂等操作。多次提交事务不是错误。
|
|
% 如果可以提交事务，则将返回HTTP 200。返回的JSON对象具有以下属性：
|
|
% error：布尔值标志，指示是否发生错误（ 在这种情况下为false）
|
|
% code：HTTP状态码
|
|
% 结果：结果包含
|
|
% id：交易的标识符
|
|
% status：包含字符串“ committed”
|
|
% 如果找不到事务，不允许提交或事务被中止，则服务器将使用HTTP 400，HTTP 404或HTTP 409进行响应。
|
|
% 然后，响应的主体将包含带有其他错误详细信息的JSON对象。该对象具有以下属性：
|
|
% error：布尔值标志，指示发生错误（在这种情况下为true）
|
|
% code：HTTP状态码
|
|
% errorNum：服务器错误号
|
|
% errorMessage：描述性错误消息
|
|
% 返回码
|
|
% 200：如果已提交事务， 则将返回HTTP 200。
|
|
% 400：如果无法提交事务，则服务器将使用HTTP 400进行响应。
|
|
% 404：如果未找到事务，则服务器将使用HTTP 404进行响应。
|
|
% 409：如果事务已经中止，则服务器将使用HTTP 409进行响应。
|
|
commitTransaction(PoolNameOrSocket, TransactionId) ->
|
|
Path = <<"/_api/transaction/", (agMiscUtils:toBinary(TransactionId))/binary>>,
|
|
agVstCli:callAgency(PoolNameOrSocket, ?AgPut, Path).
|
|
|
|
% 中止服务器端事务
|
|
% DELETE /_api/transaction/{transaction-id}
|
|
% 路径参数
|
|
% transaction-id（必填）：交易标识符，
|
|
% 中止正在运行的服务器端事务。中止是一个幂等的操作。多次中止事务不是错误。
|
|
% 如果可以中止该事务，则将返回HTTP 200。返回的JSON对象具有以下属性：
|
|
% error：布尔值标志，指示是否发生错误（ 在这种情况下为false）
|
|
% code：HTTP状态码
|
|
% 结果：结果包含
|
|
% id：交易的标识符
|
|
% status：包含字符串“ aborted”
|
|
% 如果找不到事务，不允许中止或已提交事务，则服务器将使用HTTP 400，HTTP 404或HTTP 409进行响应。
|
|
% 然后，响应的主体将包含带有其他错误详细信息的JSON对象。该对象具有以下属性：
|
|
% error：布尔值标志，指示发生错误（在这种情况下为true）
|
|
% code：HTTP状态码
|
|
% errorNum：服务器错误号
|
|
% errorMessage：描述性错误消息
|
|
% 返回码
|
|
% 200：如果事务中止， 将返回HTTP 200。
|
|
% 400：如果无法中止事务，则服务器将使用HTTP 400进行响应。
|
|
% 404：如果未找到事务，则服务器将使用HTTP 404进行响应。
|
|
% 409：如果事务已经提交，则服务器将以HTTP 409响应。
|
|
abortTransaction(PoolNameOrSocket, TransactionId) ->
|
|
Path = <<"/_api/transaction/", (agMiscUtils:toBinary(TransactionId))/binary>>,
|
|
agVstCli:callAgency(PoolNameOrSocket, ?AgDelete, Path).
|
|
|
|
% 返回当前运行的服务器端事务
|
|
% GET /_api/transaction
|
|
% 结果是一个对象，该对象使用transactions属性进行描述，其中包含一个事务数组。在群集中，阵列将包含来自所有协调器的事务。
|
|
% 每个数组条目都包含一个具有以下属性的对象：
|
|
% id：交易的ID
|
|
% status：交易的状态
|
|
% 返回码
|
|
% 200：如果可以成功检索事务列表，则将返回HTTP 200。
|
|
transactionList(PoolNameOrSocket) ->
|
|
agVstCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/transaction">>).
|
|
|
|
% JavaScript交易的HTTP接口
|
|
% ArangoDB的JS事务在服务器上执行。客户端可以通过将事务描述发送给服务器来启动事务。
|
|
% ArangoDB中的JS事务不提供单独的BEGIN，COMMIT和ROLLBACK 操作。取而代之的是，ArangoDB JS事务由JavaScript函数描述，然后JavaScript函数中的代码将以事务方式执行。
|
|
% 在该功能结束时，将自动提交事务，并且该事务完成的所有更改都将保留。如果在事务执行过程中引发异常，则将回滚事务中执行的所有操作。
|
|
% 有关ArangoDB中事务如何工作的更详细描述，请参阅Transactions。
|
|
|
|
% 执行服务器端事务
|
|
% POST /_api/transaction
|
|
% 具有以下属性的JSON对象是必需的：
|
|
% collections：collections必须是一个JSON对象，可以具有一个或所有子属性read，write或Exclusive，每个子属性 都是collection名称的数组或单个collection name作为字符串。必须使用write或Exclusive属性声明将在事务中写入的集合，否则它将失败，而仅从中读取的未声明集合将被延迟添加。可以将可选的子属性allowImplicit设置为false， 以使事务在未声明声明的读取集合的情况下失败。如果可能，应完全声明要读取的集合，以避免死锁。看到锁定和隔离 以获取更多信息。
|
|
% action：要执行的实际交易操作，采用字符串化JavaScript代码的形式。该代码将在服务器端执行，并具有后期绑定。因此，至关重要的是，在操作中指定的代码 正确设置其所需的所有变量。如果操作中指定的代码以return语句结尾， 则如果事务成功提交，则REST API还将在result属性中返回返回的值。
|
|
% waitForSync：一个可选的布尔标志，如果设置了该标志，将强制事务在返回之前将所有数据写入磁盘。
|
|
% allowImplicit：允许从未声明的集合中读取。
|
|
% lockTimeout：一个可选的数值，可用于设置等待收集锁的超时时间。如果未指定，将使用默认值。将lockTimeout设置为0将使ArangoDB不会在等待锁定时超时。
|
|
% params：传递给操作的可选参数。
|
|
% maxTransactionSize：事务大小限制（以字节为单位）。仅受RocksDB存储引擎的尊敬。
|
|
% 事务描述必须在POST请求的正文中传递。
|
|
% 如果事务已在服务器上完全执行并提交， 则将返回HTTP 200。另外，在操作中定义的代码的返回值将在result属性中返回。
|
|
% 对于成功提交的事务，返回的JSON对象具有以下属性：
|
|
% error：布尔值标志，指示是否发生错误（ 在这种情况下为false）
|
|
% code：HTTP状态码
|
|
% result：交易的返回值
|
|
% 如果缺少交易规范或格式错误，则服务器将使用HTTP 400进行响应。
|
|
% 然后，响应的主体将包含带有其他错误详细信息的JSON对象。该对象具有以下属性：
|
|
% error：布尔值标志，指示发生错误（在这种情况下为true）
|
|
% code：HTTP状态码
|
|
% errorNum：服务器错误号
|
|
% errorMessage：描述性错误消息
|
|
% 如果事务提交失败（无论是由于操作代码中引发的异常 还是内部错误），服务器都会以错误进行响应。其他任何错误都将使用返回码 HTTP 400，HTTP 409或HTTP 500返回。
|
|
% 返回码
|
|
% 200：如果事务已在服务器上完全执行并提交， 则将返回HTTP 200。
|
|
% 400：如果事务规范丢失或格式不正确，则服务器将使用HTTP 400进行响应。
|
|
% 404：如果事务规范包含未知集合，则服务器将使用HTTP 404进行响应。
|
|
% 500：用户抛出的异常将使服务器以HTTP 500的返回码进行响应
|
|
executeTransaction(PoolNameOrSocket, MapData) ->
|
|
agVstCli:callAgency(PoolNameOrSocket, ?AgPost, <<"/_api/transaction">>, ?AgDefQuery, ?AgDefHeader, eVPack:encode(MapData)).
|
|
|
|
|
|
|