From 0ca71990392b7c27c17f41c1b6ead5a6548c7d98 Mon Sep 17 00:00:00 2001 From: SisMaker <1713699517@qq.com> Date: Mon, 30 Nov 2020 19:16:14 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=9D=E5=A7=8B=E5=8C=96=E6=8F=90=E4=BA=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 23 + LICENSE | 21 + README.md | 41 ++ VelocyStream.md | 286 ++++++++ VelocyStream_zh.md | 188 ++++++ include/agHttpCli.hrl | 202 ++++++ include/erlArango.hrl | 6 + rebar.config | 8 + src/agApi/agAdminMonitor.erl | 360 ++++++++++ src/agApi/agAnalyzers.erl | 82 +++ src/agApi/agAqls.erl | 426 ++++++++++++ src/agApi/agAsyncResultHandling.erl | 140 ++++ src/agApi/agBulkImportExport.erl | 233 +++++++ src/agApi/agCluster.erl | 107 +++ src/agApi/agCollections.erl | 482 ++++++++++++++ src/agApi/agDbMgr.erl | 98 +++ src/agApi/agDocuments.erl | 500 ++++++++++++++ src/agApi/agEdges.erl | 43 ++ src/agApi/agEndPoints.erl | 43 ++ src/agApi/agFoxxServices.erl | 399 +++++++++++ src/agApi/agGeneralGraphs.erl | 961 +++++++++++++++++++++++++++ src/agApi/agHotBackup.erl | 116 ++++ src/agApi/agIndexes.erl | 413 ++++++++++++ src/agApi/agMiscFuns.erl | 241 +++++++ src/agApi/agRepairJobs.erl | 75 +++ src/agApi/agReplication.erl | 734 ++++++++++++++++++++ src/agApi/agSimpleQueries.erl | 10 + src/agApi/agTasks.erl | 92 +++ src/agApi/agTransactions.erl | 204 ++++++ src/agApi/agTraversals.erl | 13 + src/agApi/agUserMgr.erl | 240 +++++++ src/agApi/agViews.erl | 216 ++++++ src/agHttpCli/agAgencyPoolMgrExm.erl | 78 +++ src/agHttpCli/agAgencyPoolMgrIns.erl | 188 ++++++ src/agHttpCli/agAgencyPool_sup.erl | 15 + src/agHttpCli/agAgencyUtils.erl | 96 +++ src/agHttpCli/agHttpCli.erl | 278 ++++++++ src/agHttpCli/agHttpProtocol.erl | 281 ++++++++ src/agHttpCli/agKvsToBeam.erl | 45 ++ src/agHttpCli/agMiscUtils.erl | 127 ++++ src/agHttpCli/agSslAgencyExm.erl | 77 +++ src/agHttpCli/agSslAgencyIns.erl | 401 +++++++++++ src/agHttpCli/agTcpAgencyExm.erl | 77 +++ src/agHttpCli/agTcpAgencyIns.erl | 400 +++++++++++ src/agHttpCli/agVstAgencyExm.erl | 77 +++ src/agHttpCli/agVstAgencyIns.erl | 400 +++++++++++ src/agHttpCli/vst.erl | 438 ++++++++++++ src/erlArango.app.src | 11 + src/erlArango_app.erl | 11 + src/erlArango_sup.erl | 30 + src/user_default.erl | 155 +++++ start.sh | 1 + 52 files changed, 10189 insertions(+) create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 README.md create mode 100644 VelocyStream.md create mode 100644 VelocyStream_zh.md create mode 100644 include/agHttpCli.hrl create mode 100644 include/erlArango.hrl create mode 100644 rebar.config create mode 100644 src/agApi/agAdminMonitor.erl create mode 100644 src/agApi/agAnalyzers.erl create mode 100644 src/agApi/agAqls.erl create mode 100644 src/agApi/agAsyncResultHandling.erl create mode 100644 src/agApi/agBulkImportExport.erl create mode 100644 src/agApi/agCluster.erl create mode 100644 src/agApi/agCollections.erl create mode 100644 src/agApi/agDbMgr.erl create mode 100644 src/agApi/agDocuments.erl create mode 100644 src/agApi/agEdges.erl create mode 100644 src/agApi/agEndPoints.erl create mode 100644 src/agApi/agFoxxServices.erl create mode 100644 src/agApi/agGeneralGraphs.erl create mode 100644 src/agApi/agHotBackup.erl create mode 100644 src/agApi/agIndexes.erl create mode 100644 src/agApi/agMiscFuns.erl create mode 100644 src/agApi/agRepairJobs.erl create mode 100644 src/agApi/agReplication.erl create mode 100644 src/agApi/agSimpleQueries.erl create mode 100644 src/agApi/agTasks.erl create mode 100644 src/agApi/agTransactions.erl create mode 100644 src/agApi/agTraversals.erl create mode 100644 src/agApi/agUserMgr.erl create mode 100644 src/agApi/agViews.erl create mode 100644 src/agHttpCli/agAgencyPoolMgrExm.erl create mode 100644 src/agHttpCli/agAgencyPoolMgrIns.erl create mode 100644 src/agHttpCli/agAgencyPool_sup.erl create mode 100644 src/agHttpCli/agAgencyUtils.erl create mode 100644 src/agHttpCli/agHttpCli.erl create mode 100644 src/agHttpCli/agHttpProtocol.erl create mode 100644 src/agHttpCli/agKvsToBeam.erl create mode 100644 src/agHttpCli/agMiscUtils.erl create mode 100644 src/agHttpCli/agSslAgencyExm.erl create mode 100644 src/agHttpCli/agSslAgencyIns.erl create mode 100644 src/agHttpCli/agTcpAgencyExm.erl create mode 100644 src/agHttpCli/agTcpAgencyIns.erl create mode 100644 src/agHttpCli/agVstAgencyExm.erl create mode 100644 src/agHttpCli/agVstAgencyIns.erl create mode 100644 src/agHttpCli/vst.erl create mode 100644 src/erlArango.app.src create mode 100644 src/erlArango_app.erl create mode 100644 src/erlArango_sup.erl create mode 100644 src/user_default.erl create mode 100644 start.sh diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9398d4e --- /dev/null +++ b/.gitignore @@ -0,0 +1,23 @@ +.eunit +*.o +*.beam +*.plt +erl_crash.dump +.concrete/DEV_MODE +ebin + +# rebar 2.x +.rebar +rel/example_project +ebin/*.beam +deps + +# rebar 3 +.rebar3 +_build/ +_checkouts/ +rebar.lock + +# idea +.idea +*.iml \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..401d523 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2019 AICells + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..777b42e --- /dev/null +++ b/README.md @@ -0,0 +1,41 @@ +# erlArango + arangodb erlang driver + erlang otp21.2+ arangodb 3.6.2 3.7 + +# Feature + Efficient, fast and easy to use. + 1. To make this driver as efficient as possible, customizations encapsulate an HTTP1.1 client(agHttpCli) with connection pooling. + Comparisons between packaged agHttpCli and similar HTTP client tests are available:[Address](https://github.com/SisMaker/httpc_bench) + 2. This driver can use connection pooling or simply establish multiple connections in a single process (non-connection pooling mode) for various data operations. + Synchronous and asynchronous operations are supported when using connection pooling, + and you need to save the requestId extra if you want to use asynchronous operations Waiting for the received data to return, + the API encapsulated by the current driver all USES synchronous operation, and can be modified if asynchronous operation is needed. + Only synchronous operations are supported for single-process operations. + In single-process mode, compared with connection pooling mode, data replication between processes can be reduced once. + For operation of large amount of data, database connection can be established separately in data management process instead of connection pooling. + 3. The connection pooling mode and connectionless pool mode API interface ensures the identity, does not need to be treated differently, + and is easy to understand and change between connection pooling mode and connectionless pool mode. + +# Batch requests are not supported + https://www.arangodb.com/docs/stable/http/batch-request.html + +# compile + rebar get-deps; rebar compile or rebar3 compile + Note: If you build Jiffy on The Windows platform, you will need to set up an additional compilation environment. [See jiffy for details](https://github.com/SisMaker/erlUtils/tree/master/src/docs) + +# how to use + rebar: erl -pa ./ebin -pa ./deps/jiffy/ebin or + revar3: rebar3 shell + Non-connection pooling mode + Make a connection first + {ok, Socket} = agHttpCli:connect([]). %% Use default Settings + %% Then you can then call various apis using Socket as the first argument + agMgrDb:curDbInfo(Socket). + + Connection pooling mode + application:ensure_all_started(erlArango). %% start app + agHttpCli:startPool(poolName, [], []). %% start pool + %% Then you can then invoke various apis using poolName as the first argument + agMgrDb:curDbInfo(poolName). + + diff --git a/VelocyStream.md b/VelocyStream.md new file mode 100644 index 0000000..8857581 --- /dev/null +++ b/VelocyStream.md @@ -0,0 +1,286 @@ +Client / Server Communication (VST 1.1) +======================================= + +Version 1.1.0 of 23 November 2016 + +HTTP +---- + +Use VelocyPack as body. Content-Type is `"application/vpack"` + +Binary Protocol +--------------- + +This is not a request / response protocol. It is symmetric (in +principle). Messages can be sent back and forth, pipelined, multiplexed, +uni-directional or bi-directional. + +It is possible that a message generates + +- no response + +- exactly one response + +- multiple responses + +The VelocyStream does **not** impose or specify or require one of the +above behaviors. The application must define a behavior in general or on +a per-request basis, see below. The server and client must then +implement that behavior. + +### Message vs. Chunk + +The consumer (client or server) will deal with messages. A message +consists of one or more VelocyPacks (or in some cases of certain parts +of binary data). How many VelocyPacks are part of a message is +completely application dependent, see below for ArangoDB. + +It is possible that the messages are very large. As messages can be +multiplexed over one connection, large messages need to be split into +chunks. The sender/receiver class will accept a vector of VelocyPacks, +split them into chunks, send these chunks over the wire, assemble these +chunks, generates a vector of VelocyPacks and passes this to the +consumer. + +### Chunks + +In order to allow reassemble chunks, each package is prefixed by a small +header. A chunk is always at least 24 bytes long. The byte order is +ALWAYS little endian. The format of a chunk is the following, regardless +on whether it is the first in a message or a subsequent one: + + +| name | type | description | +| --------------- | ------------------------- | --- | +| length | uint32\_t | total length in bytes of the current chunk, including this header | +| chunkX | uint32\_t | chunk/isFirstChunk (upper 31bits/lowest bit), details see below | +| messageId | uint64\_t | a unique identifier, it is the responsibility of the sender to generate such an identifier (zero is reserved for not set ID) | +| messageLength | uint64\_t | the total size of the message. | +| Binary data | binary data blob | size b1 | + + +Clarification: "chunk" and "isFirstChunk" are combined into an unsigned +32bit value. Therefore it will be encoded as + + uint32_t chunkX + +and extracted as + + chunk = chunkX >> 1 + + isFirstChunk = chunkX & 0x1 + +For the first chunk of a message, the low bit of the second uint32\_t is +set, for all subsequent ones it is reset. In the first chunk of a +message, the number "chunk" is the total number of chunks in the +message, in all subsequent chunks, the number "chunk" is the current +number of this chunk. + +The total size of the data package is (24 + b1) bytes. This number is +stored in the length field. If one needs to send messages larger than +UINT32\_MAX, then these messages must be chunked. In general it is a +good idea to restrict the maximal size to a few megabytes. + +**Notes:** + +When sending a (small) message, it is important (for performance reasons) +to ensure that only one TCP +packet is sent. For example, by using sendmmsg under Linux +([*https://blog.cloudflare.com/how-to-receive-a-million-packets/*](https://blog.cloudflare.com/how-to-receive-a-million-packets/)) + +Implementors should nevertheless be aware that in TCP/IP one cannot +enforce this and so implementations must always be aware that some part +of the network stack can split packets and the payload might arrive in +multiple parts! + +ArangoDB +======== + +### Request / Response + +For an ArangoDB client, the request is of the following format, the +array is a VelocyPack array: + + [ + /* 0 - version: */ 1, // [int] + /* 1 - type: */ 1, // [int] 1=Req, 2=Res,.. + /* 2 - database: */ "test", // [string] + /* 3 - requestType: */ 1, // [int] 0=Delete, ... + /* 4 - request: */ "/_api/collection", // [string\] + /* 5 - parameter: */ { force: true }, // [[string]->[string]] + /* 6 - meta: */ { x-arangodb: true } // [[string]->[string]] + ] + + Body (binary data) + +If database is missing (entry is `null`), then "\_system" is assumed. + +`type`: + + 1 = Request + 2 = Response (final response for this message id) + 3 = Response (but at least one more response will follow) + 1000 = Authentication + +`requestType`: + + 0 = DELETE + 1 = GET + 2 = POST + 3 = PUT + 4 = HEAD (not used in VPP) + 5 = PATCH + 6 = OPTIONS (not used in VPP) + +For example: + +The HTTP request + + http://localhost:8529/_db/test/_admin/echo?a=1&b=2&c[]=1&c[]=3 + +With header: + + X-ArangoDB-Async: true + +is equivalent to + + [ + 1, // version + 1, // type + "test", // database + 1, // requestType GET + "/_admin/echo", // request path + { // parameters + a: 1, + b: 2, + c: [ 1, 3 ] + }, + { // meta + x-arangodb-async: true + } + ] + +The request is a message beginning with one VelocyPack. This VelocyPack +always contains the header fields, parameters and request path. If the +meta field does not contain a content type, then the default +`"application/vpack"` is assumed and the body will be one or multiple +VelocyPack object. + +The response will be + + [ + 1, // 0 - version + 2 or 3, // 1 - type + 400, // 2 - responseCode + { etag: "1234" } // 3 - meta: [[str]->[str]] + ] + + Body (binary data) + +Request can be pipelined or mixed. The responses are mapped using the +"messageId" in the header. It is the responsibility of the **sender** to +generate suitable "messageId" values. + +The default content-type is `"application/vpack"`. + +### Authentication + +A connection can be authenticated with the following message: + + [ + 1, // version + 1000, // type + "plain", // encryption + "admin", // user + "plaintext", // password + ] + +or + + [ + 1, // version + 1000, // type + "jwt", // encryption + "abcd..." // token + ] + +The response is + + { "error": false } + +if successful or + + { + "error": true, + "errorMessage": "MESSAGE", + "errorCode": CODE + } + +if not successful, and in this case the connection is closed by the server. +One can acquire a JWT token in the same way as with HTTP using the +open, unauthenticated route `/_open/auth` with the same semantics as +in the HTTP version. In this way, the complete authentication can be +done in a single session via JWT. + + +### Content-Type and Accept + +In general the content-type will be VPP, that is the body is an object +stored as VelocyPack. + +Sometimes it is necessary to respond with unstructured data, like text, +css or html. The body will be a VelocyPack object containing just a +binary attribute and the content-type will be set accordingly. + +The rules are as follows. + +#### Http + +Request: Content-Type + +- `"application/json"`: the body contains the JSON string representation + +- `"application/vpack"`: the body contains a velocy pack + +There are some handler that allow lists of JSON (seperared by newline). +In this case we also allow multiple velocy packs without any separator. + +Request: Accept + +- `"application/json"`: send a JSON string representation in the body, + if possible + +- `"application/vpack"`: send velocy pack in the body, if possible + +If the request asked for `"application/json"` or `"application/vpack"` and +the handler produces something else (i.e. `"application/html"`), then the +accept is ignored. + +If the request asked `"application/json"` and the handler produces +`"application/vpack"`, then the VPACK is converted into JSON. + +If the request asked `"application/vpack"` and the handler produces +"application/json", then the JSON is converted into VPACK. + +#### VPP + +Similar to HTTP with the exception: the "Accept" header is not supported +and `"application/json"` will always be converted into +"application/vpack". This means that the body contains one or more +velocy-packs. In general it will contain one - notable exception being +the import. + +If the handler produces something else (i.e. `"application/html"`), then +The body will be a binary blob (instead of a velocy-pack) and the +content-type will be set accordingly. + +The first bytes sent after a connection (the "client" side - even if the +program is bi-directional, there is a server listening to a port and a +client connecting to a port) are + + VST/1.1\r\n\r\n + +(11 Bytes) + + + diff --git a/VelocyStream_zh.md b/VelocyStream_zh.md new file mode 100644 index 0000000..b703a48 --- /dev/null +++ b/VelocyStream_zh.md @@ -0,0 +1,188 @@ +Client / Server Communication (VST 1.1) +======================================= + +Version 1.1.0 of 23 November 2016 + +# HTTP + 使用VelocyPack作为身体。内容类型为"application/vpack" + +Binary Protocol +--------------- + 这不是请求/响应协议。它是对称的（原则上）。消息可以来回发送，流水线，多路复用，单向或双向。 + 可能会生成一条消息 + 没有反应 + 只是一个回应 + 多重回应 + + 该VelocyStream并没有强加或指定或要求上述行为之一。 + 应用程序必须在一般情况下或根据每个请求定义行为， + 请参见下文。然后，服务器和客户端必须实现该行为。 + +### Message vs. Chunk + 使用者（客户端或服务器）将处理消息。一条消息包含一个或多个VelocyPack（在某些情况下是二进制数据的某些部分）。 + 消息中有多少VelocyPacks完全取决于应用程序，请参阅下文了解ArangoDB。 + + 消息可能很大。由于可以通过一个连接对消息进行多路复用，因此需要将大消息拆分为多个块。 + 发送者/接收者类将接受一个VelocyPacks向量，将其分割成块，通过导线发送这些块，组装这些块， + 生成一个VelocyPacks向量并将其传递给消费者。 + +### Chunks + 为了允许重组块，每个程序包都以一个 header 作为前缀。块始终至少为24个字节长。字节顺序始终是小端。 + 块的格式如下，无论它是消息中的第一个消息还是随后的消息： + + 名称 类型 描述 + length uint32_t 当前块（包括此标头）的总长度（以字节为单位） + chunkX uint32_t chunk / isFirstChunk（高31位/最低位），详细信息请参见下文 + messageId uint64_t 唯一标识符，发送方有责任生成这样的标识符（zero is reserved for not set ID） + messageLength uint64_t the total size of the message. + Binary data binary data blob size b1 | + + 声明："chunk" and "isFirstChunk" are combined into an unsigned 32bit value. + Therefore it will be encoded as + uint32_t chunkX and extracted as + + chunk = chunkX >> 1 + isFirstChunk = chunkX & 0x1 + + 对于消息的第一块，设置第二个uint32_t的低位，对于所有后续消息，将其复位。 + 在消息的第一个块中，数字 chunk 是消息中的块总数，在所有后续块中，数字 chunk 是该块的当前number。 + + 数据包的总大小为（24 + b1）字节。此数字存储在length字段中。 + 如果需要发送大于UINT32_MAX的消息，则必须将这些消息分块。通常，最好将最大大小限制为几兆字节。 + +### **Notes:** + 发送（小）消息时，（出于性能原因）确保仅发送一个TCP数据包非常重要。 + 例如，通过在Linux下使用sendmmsg + ([https://blog.cloudflare.com/how-to-receive-a-million-packets](https://blog.cloudflare.com/how-to-receive-a-million-packets/)) + 但是，实现者应该意识到，在TCP / IP中不能强制执行此操作，因此实现者必须始终意识到， + 网络堆栈的某些部分可以拆分数据包，并且有效负载可能分成多个部分！ + +ArangoDB +======== +### Request / Response + 对于ArangoDB客户端，请求的格式如下，该数组是VelocyPack数组： + [ + /* 0 - version: */ 1, // [int] + /* 1 - type: */ 1, // [int] 1=Req, 2=Res,.. + /* 2 - database: */ "test", // [string] + /* 3 - requestType: */ 1, // [int] 0=Delete, ... + /* 4 - request: */ "/_api/collection", // [string\] + /* 5 - parameter: */ { force: true }, // [[string]->[string]] http的请求参数列表 + /* 6 - meta: */ { x-arangodb: true } // [[string]->[string]] http的header + ] + Body (binary data) + + 如果数据库未设置（entry is `null`），则数据库为“ _system”。 + +#### type： + 1 = Request + 2 = Response (final response for this message id) + 3 = Response (but at least one more response will follow) + 1000 = Authentication +#### requestType： + 0 = DELETE + 1 = GET + 2 = POST + 3 = PUT + 4 = HEAD (not used in VPP) + 5 = PATCH + 6 = OPTIONS (not used in VPP) + +### For example: + HTTP请求 + http://localhost:8529/_db/test/_admin/echo?a=1&b=2&c[]=1&c[]=3 + With header:： + X-ArangoDB-Async: true + is equivalent to + [ + 1, // version + 1, // type + "test", // database + 1, // requestType GET + "/_admin/echo", // request path + { // parameters + a: 1, + b: 2, + c: [ 1, 3 ] + }, + { // meta + x-arangodb-async: true + } + ] + + 该请求是一条以VelocyPack开头的消息。这个VelocyPack始终包含标题字段，参数和请求路径。 + 如果meta字段不包含内容类型，则采用默认值 "application/vpack"，并且正文将是一个或多个VelocyPack对象。 + +#### The response will be + [ + 1, // 0 - version + 2 or 3, // 1 - type + 400, // 2 - responseCode + { etag: "1234" } // 3 - meta: [[str]->[str]] + ] + +#### Body (binary data) + 请求可以通过管道传输或混合。使用标头中的“ messageId”映射响应。发送者有责任生成合适的“ messageId”值。 + + 默认内容类型为"application/vpack"。 + +### Authentication + A connection can be authenticated with the following message: + [ + 1, // version + 1000, // type + "plain", // encryption + "admin", // user + "plaintext", // password + ] + or + [ + 1, // version + 1000, // type + "jwt", // encryption + "abcd..." // token + ] + The response is + { "error": false } + + if successful or + { + "error": true, + "errorMessage": "MESSAGE", + "errorCode": CODE + } + + 如果不成功，则在这种情况下服务器将关闭连接。可以使用/_open/auth与HTTP版本相同的语义，使用未经身份验证的开放式路由，以与HTTP相同的方式获取JWT令牌。这样，可以通过JWT在单个会话中完成完整的身份验证。 + +### Content-Type and Accept + 通常，内容类型将是VPP，即主体是存储为VelocyPack的对象。 + 有时有必要使用非结构化数据（例如文本，css或html）进行响应。主体将是一个仅包含二进制属性的VelocyPack对象，并将相应地设置content-type。 + +规则如下。 + +#### Http + Request: Content-Type + "application/json"`: the body contains the JSON string representation + `"application/vpack"`: the body contains a velocy pack + + 有一些处理程序允许JSON列表（由换行符分隔）。在这种情况下，我们还允许不使用任何分隔符的多个速度包。 + + Request: Accept + "application/json"：如果可能，在正文中发送JSON字符串表示形式 + "application/vpack"：如果可能的话，在体内发送速度包 + + 如果请求是"application/json"或"application/vpack"处理程序产生了其他请求（即"application/html"），那么将忽略接受。 + + 如果请求被请求"application/json"并且处理程序产生 "application/vpack"，则VPACK将转换为JSON。 + + 如果请求被请求"application/vpack"，并且处理程序生成“ application / json”，则JSON将转换为VPACK。 + +#### VPP + 与HTTP相似，不同之处在于：不支持“ Accept”标头，并且"application/json"始终将其转换为“ application / vpack”。这意味着主体包含一个或多个速度包。通常，它将包含一个-值得注意的例外是导入。 + + 如果处理程序产生了其他东西（即"application/html"），则主体将是一个二进制blob（而不是一个velocy-pack），并且将相应地设置content-type。 + + 连接后发送的第一个字节（“客户端”端-即使程序是双向的，也有服务器在监听端口，而客户端在连接端口） + + VST/1.1\r\n\r\n +(11 Bytes) \ No newline at end of file diff --git a/include/agHttpCli.hrl b/include/agHttpCli.hrl new file mode 100644 index 0000000..a638e17 --- /dev/null +++ b/include/agHttpCli.hrl @@ -0,0 +1,202 @@ +%% agency 管理进程的名称 +-define(agAgencyPoolMgr, agAgencyPoolMgr). + +%% beam cache 模块名 +-define(agBeamPool, agBeamPool). +-define(agBeamAgency, agBeamAgency). + +%% 默认选项定义 +-define(DEFAULT_BASE_URL, <<"http://127.0.0.1:8529">>). +-define(DEFAULT_DBNAME, <<"_system">>). +-define(DEFAULT_USER, <<"root">>). +-define(DEFAULT_PASSWORD, <<"156736">>). +-define(DEFAULT_BACKLOG_SIZE, 1024). +-define(DEFAULT_CONNECT_TIMEOUT, 5000). +-define(DEFAULT_POOL_SIZE, 16). +-define(DEFAULT_IS_RECONNECT, true). +-define(DEFAULT_RECONNECT_MIN, 500). +-define(DEFAULT_RECONNECT_MAX, 120000). +-define(DEFAULT_TIMEOUT, infinity). +-define(DEFAULT_PID, self()). +-define(DEFAULT_SOCKET_OPTS, [binary, {active, true}, {nodelay, true}, {delay_send, true}, {keepalive, true}, {recbuf, 1048576}, {send_timeout, 5000}, {send_timeout_close, true}]). + +-define(GET_FROM_LIST(Key, List), agMiscUtils:getListValue(Key, List, undefined)). +-define(GET_FROM_LIST(Key, List, Default), agMiscUtils:getListValue(Key, List, Default)). +-define(WARN(Tag, Format, Data), agMiscUtils:warnMsg(Tag, Format, Data)). + +-define(miDoNetConnect, miDoNetConnect). + +-record(miRequest, { + method :: method() + , path :: path() + , headers :: headers() + , body :: body() + , requestId :: tuple() + , fromPid :: pid() + , overTime = infinity :: timeout() + , isSystem = false :: boolean() +}). + +-record(miRequestRet, { + requestId :: requestId(), + reply :: term() +}). + +-record(reconnectState, { + min :: non_neg_integer(), + max :: non_neg_integer() | infinity, + current :: non_neg_integer() | undefined +}). + +-record(srvState, { + poolName :: poolName(), + serverName :: serverName(), + userPassWord :: binary(), + host :: binary(), + dbName :: binary(), + rn :: binary:cp(), + rnrn :: binary:cp(), + reconnectState :: undefined | reconnectState(), + socket :: undefined | ssl:sslsocket(), + timerRef :: undefined | reference() +}). + +-record(recvState, { + stage = header :: header | body | done, %% 一个请求收到http(底层是tcp)回复可能会有多个包 最多分三个阶接收 + contentLength :: undefined | non_neg_integer() | chunked, + statusCode :: undefined | 100..505, + headers :: undefined | [binary()], + buffer = <<>> :: binary(), + body = <<>> :: binary() +}). + +-record(cliState, { + isHeadMethod = false :: boolean(), %% 是否是<<"HEAD">>请求方法 + %method = undefined :: undefined | method(), + requestsIns = [] :: list(), + requestsOuts = [] :: list(), + backlogNum = 0 :: integer(), + backlogSize = 0 :: integer(), + status = leisure :: waiting | leisure, + curInfo = undefined :: tuple(), + recvState = undefined :: recvState() | undefined +}). + +-record(dbOpts, { + host :: host(), + port :: 0..65535, + hostname :: hostName(), + dbName :: binary(), + protocol :: protocol(), + poolSize :: poolSize(), + userPassword :: binary(), + socketOpts :: socketOpts() +}). + +-record(agencyOpts, { + reconnect :: boolean(), + backlogSize :: backlogSize(), + reconnectTimeMin :: pos_integer(), + reconnectTimeMax :: pos_integer() +}). + +-type miRequest() :: #miRequest{}. +-type miRequestRet() :: #miRequestRet{}. +-type recvState() :: #recvState{}. +-type srvState() :: #srvState{}. +-type cliState() :: #cliState{}. +-type reconnectState() :: #reconnectState{}. + +-type poolName() :: atom(). +-type poolNameOrSocket() :: atom() | socket(). +-type serverName() :: atom(). +-type protocol() :: ssl | tcp. +-type method() :: binary(). +-type headers() :: [{iodata(), iodata()}]. +-type body() :: iodata() | undefined. +-type path() :: binary(). +-type host() :: binary(). +-type hostName() :: string(). +-type poolSize() :: pos_integer(). +-type backlogSize() :: pos_integer() | infinity. +-type requestId() :: {serverName(), reference()}. +-type socket() :: inet:socket() | ssl:sslsocket(). +-type socketOpts() :: [gen_tcp:connect_option() | ssl:tls_client_option()]. +-type error() :: {error, term()}. + +-type dbCfg() :: + {baseUrl, binary()} | + {dbName, binary()} | + {user, binary()} | + {password, binary()} | + {poolSize, poolSize()} | + {socketOpts, socketOpts()}. + +-type agencyCfg() :: + {reconnect, boolean()} | + {backlogSize, backlogSize()} | + {reconnectTimeMin, pos_integer()} | + {reconnectTimeMax, pos_integer()}. + +-type dbCfgs() :: [dbCfg()]. +-type dbOpts() :: #dbOpts{}. +-type agencyCfgs() :: [agencyCfg()]. +-type agencyOpts() :: #agencyOpts{}. + +%% http header 头 +%% -type header() :: +%% 'Cache-Control' | +%% 'Connection' | +%% 'Date' | +%% 'Pragma'| +%% 'Transfer-Encoding' | +%% 'Upgrade' | +%% 'Via' | +%% 'Accept' | +%% 'Accept-Charset'| +%% 'Accept-Encoding' | +%% 'Accept-Language' | +%% 'Authorization' | +%% 'From' | +%% 'Host' | +%% 'If-Modified-Since' | +%% 'If-Match' | +%% 'If-None-Match' | +%% 'If-Range'| +%% 'If-Unmodified-Since' | +%% 'Max-Forwards' | +%% 'Proxy-Authorization' | +%% 'Range'| +%% 'Referer' | +%% 'User-Agent' | +%% 'Age' | +%% 'Location' | +%% 'Proxy-Authenticate'| +%% 'Public' | +%% 'Retry-After' | +%% 'Server' | +%% 'Vary' | +%% 'Warning'| +%% 'Www-Authenticate' | +%% 'Allow' | +%% 'Content-Base' | +%% 'Content-Encoding'| +%% 'Content-Language' | +%% 'Content-Length' | +%% 'Content-Location'| +%% 'Content-Md5' | +%% 'Content-Range' | +%% 'Content-Type' | +%% 'Etag'| +%% 'Expires' | +%% 'Last-Modified' | +%% 'Accept-Ranges' | +%% 'Set-Cookie'| +%% 'Set-Cookie2' | +%% 'X-Forwarded-For' | +%% 'Cookie' | +%% 'Keep-Alive' | +%% 'Proxy-Connection' | +%% binary() | +%% string(). + diff --git a/include/erlArango.hrl b/include/erlArango.hrl new file mode 100644 index 0000000..cdfb0e4 --- /dev/null +++ b/include/erlArango.hrl @@ -0,0 +1,6 @@ +-define(AgGet, <<"GET ">>). +-define(AgPut, <<"PUT ">>). +-define(AgPost, <<"POST ">>). +-define(AgHead, <<"HEAD ">>). +-define(AgPatch, <<"PATCH ">>). +-define(AgDelete, <<"DELETE ">>). \ No newline at end of file diff --git a/rebar.config b/rebar.config new file mode 100644 index 0000000..ad795f0 --- /dev/null +++ b/rebar.config @@ -0,0 +1,8 @@ +{erl_opts, [{i, "include"}]}. +{edoc_opts, [{preprocess, true}]}. +{deps, [ + {eVPack, {git, "http://192.168.0.88:53000/SisMaker/eVPack.git", {branch, master}}}, + {jiffy, {git, "https://github.com/davisp/jiffy.git", {tag, "1.0.5"}}} + %% {jsx, {git, "https://github.com/talentdeficit/jsx.git", {tag, "v3.0.0"}}} +]}. + diff --git a/src/agApi/agAdminMonitor.erl b/src/agApi/agAdminMonitor.erl new file mode 100644 index 0000000..d80ed88 --- /dev/null +++ b/src/agApi/agAdminMonitor.erl @@ -0,0 +1,360 @@ +-module(agAdminMonitor). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/administration-and-monitoring.html + +% 从服务器Permalink读取全局日志 +% 返回服务器日志 +% GET /_admin/log +% 查询参数 +% upto （可选）：返回所有日志条目多达日志级别高达。请注意，upto必须为： +% fatal 或0 +% error或1 +% warning或2 +% info或3 +% debug 或4 默认值为info。 +% level （可选）：返回日志级别的所有日志条目级别。请注意，查询参数 upto和level是互斥的。 +% start（可选）：返回所有日志条目，以使其日志条目标识符（lid值）大于或等于start。 +% size（可选）：将结果限制为最大大小的日志条目。 +% offset（可选）：开始返回日志条目，跳过第一个偏移日志条目。偏移量 和大小可用于分页。 +% search （可选）：仅返回包含search中指定的文本的日志条目。 +% sort（可选）：根据日志条目的盖值对日志条目进行升序（如果sort为asc）或降序（如果sort为desc）。请注意，盖子会 按时间顺序排列。默认值为asc。 +% 从服务器的全局日志中返回致命，错误，警告或信息日志消息。结果是具有以下属性的JSON对象： +% HTTP 200 +% lid：日志条目标识符的列表。每个日志消息都由其@LIT {lid}唯一标识，并且标识符按升序排列。 +% level：所有日志条目的日志级别列表。 +% timestamp：所有日志条目的时间戳列表，自1970-01-01开始以秒为单位。 +% text：所有日志条目的文本列表 +% topic：所有日志条目的主题列表 +% totalAmount：分页前的日志条目总数。 +% 400：如果为up或level指定了无效值，则返回。 +% 500：如果服务器由于内存不足错误而无法生成结果，则返回。 +getAdminLog(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/log">>, [], undefined). + +getAdminLog(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_admin/log", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 返回当前的日志级别设置 +% GET /_admin/log/level +% 返回服务器的当前日志级别设置。结果是一个JSON对象，其日志主题为对象键，日志级别为对象值。 +% 返回码 +% 200：如果请求有效，则返回 +% 500：如果服务器由于内存不足错误而无法生成结果，则返回。 +getAdminLogLevel(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/log/level">>, [], undefined). + +% 修改当前的日志级别设置 +% PUT /_admin/log/level +% 具有以下属性的JSON对象是必需的： +% agency：可能的日志级别之一。 +% agencycomm：可能的日志级别之一。 +% authentication：可能的日志级别之一。 +% 授权：可能的日志级别之一。 +% cache：可能的日志级别之一。 +% cluster：可能的日志级别之一。 +% collector：可能的日志级别之一。 +% 通信：可能的日志级别之一。 +% 压缩器：可能的日志级别之一。 +% config：可能的日志级别之一。 +% datafiles：可能的日志级别之一。 +% 开发：可能的日志级别之一。 +% 引擎：可能的日志级别之一。 +% general：可能的日志级别之一。 +% graphs：可能的日志级别之一。 +% 心跳：可能的日志级别之一。 +% 内存：可能的日志级别之一。 +% mmap：可能的日志级别之一。 +% 性能：可能的日志级别之一。 +% pregel：可能的对数水平之一。 +% 查询：可能的日志级别之一。 +% 复制：可能的日志级别之一。 +% 请求：可能的日志级别之一。 +% rocksdb：可能的日志级别之一。 +% ssl：可能的日志级别之一。 +% startup：可能的日志级别之一。 +% 监视：可能的日志级别之一。 +% syscall：可能的日志级别之一。 +% 线程：可能的日志级别之一。 +% trx：可能的日志级别之一。 +% v8：可能的日志级别之一。 +% views：可能的日志级别之一。 +% ldap：可能的日志级别之一。 +% audit-authentication：可能的日志级别之一。 +% audit-authorization：可能的日志级别之一。 +% audit-database：可能的日志级别之一。 +% audit-collection：可能的日志级别之一。 +% audit-view：可能的日志级别之一。 +% audit-document：可能的日志级别之一。 +% audit-service：可能的日志级别之一。 +% 修改并返回服务器的当前日志级别设置。请求主体必须是JSON对象，日志主题为对象键，日志级别为对象值。 +% 结果是一个JSON对象，其中调整后的日志主题为对象键，调整后的日志级别为对象值。 +% 它可以通过仅将日志级别指定为字符串而不设置json来设置所有功能的日志级别。 +% 可能的日志级别为： +% 致命-这是没有办法的。此消息后，ArangoDB将关闭。 +% 错误-这是一个错误。您应该调查并修复它。它可能会损害您的生产。 +% 警告-这可能是严重的应用程序明智的选择，但我们不知道。 +% 信息-发生了什么事，请注意，但没有发生任何戏剧事件。 +% 调试-输出调试消息 +% 跟踪-跟踪-准备要淹没的日志-请勿在生产中使用。 +% 返回码 +% 200：如果请求有效，则返回 +% 400：当请求正文包含无效JSON时返回。 +% 405：使用无效的HTTP方法时返回。 +% 500：如果服务器由于内存不足错误而无法生成结果，则返回。 +modifyAdminLogLevel(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, <<"/_admin/log/level">>, [], BodyStr). + +% 返回统计信息 +% GET /_admin/statistics +% 返回统计信息。返回的对象包含根据_admin / statistics-description返回的描述分组在一起的 统计数字。例如， 要从组系统访问图userTime，您首先选择描述存储在系统中的组的子对象，然后在该子对象中，userTime的值存储在同名属性中。 +% 如果是分发，则返回的对象包含以count为单位的总计 数和以counts为单位的分发列表。各个值的总和（或全部）中被返回总和。 +% 事务统计信息显示本地已启动，已提交和已中止的事务，以及为查询的服务器完成的中间提交。对于RocksDB存储引擎，中间提交计数将仅采用非零值。协调器几乎不会在其本地数据库中进行任何本地事务，因此，群集事务（在协调器上启动的事务需要DBServer在事务提交到群集范围之前完成）才被添加到其本地统计信息中。这意味着您将在单个服务器上看到的统计信息大致是在使用单个协调器查询该协调器的群集设置中所期望的统计信息。区别在于群集事务没有中间提交的概念，也不会增加价值。 +% HTTP 200统计信息已成功返回。 +% error：布尔值标志，指示是否发生错误（在这种情况下为false） +% code：HTTP状态码-在这种情况下为200 +% time：当前服务器时间戳 +% errorMessage：描述性错误消息 +% enabled：如果服务器启用了统计模块，则为true。如果没有，不要期望任何值。 +% 系统：从系统收集的有关此过程的指标；可能取决于主机操作系统 +% minorPageFaults：pagefaults +% majorPageFaults：pagefaults +% userTime：服务器进程使用的用户CPU时间 +% systemTime：服务器进程使用的系统CPU时间 +% numberOfThreads：服务器中的线程数 +% residentSize：流程的RSS +% residentSizePercent：进程的RSS，以％为单位 +% virtualSize：进程的VSS +% client：有关连接的客户端及其资源使用情况的信息 +% sum：所有计数的汇总值 +% count：汇总的值数 +% counts：包含值的数组 +% connectionTime：总连接时间 +% totalTime：系统时间 +% requestTime：请求时间 +% queueTime：请求排队等待处理的时间 +% ioTime：IO时间 +% bytesSent：发送给客户端的字节数 +% bytesReceived：从客户端收到的字节数 +% httpConnections：打开的http连接数 +% http：动词的请求数 +% requestsTotal：http请求总数 +% requestsAsync：异步http请求的总数 +% RequestsGet：使用GET动词的请求数 +% requestHead：使用HEAD动词的请求数 +% requestPost：使用POST动词的请求数 +% requestsPut：使用PUT动词的请求数 +% requestsPatch：使用PATCH动词的请求数 +% requestsDelete：使用DELETE动词的请求数 +% requestsOptions：使用OPTIONS动词的请求数 +% requestOther：没有使用以上识别的动词的任何请求 +% 服务器：服务器的统计信息 +% 正常运行时间：服务器启动和运行的时间 +% physicalMemory：服务器上的可用物理内存 +% Transactions：交易统计 +% 已开始：已开始交易的数量 +% 已提交：已提交交易的数量 +% 已中止：已中止交易的数量 +% middleCommits：完成的中间提交数 +% v8Context：有关V8 JavaScript上下文的统计信息 +% 可用：当前生成的V8上下文的数量 +% busy：当前活动的V8上下文的数量 +% dirty：先前使用的上下文数量，现在应该在重新使用之前对其进行垃圾回收 +% free：可以免费使用的V8上下文的数量 +% max：我们可以通过--javascript.v8-contexts配置生成的V8上下文总数 +% 内存：V8内存/垃圾回收水印列表；每次运行垃圾回收时都要刷新；将当时使用的最小/最大内存保留10秒钟 +% contextId：这组内存统计信息来自的上下文的ID +% tMax：10秒间隔开始的时间戳 +% countOfTimes：这10秒内垃圾回收运行了多少次 +% heapMax：所有垃圾收集的高水位标记在10秒内运行 +% heapMin：这10秒内运行的所有垃圾回收的低水印 +% 线程：有关服务器工作线程的统计信息（不包括特定于V8或jemalloc的线程和系统线程） +% scheduler-threads：产生的工作线程数 +% 进行中：当前繁忙的工作线程数 +% 排队：排队等待工作线程可用的作业数 +getAdminProps(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/statistics">>, [], undefined). + +% 统计数据说明 +% 获取统计信息的描述性信息 +% GET /_admin/statistics-description +% 返回/ _admin / statistics返回的统计信息的描述。返回的对象在属性组中包含一组统计信息组，在属性图中包含一组统计信息 图。 +% 统计组由 +% group：组的标识符。 +% name：组的名称。 +% description：组的描述。 +% 统计数字由 +% group：此图所属的组的标识符。 +% 标识符：图形的标识符。它在组中是唯一的。 +% name：图形名称。 +% description：对图形的描述。 +% 类型：当前，累计或分配。 +% cuts：分布向量。 +% 单位：测量数字的单位。 +% HTTP 200描述已成功返回。 +% 组：统计组 +% group：组的标识符。 +% name：组的名称。 +% description：组的描述。 +% 数字：统计数字 +% group：此图所属的组的标识符。 +% 标识符：图形的标识符。它在组中是唯一的。 +% name：图形名称。 +% description：对图形的描述。 +% 类型：当前，累计或分配。 +% cuts：分布向量。 +% 单位：测量数字的单位。 +% code：HTTP状态码 +% 错误：错误，在这种情况下为false +getAdminStatisticsDesc(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/statistics-description">>, [], undefined). + +% TLS 永久链接 +% 返回TLS数据的摘要 +% 返回此服务器的TLS数据（服务器密钥，客户端身份验证CA） +% GET /_admin/server/tls +% 返回TLS数据的摘要。JSON响应将包含result具有以下组件的字段 ： +% keyfile：有关密钥文件的信息。 +% clientCA：有关用于客户端证书验证的CA的信息。 +% 如果使用服务器名称指示（SNI），并且为不同的服务器名称配置了多个密钥文件，那么将存在一个附加属性SNI，该属性为每个配置的服务器名称包含有关该服务器名称的密钥文件的相应信息。 +% +% 在所有情况下，该属性的值都将是一个JSON对象，该对象具有以下属性的子集（无论适当）： +% SHA256：该值是一个带有整个输入文件的SHA256的字符串。 +% certificates：值是一个JSON数组，文件链中包含公共证书。 +% privateKeySHA256：如果存在私钥（keyfile 但没有私钥clientCA），则此字段存在并且包含带有私钥SHA256的JSON字符串。 +% 这是一个公共API，因此它不要求身份验证。 +% 返回码 +% 200：如果一切正常，此API将返回HTTP 200 +getAdminTLS(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/server/tls">>, [], undefined). + +% 触发TLS数据的重新加载并返回摘要永久链接 +% 触发此服务器的TLS数据（服务器密钥，客户端身份验证CA）的重新加载，并以摘要形式返回新数据。 +% POST /_admin/server/tls +% 此API调用触发所有TLS数据的重新加载，然后返回摘要。JSON响应与相应的GET请求完全相同（请参见此处）。 +% 这是受保护的API，只能以超级用户权限执行。 +% 返回码 +% 200：如果一切正常，此API将返回HTTP 200 +% 403：如果未使用超级用户权限调用此API，它将返回HTTP 403 FORBIDDEN。 +triggerAdminTLS(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, <<"/_admin/server/tls">>, [], undefined). + +% 返回当前实例指标 +% GET /_admin/metrics +% 以Prometheus格式返回实例的当前指标。返回的文档收集所有实例指标，这些指标在任何给定时间进行测量，并将其公开以供Prometheus收集。 +% 该文档包含不同的度量标准和度量标准组，具体取决于查询实例的角色。所有导出的指标都使用arangodb_或rocksdb_字符串发布，以将其与其他收集的数据区分开。 +% 然后需要将API添加到Prometheus配置文件中进行收集。 +% 返回码 +% 200：指标已成功返回。 +% 404：可以使用--server.export-metrics-api false 服务器中的设置禁用指标API 。在这种情况下，调用结果表明找不到该API。 +getAdminMetrics(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/metrics">>, [], undefined). + + +% 集群 +% 服务器返回是否是在只读模式 +% 返回此服务器的模式（只读或默认） +% GET /_admin/server/mode +% 关于服务器的返回模式信息。json响应将包含一个mode值为readonly或的字段default。在只读服务器中，所有写入操作将失败，错误代码为1004（ERROR_READ_ONLY）。创建或删除数据库和集合也将失败，并显示错误代码11（ERROR_FORBIDDEN）。 +% 这是一个公共API，因此它不要求身份验证。 +% 返回码 +% 200：如果一切正常，此API将返回HTTP 200 +getAdminServerMode(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/server/mode">>, [], undefined). + +% 返回集群永久链接中服务器的ID +% 了解服务器的内部ID +% GET /_admin/server/id +% 返回集群中服务器的ID。如果服务器未在集群模式下运行，则请求将失败。 +% 返回码 +% 200：当服务器以群集模式运行时返回。 +% 500：当服务器未在群集模式下运行时返回。 +getAdminServerId(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/server/id">>, [], undefined). + +% 返回集群中服务器的角色 +% GET /_admin/server/role +% 返回集群中服务器的角色。该角色在结果的role属性中返回。角色的可能返回值是： +% SINGLE：服务器是没有集群的独立服务器 +% 协调器：服务器是集群中的协调器 +% PRIMARY：服务器是集群中的DBServer +% 次要的：不再使用此角色 +% 代理：服务器是集群中的代理节点 +% UNDEFINED：在集群中，如果无法确定服务器角色，则返回UNDEFINED。 +% 在所有情况下均返回HTTP 200。 +% 错误：始终为假 +% code：HTTP状态码，始终为200 +% errorNum：服务器错误号 +% 作用：之一[ SINGLE，协调员，PRIMARY，SECONDARY，AGENT，UNDEFINED ] +getAdminServerRole(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/server/role">>, [], undefined). + + +% 返回服务器是否可用 +% GET /_admin/server/availability +% 返回有关服务器的可用性信息。 +% 这是一个公共API，因此它不要求身份验证。它仅在服务器监视的上下文中使用。 +% 返回码 +% 200：如果服务器已启动并且正在运行并且可用于任意操作，并且未设置为只读模式，并且在活动故障转移设置的情况下当前不是关注者，则此API将返回HTTP 200。 +% 503：如果服务器在启动或关闭过程中，设置为只读模式或当前在活动故障转移设置中为关注者，则将返回HTTP 503。 +getAdminServerAvailability(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/server/availability">>, [], undefined). + +% DBserver 永久链接的查询统计信息 +% 允许查询集群中数据库服务器的统计信息 +% GET /_admin/clusterStatistics +% 查询参数 +% DBserver（必填）：查询给定DBserver的统计信息 +% 返回码 +% 200： +% 400：数据库服务器的ID +% 403： +getAdminClusterProps(PoolNameOrSocket, DBserver) -> + Path = <<"/_admin/clusterStatistics?DBserver=", (agMiscUtils:toBinary(DBserver))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 查询集群的运行状况以监视Permalink +% 返回由监督（机构）评估的集群的运行状况 +% GET /_admin/cluster/health +% 查询群集的运行状况以进行监视。该响应是一个JSON对象，包含标准code，error，errorNum，和errorMessage字段适当。特定于端点的字段如下： +% ClusterId：标识集群的UUID字符串 +% Health：一个对象，该对象包含群集中每个节点的描述性子对象。 +% ：中的每个条目Health将由节点ID键入，并包含以下属性： +% Endpoint：代表服务器网络端点的字符串。 +% Role：服务器扮演的角色。可能的值是"AGENT"，"COORDINATOR"和"DBSERVER"。 +% CanBeDeleted：布尔值，表示是否可以安全地从群集中删除节点。 +% Version：该节点使用的ArangoDB的版本字符串。 +% Engine：该节点使用的存储引擎。 +% Status：一个字符串，指示由监督（机构）评估的节点的运行状况。对于协调器和dbservers节点运行状况，应将其视为真实的主要来源。如果节点正常响应请求，则为"GOOD"。如果错过了一个心跳，那就是"BAD"。如果在缺少心跳约15秒钟后通过监督宣布它失败，则会对其进行标记"FAILED"。 +% 此外，它还将具有以下属性： +% 协调器和数据库服务器 +% SyncStatus：节点上次报告的同步状态。该值主要用于确定的值Status。可能的值包括"UNKNOWN"，"UNDEFINED"，"STARTUP"，"STOPPING"，"STOPPED"，"SERVING"，"SHUTDOWN"。 +% LastAckedTime：ISO 8601时间戳记，指定接收到的最后一个心跳。 +% ShortName：代表服务器的简称的字符串，例如"Coordinator0001"。 +% Timestamp：ISO 8601时间戳记，指定接收到的最后一个心跳。（已弃用） +% Host：可选字符串，指定主机（如果已知）。 +% 仅协调员 +% AdvertisedEndpoint：表示已播报端点的字符串（如果已设置）。（例如，外部IP地址或负载平衡器，可选） +% 代理商 +% Leader：此节点视为领导者的代理的ID。 +% Leading：此代理程序是否是领导者（true）或不是（false）。 +% LastAckedTime：自上次以来的时间（acked以秒为单位）。 +% 返回码 +% 200： +getAdminClusterHealth(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/cluster/health">>, [], undefined). + +% 重新加载路由表。 +% POST /_admin/routing/reload +% 从集合路由中重新加载路由信息。 +% 返回码 +% 200：路由信息重新加载成功 +reloadAdminRouting(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, <<"/_admin/routing/reload">>, [], undefined). diff --git a/src/agApi/agAnalyzers.erl b/src/agApi/agAnalyzers.erl new file mode 100644 index 0000000..6b6271c --- /dev/null +++ b/src/agApi/agAnalyzers.erl @@ -0,0 +1,82 @@ +-module(agAnalyzers). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/analyzers.html + +% 分析仪的HTTP接口 +% 可通过/_api/analyzer端点访问用于管理ArangoSearch Analyzer的RESTful API 。 +% 有关简介以及可用的类型，属性和功能，请参见分析器的描述。 + +% 根据提供的定义创建一个新的分析器 +% POST /_api/analyzer +% 具有以下属性的JSON对象是必需的： +% name：分析器名称。 +% type：分析器类型。 +% properties：用于配置指定分析器类型的属性。 +% features：在分析器生成的字段上设置的一组功能。默认值为空数组。 +% 根据提供的配置创建一个新的分析器。 +% 返回码 +% 200：名称和定义匹配的分析器已存在。 +% 201：成功创建了新的分析器定义。 +% 400：缺少一个或多个必需参数，或者一个或多个参数无效。 +% 403：用户无权使用此配置创建和分析器。 +newAnalyzer(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, <<"/_api/analyzer">>, [], BodyStr). + +% 返回分析器定义 +% GET /_api/analyzer/{analyzer-name} +% 路径参数 +% Analyzer-name（必填）：要检索的分析器的名称。 +% 检索指定分析器名称的完整定义。结果对象包含以下属性： +% name：分析器名称 +% type：分析仪类型 +% properties：用于配置指定类型的属性 +% features：在分析器生成的字段上设置的功能集 +% 返回码 +% 200：分析器定义已成功检索。 +% 404：不存在这种分析器配置。 +getAnalyzer(PoolNameOrSocket, AnalyzerName) -> + Path = <<"/_api/analyzer/", AnalyzerName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 返回可用的分析器定义列表 +% GET /_api/analyzer +% 检索所有分析器定义的数组。结果数组包含具有以下属性的对象： +% name：分析器名称 +% type：分析仪类型 +% properties：用于配置指定类型的属性 +% features：在分析器生成的字段上设置的功能集 +% 返回码 +% 200：分析器定义已成功检索。 +getAnalyzerList(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/analyzer">>, [], undefined). + +% 删除分析仪配置 +% DELETE /_api/analyzer/{analyzer-name} +% 路径参数 +% Analyzer-name（必填）：要删除的分析器的名称。 +% 查询参数 +% force （可选）：即使正在使用分析仪配置，也应将其删除。默认值为false。 +% 删除由analyzer-name标识的Analyzer配置。 +% 如果成功删除了分析器定义，将返回具有以下属性的对象： +% 错误：假 +% name：删除的分析器的名称 +% 返回码 +% 200：分析仪配置已成功删除。 +% 400：未提供分析器名称，或其他请求参数无效。 +% 403：用户无权删除此分析器配置。 +% 404：不存在这种分析器配置。 +% 409：指定的分析器配置仍在使用中，并且省略了强制或 指定了错误。。 +delAnalyzer(PoolNameOrSocket, AnalyzerName) -> + Path = <<"/_api/analyzer/", AnalyzerName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delAnalyzer(PoolNameOrSocket, AnalyzerName, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/analyzer/", AnalyzerName/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). diff --git a/src/agApi/agAqls.erl b/src/agApi/agAqls.erl new file mode 100644 index 0000000..5c5276c --- /dev/null +++ b/src/agApi/agAqls.erl @@ -0,0 +1,426 @@ +-module(agAqls). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +% doc_address: +% AQL Query Cursors: +% https://www.arangodb.com/docs/stable/http/aql-query-cursor.html +% AQL Query: +% https://www.arangodb.com/docs/stable/http/aql-query-cursor.html +% AQL Query Results Cache: +% https://www.arangodb.com/docs/stable/http/aql-query-cursor.html +% AQL User Functions Management: +% https://www.arangodb.com/docs/stable/http/aql-query-cursor.html +% 该模块汇总封装上面所有AQL操作 + +% AQL查询游标的HTTP接口 +% 这是ArangoDB查询的HTTP接口的简介。AQL的结果和简单查询作为游标返回，以便批量处理服务器与客户端之间的通信。每次调用将返回一批文档，并指示当前批是否为最终批。根据查询的不同，结果集中的文档总数可能会或可能不会事先知道。为了释放服务器资源，客户端应在不再需要游标时将其删除。 +% 要执行查询，需要通过HTTP POST请求将查询详细信息从客户端传送到服务器。 + +% 检索查询结果 +% 选择查询在服务器上即时执行，结果集将返回给客户端。 +% 客户端可以通过两种方式从服务器获取结果集： +% 单次返回 +% 使用游标 + +% 单次返回 +% 服务器将在一次往返中仅将一定数量的结果文档传送回客户端。客户端可以通过在发出查询时设置batchSize属性来控制此数字。 +% 如果完整的结果可以一次性传递给客户端，则客户端不需要发出任何其他请求。客户端可以通过检查结果集的hasMore属性来检查是否已检索到完整的结果集。如果将其设置为false，则客户端已从服务器获取了完整的结果集。在这种情况下，将不会创建服务器端游标。 + +% 使用游标 +% 如果结果集中包含的文档数量超出单次往返传输的文档数量（即通过batchSize属性设置的数量），则服务器将返回前几个文档并创建一个临时游标。游标标识符也将返回给客户端。服务器会将光标标识符放在响应对象的id属性中。此外， 响应对象的hasMore属性将设置为true。这表明客户端还有其他结果要从服务器获取。 + +% 通过HTTP访问游标 +% 创建光标 +% 创建一个游标并返回第一个结果 +% POST /_api/cursor +% 描述查询和查询参数的JSON对象。 +% 具有以下属性的JSON对象是必需的： +% query：包含要执行的查询字符串 +% count：指示是否应在结果的“ count”属性中返回结果集中的文档数。计算“ count”属性将来可能会对某些查询产生性能影响，因此默认情况下此选项处于关闭状态，并且仅在请求时返回“ count”。 +% batchSize：一次往返从服务器传输到客户端的最大结果文档数。如果未设置此属性，则将使用服务器控制的默认值。甲BATCHSIZE的值 0是不允许的。 +% ttl：光标的生存时间（以秒为单位）。在指定的时间后，游标将自动在服务器上删除。这对于确保客户端不完全获取的游标的垃圾回收很有用。如果未设置，则将使用服务器定义的值（默认值：30秒）。 +% cache：用于确定是否应使用AQL查询结果缓存的标志。如果设置为false，那么将跳过查询的任何查询缓存。如果设置为真，这将导致被检查的查询缓存为查询，如果查询缓存模式是上还是需求。 +% memoryLimit：允许查询使用的最大内存数（以字节为单位）。如果设置，则查询将分配过多的内存而失败，并显示错误“超出资源限制”。值为0表示没有内存限制。 +% bindVars：表示绑定参数的键/值对。 +% options：键/值对象，带有用于查询的其他选项。 +% FULLCOUNT：如果设置为真，并在查询中包含LIMIT子句，那么结果将有一个额外的与子属性属性统计 和FULLCOUNT，{ ... , "extra": { "stats": { "fullCount": 123 } } }。该FULLCOUNT属性将包含的文档数量的结果应用于在查询的最后顶层限制之前。它可用于计算符合特定过滤条件的文档数量，但一次只能返回其中的一部分。因此，它类似于MySQL的SQL_CALC_FOUND_ROWS暗示。请注意，设置该选项将禁用一些LIMIT优化，并可能导致处理更多文档，从而使查询运行时间更长。请注意，仅当查询具有顶级LIMIT子句并且在查询中实际使用LIMIT子句时，fullCount属性才可能出现在结果中。 +% maxPlans：限制AQL查询优化器创建的最大计划数。 +% maxWarningCount：限制查询将返回的最大警告数。默认情况下，查询将返回的警告数限制为10，但是可以通过设置此属性来增加或减少该警告数。 +% failOnWarning：设置为true时，查询将引发异常并中止而不产生警告。在开发过程中应使用此选项，以尽早发现潜在问题。当该属性设置为false时，警告将不会传播到异常，并将与查询结果一起返回。还有一个服务器配置选项，--query.fail-on-warning用于设置failOnWarning的默认值，因此不需要在每个查询级别上进行设置。 +% stream：指定true，查询将以流方式执行。查询结果不存储在服务器上，而是动态计算的。注意：只要查询游标存在，长时间运行的查询就需要保持收集锁。设置为false时，查询将立即全部执行。在这种情况下，查询结果要么立即返回（如果结果集足够小），要么存储在arangod实例上，并且可以通过游标API进行访问（相对于ttl）。建议仅在短期运行的查询上使用此选项，或者不使用排他锁（MMFiles上的写锁）。请注意查询选项cache，count并且fullCount不适用于流查询。此外，查询统计信息，警告和概要分析数据仅在查询完成之后才可用。默认值为false +% Optimizer：与查询优化器有关的选项。 +% rules：可以在此属性中放入要包括的或要排除的优化器规则的列表，告诉优化器包括或排除特定的规则。要禁用规则，请在其名称前面加上-，以启用规则，并在其前面加上+。还有一个伪规则all，它匹配所有优化程序规则。-all禁用所有规则。 +% profile：如果设置为true或1，那么如果未从查询缓存提供查询结果，则将在Extra Return属性的子属性配置文件中返回其他查询概要信息。设置为2时，查询将在Extra Return属性的子属性stats.nodes中包含每个查询计划节点的执行统计信息。此外，查询计划在子属性extra.plan中返回。 +% satelliteSyncWait：此Enterprise Edition参数允许配置DB-Server将有多长时间使查询中涉及的Satellite集合同步。默认值为60.0（秒）。达到最大时间后，查询将停止。 +% maxRuntime：查询必须在给定的运行时内执行，否则将被终止。该值以秒为单位指定。默认值为0.0（无超时）。 +% maxTransactionSize：事务大小限制（以字节为单位）。仅受RocksDB存储引擎的尊敬。 +% middleCommitSize：最大操作总数，之后将自动执行中间提交。仅受RocksDB存储引擎的尊敬。 +% middleCommitCount：操作之后自动执行中间提交的最大操作数。仅受RocksDB存储引擎的尊敬。 +% skipInaccessibleCollections：AQL查询（尤其是图遍历）将用户没有访问权限的集合视为这些集合为空。您的查询将正常执行，而不是返回禁止的访问错误。这旨在帮助某些用例：一个图包含多个集合，并且不同的用户在该图上执行AQL查询。现在，您可以通过更改用户对集合的访问权限来自然地限制可访问的结果。此功能仅在企业版中可用。 +% +% 查询详细信息包括查询字符串以及可选的查询选项和绑定参数。这些值需要在POST请求的主体中以JSON表示形式传递。 +% 如果结果集可以由服务器创建，则返回HTTP 201。 +% error：一个标志，指示发生错误（在这种情况下为false） +% code：HTTP状态码 +% result：结果文档数组（如果查询没有结果，则可能为空） +% hasMore：一个布尔值指示符，指示服务器上的游标是否还有更多结果可用 +% count：可用结果文档总数（仅当查询是在设置了count属性的情况下执行的） +% id：在服务器上创建的临时光标的ID（可选，请参见上文） +% extra：一个可选的JSON对象，其统计信息子属性中包含有关查询结果的额外信息。对于数据修改查询， extra.stats子属性将包含已修改的文档数和由于错误而无法修改的文档数（如果指定了ignoreErrors查询选项） +% cached：一个布尔型标志，指示是否从查询缓存提供查询结果。如果从查询缓存提供查询结果，则额外的 return属性将不包含任何stats子属性，也不会包含任何配置文件子属性。 +% +% 如果JSON格式不正确或请求中缺少查询规范，则返回HTTP 400。 +% 如果JSON格式不正确或请求中缺少查询规范，则服务器将使用HTTP 400进行响应。 +% 响应的主体将包含带有其他错误详细信息的JSON对象。该对象具有以下属性： +% error：布尔值标志，指示发生错误（在这种情况下为true） +% code：HTTP状态码 +% errorNum：服务器错误号 +% errorMessage：描述性错误消息 +% 如果查询规范已完成，服务器将处理查询。如果在查询处理期间发生错误，则服务器将使用HTTP 400进行响应。同样，响应的正文将包含有关错误的详细信息。 +% 一个查询错误的列表可以在这里找到。 +% 404：如果查询中访问了不存在的集合，服务器将以HTTP 404进行响应。 +% 405：如果使用了不受支持的HTTP方法，则服务器将以HTTP 405进行响应。 +newCursor(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, <<"/_api/cursor">>, [], BodyStr). + + +% 从现有游标返回下一个结果 +% PUT /_api/cursor/{cursor-identifier} +% 路径参数 +% cursor-identifier（必填）：光标的名称 +% 如果游标仍然存在，则返回具有以下属性的对象： +% id：光标标识符 +% 结果：当前批次的文档列表 +% hasMore：如果这是最后一批，则为false +% count：如果存在，元素总数 +% 请注意，即使hasMore返回true，下一次调用仍可能不返回任何文档。但是，如果hasMore为false，则光标将被耗尽。一旦hasMore属性的值为 false，客户端就可以停止。 +% 返回码 +% 200：如果成功，服务器将以HTTP 200响应。 +% 400：如果省略了光标标识符，则服务器将使用HTTP 404进行响应。 +% 404：如果找不到具有指定标识符的游标，则服务器将使用HTTP 404进行响应。 +nextCursor(PoolNameOrSocket, CursorId) -> + Path = <<"/_api/cursor/", (agMiscUtils:toBinary(CursorId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], undefined). + +% 删除光标永 +% DELETE /_api/cursor/{cursor-identifier} +% 路径参数 +% cursor-identifier（必填）：光标的ID +% 删除游标并释放与其关联的资源。 +% 当客户端从服务器上检索所有文档时，游标将在服务器上自动销毁。客户端还可以使用HTTP DELETE请求在任何较早的时间显式销毁游标。游标ID必须作为URL的一部分包含在内。 +% 注意：在服务器控制的特定超时后，服务器还将自动销毁废弃的游标，以避免资源泄漏。 +% 返回码 +% 202：如果服务器知道游标，则返回。 +% 404：如果服务器不知道游标，则返回404。如果在销毁游标后使用了游标，也将返回该值。 +delCursor(PoolNameOrSocket, CursorId) -> + Path = <<"/_api/cursor/", (agMiscUtils:toBinary(CursorId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +% AQL查询的HTTP接口 +% +% 解释和解析查询 +% ArangoDB有一个HTTP接口，用于语法验证AQL查询。此外，它提供了一个HTTP接口来检索任何有效AQL查询的执行计划。 +% 这两个功能实际上并不执行提供的AQL查询，而只是检查它并返回有关它的元信息。 + +% 解释一个AQL查询并返回有关它的信息 +% POST /_api/explain +% 描述查询和查询参数的JSON对象。 +% 具有以下属性的JSON对象是必需的： +% query：您要解释的查询；如果查询引用了任何绑定变量，则这些变量也必须在属性bindVars中传递。可以在options属性中传递查询的其他选项。 +% bindVars：表示绑定参数的键/值对。 +% options：查询选项 +% allPlans：如果设置为true，将返回所有可能的执行计划。默认值为false，这意味着将仅返回最佳计划。 +% maxNumberOfPlans：允许优化程序生成的可选计划最大数量。将此属性设置为较低的值可以限制优化器的工作量。 +% Optimizer：与查询优化器有关的选项。 +% rules：可以在此属性中放入要包括的或要排除的优化器规则的列表，告诉优化器包括或排除特定的规则。要禁用规则，请在其名称前面加上-，以启用规则，并在其前面加上+。还有一个伪规则all，它匹配所有优化程序规则。-all禁用所有规则。 +% +% 为了说明如何在服务器上执行AQL查询，可以通过HTTP POST请求将查询字符串发送到服务器。然后，服务器将验证查询并为其创建执行计划。将返回执行计划，但不会执行查询。 +% 服务器返回的执行计划可用于估计查询的可能性能。尽管实际性能将取决于许多不同的因素，但是执行计划通常可以对服务器实际运行查询所需的工作量提供一些粗略的估计。 +% 默认情况下，解释操作将返回查询优化器选择的最佳计划。最佳计划是总估计成本最低的计划。该计划将在响应对象的属性计划中返回。如果在请求中指定了allPlans选项，则结果将包含优化器创建的所有计划。然后将在属性计划中返回计划。 +% 结果还将包含一个属性warnings，它是在优化或执行计划创建期间发生的一系列警告。此外，结果中还包含stats属性以及一些优化程序统计信息。如果allPlans设置为false，则结果将包含可缓存的属性 ，该属性指示如果使用了查询结果缓存，则是否可以将查询结果缓存在服务器上。该缓存时属性不存在allPlans 设置为真。 +% 结果中的每个计划都是一个具有以下属性的JSON对象： +% nodes：计划执行节点的数组。可在此处找到可用节点类型的数组 +% estimatedCost：计划的总估计费用。如果有多个计划，优化器将选择总成本最低的计划。 +% collections：查询中使用的一组collections +% rules：优化程序应用的规则数组。可在此处找到可用规则的​​概述 +% variables：查询中使用的变量数组（注意：这可能包含优化器创建的内部变量） +% 返回码 +% 200：如果查询有效，则服务器将使用HTTP 200进行响应，并在响应的plan属性中返回最佳执行计划。如果在请求中设置了选项allPlans，则将在allPlans属性中返回一系列计划。 +% 400：如果请求格式错误或查询包含解析错误，服务器将以HTTP 400响应。响应的正文将包含嵌入在JSON对象中的错误详细信息。如果查询引用任何变量，则忽略绑定变量也会导致HTTP 400错误。 +% 404：如果查询中访问了不存在的集合，服务器将以HTTP 404进行响应。 +explainQuery(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, <<"/_api/explain">>, [], BodyStr). + +% 解析一个AQL查询并返回有关它的信息 +% POST /_api/query +% 具有以下属性的JSON对象是必需的： +% query：要在不执行查询字符串的情况下对其进行验证，可以通过HTTP POST请求将查询字符串传递到服务器。 +% 该端点仅用于查询验证。要实际查询数据库，请参阅/api/cursor。 +% 返回码 +% 200：如果查询有效，服务器将使用HTTP 200进行响应，并在响应的bindVars属性中返回在查询中找到的绑定参数的名称（如果有）。它还将在collections属性中返回查询中使用的collections的数组。如果查询可以成功解析，则返回的JSON 的ast属性将包含查询的抽象语法树表示形式。ast的格式在将来的ArangoDB版本中可能会发生变化，但是可以用来检查ArangoDB如何解释给定查询。请注意，将在不对其应用任何优化的情况下返回抽象语法树。 +% 400：如果请求格式错误或查询包含解析错误，服务器将以HTTP 400响应。响应的正文将包含嵌入在JSON对象中的错误详细信息。 +parseQuery(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, <<"/_api/query">>, [], BodyStr). + +% 查询跟踪固定链接 +% ArangoDB具有HTTP接口，用于检索当前正在执行的AQL查询列表和慢速AQL查询列表。为了有意义地使用这些API，需要在执行HTTP请求的数据库中启用查询跟踪。 + +% 返回AQL查询跟踪的配置 +% GET /_api/query/properties +% 返回当前查询跟踪配置。该配置是具有以下属性的JSON对象： +% enabled：如果设置为true，那么将跟踪查询。如果设置为 false，则不会跟踪查询或慢速查询。 +% trackSlowQueries：如果设置为true，则如果慢查询的运行时间超过了slowQueryThreshold中设置的值，则将在慢查询列表中跟踪慢查询 。为了跟踪慢查询， 还必须将enabled属性设置为true。 +% trackBindVars：如果设置为true，那么将跟踪查询中使用的绑定变量。 +% maxSlowQueries：保留在慢速查询列表中的最大慢速查询数。如果慢速查询列表已满，则在发生其他慢速查询时，其中最早的条目将被丢弃。 +% slowQueryThreshold：用于将查询视为慢查询的阈值。当启用慢查询跟踪时，运行时大于或等于此阈值的查询将被放入慢查询列表中。slowQueryThreshold的值以秒为单位指定。 +% maxQueryStringLength：保留在查询列表中的最大查询字符串长度。查询字符串可以有任意长度，如果使用非常长的查询字符串，则可以使用此属性来节省内存。该值以字节为单位指定。 +% 返回码 +% 200：如果成功检索到属性，则返回。 +% 400：如果请求格式错误，服务器将以HTTP 400进行响应， +getQueryProps(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/query/properties">>, [], undefined). + +% 更改AQL查询跟踪的配置 +% PUT /_api/query/properties +% 具有以下属性的JSON对象是必需的： +% enabled：如果设置为true，那么将跟踪查询。如果设置为 false，则不会跟踪查询或慢速查询。 +% trackSlowQueries：如果设置为true，则如果慢查询的运行时间超过了slowQueryThreshold中设置的值，则将在慢查询列表中跟踪慢查询 。为了跟踪慢查询， 还必须将enabled属性设置为true。 +% trackBindVars：如果设置为true，那么将与查询一起跟踪查询中使用的绑定变量。 +% maxSlowQueries：保留在慢速查询列表中的最大慢速查询数。如果慢速查询列表已满，则在发生其他慢速查询时，其中最早的条目将被丢弃。 +% slowQueryThreshold：用于将查询视为慢速的阈值。当启用慢查询跟踪时，运行时大于或等于此阈值的查询将被放入慢查询列表中。slowQueryThreshold的值以秒为单位指定。 +% maxQueryStringLength：要保留在查询列表中的最大查询字符串长度。查询字符串可以有任意长度，如果使用非常长的查询字符串，则可以使用此属性来节省内存。该值以字节为单位指定。 +% 这些属性需要在HTTP请求主体的属性属性中传递。属性必须是JSON对象。 +% 更改属性后，将在HTTP响应中返回当前属性集。 +% 返回码 +% 200：如果属性更改成功，则返回。 +% 400：如果请求格式错误，服务器将以HTTP 400进行响应， +changeQueryProps(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, <<"/_api/query/properties">>, [], BodyStr). + +% 返回当前正在运行的AQL查询的列表 +% GET /_api/query/current +% 返回一个数组，其中包含所选数据库中当前正在运行的AQL查询。每个查询都是一个具有以下属性的JSON对象： +% id：查询的ID +% query：查询字符串（可能被截断） +% bindVars：查询使用的绑定参数值 +% started：查询开始的日期和时间 +% runTime：查询的运行时间，直到查询到查询列表为止 +% state：查询的当前执行状态（以字符串形式） +% stream：查询是否使用流游标 +% 返回码 +% 200：可以成功检索查询列表时返回。 +% 400：如果请求格式错误，服务器将以HTTP 400进行响应， +currentQuery(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/query/current">>, [], undefined). + + +% 返回运行缓慢的AQL查询的列表 +% GET /_api/query/slow +% 返回一个数组，其中包含已完成并超过所选数据库中慢速查询阈值的最后一个AQL查询。可以通过设置查询跟踪属性来控制列表中的最大查询数量maxSlowQueries。可以通过设置查询跟踪属性来调整 将查询视为慢速查询的阈值slowQueryThreshold。 +% 每个查询都是一个具有以下属性的JSON对象： +% id：查询的ID +% query：查询字符串（可能被截断） +% bindVars：查询使用的绑定参数值 +% started：查询开始的日期和时间 +% runTime：查询的总运行时间 +% state：查询的当前执行状态（对于慢速查询列表将始终“完成”） +% stream：查询是否使用流游标 +% 返回码 +% 200：可以成功检索查询列表时返回。 +% 400：如果请求格式错误，服务器将以HTTP 400进行响应， +getSlowQuery(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/query/slow">>, [], undefined). + +% 清除慢速AQL查询列表 +% DELETE /_api/query/slow +% 清除慢速AQL查询列表 +% 返回码 +% 200：成功清除查询列表后，服务器将以HTTP 200响应。 +% 400：如果请求格式错误，服务器将使用HTTP 400进行响应。 +delSlowQuery(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, <<"/_api/query/slow">>, [], undefined). + + +% 杀死查询永久链接 +% 运行中的AQL查询也可以在服务器上终止。ArangoDB通过HTTP接口提供了终止功能。要终止正在运行的查询，必须指定其ID（在当前正在运行的查询列表中为该查询返回的ID）。然后将设置查询的kill标志，并且查询到达取消点后将中止查询。 + +% 杀死一个AQL查询 +% DELETE /_api/query/{query-id} +% 路径参数 +% query-id（必填）：查询的ID。 +% 终止正在运行的查询。查询将在下一个取消点终止。 +% 返回码 +% 200：当执行终止请求并设置查询的终止标志时，查询仍在运行时，服务器将以HTTP 200响应。 +% 400：如果请求格式错误，服务器将使用HTTP 400进行响应。 +% 404：当找不到指定ID的查询时，服务器将以HTTP 404响应。 +killQuery(PoolNameOrSocket, QueryId) -> + Path = <<"/_api/query/", (agMiscUtils:toBinary(QueryId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +% AQL查询结果缓存的HTTP接口 +% 本节介绍用于控制AQL查询结果缓存的API方法。 + +% 返回AQL查询结果缓存中存储结果的列表 +% GET /_api/query-cache/entries +% 返回一个数组，其中包含当前存储在所选数据库的查询结果缓存中的AQL查询结果。每个结果都是一个具有以下属性的JSON对象： +% hash：查询结果的哈希值 +% query：查询字符串 +% bindVars：查询的绑定参数。仅当服务器启动时启用了对绑定变量的跟踪时，才显示此属性 +% size：查询结果和绑定参数的大小，以字节为单位 +% results：查询结果中的文档/行数 +% started：查询存储在缓存中的日期和时间 +% hits：从缓存中提供结果的次数（对于仅存储在缓存中但以后再也不会访问的查询，可以为 0） +% runTime：查询的运行时间 +% dataSources：查询所使用的集合/视图的数组 +% 返回码 +% 200：可以成功检索结果列表时返回。 +% 400：如果请求格式错误，服务器将以HTTP 400进行响应， +getQueryCaches(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/query-cache/entries">>, [], undefined). + +% 清除AQL查询结果缓存中的所有结果 +% DELETE /_api/query-cache +% 清除当前数据库的查询结果缓存 +% 返回码 +% 200：成功清除缓存后，服务器将以HTTP 200响应。 +% 400：如果请求格式错误，服务器将使用HTTP 400进行响应。 +clearQueryCaches(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, <<"/_api/query-cache">>, [], undefined). + +% 返回AQL查询结果缓存的全局配置 +% GET /_api/query-cache/properties +% 返回全局AQL查询结果缓存配置。该配置是具有以下属性的JSON对象： +% mode：AQL查询结果缓存运行的模式。该模式是下列值之一：off，on或demand。 +% maxResults：每个特定于数据库的缓存将存储的最大查询结果数。 +% maxResultsSize：每个数据库特定的缓存将存储的查询结果的最大累积大小。 +% maxEntrySize：每个特定于数据库的缓存将存储的查询的最大单个结果大小。 +% includeSystem：是否将涉及系统集合的查询结果存储在查询结果缓存中。 +% 返回码 +% 200：如果可以成功检索属性，则返回。 +% 400：如果请求格式错误，服务器将以HTTP 400进行响应， +getQCacheProps(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/query-cache/properties">>, [], undefined). + +% 全局调整AQL查询结果缓存属性 +% PUT /_api/query-cache/properties +% 具有以下属性的JSON对象是必需的： +% mode：AQL查询缓存应以哪种模式运行。可能的值是off，on或demand。 +% maxResults：每个特定于数据库的缓存将存储的最大查询结果数。 +% maxResultsSize：每个数据库特定的缓存将存储的查询结果的最大累积大小。 +% maxEntrySize：每个数据库特定的缓存将存储的查询结果的最大单个大小。 +% includeSystem：是否存储涉及系统集合的查询结果。 +% 更改属性后，将在HTTP响应中返回当前属性集。 +% 注意：更改属性可能会使缓存中的所有结果无效。AQL查询缓存的全局属性。这些属性需要在HTTP请求主体的属性属性中传递。属性必须是具有以下属性的JSON对象： +% 返回码 +% 200：如果属性更改成功，则返回。 +% 400：如果请求格式错误，服务器将以HTTP 400进行响应， +changeQCacheProps(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, <<"/_api/query-cache/properties">>, [], BodyStr). + +% AQL用户功能管理固定链接 +% 这是用于管理AQL用户功能的ArangoDB HTTP接口的简介。AQL用户功能是一种使用用户定义的JavaScript代码扩展ArangoDB查询语言（AQL）功能的方法。 +% 有关AQL用户功能及其含义的概述，请参阅“ 扩展AQL”一章。 +% HTTP接口提供用于添加，删除和列出以前注册的AQL用户功能的API。 +% 通过此接口管理的所有用户功能将存储在系统集合_aqlfunctions中。此集合中的文档不应直接访问，而只能通过专用接口访问。 + +% 创建一个新的AQL用户功能 +% POST /_api/aqlfunction +% 具有以下属性的JSON对象是必需的： +% name：用户函数的标准名称。 +% code：函数主体的字符串表示形式。 +% isDeterministic：一个可选的布尔值，用于指示函数结果是否完全确定（函数返回值仅取决于输入值，并且对于具有相同输入的重复调用，返回值相同）。该isDeterministic属性是当前未使用但对于优化可以在以后使用。 +% 如果成功，则返回HTTP 200。如果该功能无效等，则将返回包含详细错误消息的HTTP 400。 +% HTTP 200如果功能已经存在并被调用所取代，则服务器将使用HTTP 200进行响应。 +% error：布尔值标志，指示是否发生错误（在这种情况下为false） +% code：HTTP状态码 +% isNewlyCreated：布尔值标志，指示是否新创建了函数（在这种情况下为false） +% HTTP 201如果服务器可以注册该功能，则服务器将使用HTTP 201进行响应 。 +% error：布尔值标志，指示是否发生错误（在这种情况下为false） +% code：HTTP状态码 +% isNewlyCreated：布尔值标志，指示是否新创建了函数（在这种情况下为true） +% HTTP 400如果JSON格式不正确或请求中缺少必需数据，则服务器将使用HTTP 400进行响应。 +% error：布尔值标志，指示是否发生错误（在这种情况下为true） +% code：HTTP状态码 +% errorNum：服务器错误号 +% errorMessage：描述性错误消息 +newUserFun(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, <<"/_api/aqlfunction">>, [], BodyStr). + +% 删除现有的AQL用户功能 +% DELETE /_api/aqlfunction/{name} +% 路径参数 +% name（必填）：AQL用户功能的名称。 +% 查询参数 +% group（可选）： - 真：中提供的功能的名称的名称被视为一个命名空间前缀，并在指定的命名空间的所有功能。将被删除。如果没有匹配的字符串，返回的删除函数数可能变为0。 +% false：中提供的函数名的名称必须是完全限定，包括任何命名空间。如果没有一个与名称匹配，则返回HTTP 404。 + +% 删除由name标识的现有AQL用户功能或功能组。 +% HTTP 200如果服务器可以删除该功能，则服务器将使用HTTP 200进行响应 。 +% error：布尔值标志，指示是否发生错误（在这种情况下为false） +% code：HTTP状态码 +% DeleteCount：删除的用户功能的数量，总是1在group设置为false时。设置为true>= 0时的任何数字group +% HTTP 400如果用户功能名称格式错误，则服务器将使用HTTP 400进行响应。 +% error：布尔值标志，指示是否发生错误（在这种情况下为true） +% code：HTTP状态码 +% errorNum：服务器错误号 +% errorMessage：描述性错误消息 +% HTTP 404如果指定的用户用户功能不存在，则服务器将使用HTTP 404进行响应。 +% error：布尔值标志，指示是否发生错误（在这种情况下为true） +% code：HTTP状态码 +% errorNum：服务器错误号 +% errorMessage：描述性错误消息 +delUserFun(PoolNameOrSocket, UserFunName) -> + Path = <<"/_api/aqlfunction/", (agMiscUtils:toBinary(UserFunName))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delUserFun(PoolNameOrSocket, UserFunName, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/aqlfunction/", (agMiscUtils:toBinary(UserFunName))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +% 返回注册的AQL用户功能 +% GET /_api/aqlfunction +% 查询参数 +% namespace（可选）：从result下的命名空间namespace返回所有已注册的AQL用户函数。 +% 返回所有已注册的AQL用户功能。 +% 该调用将返回一个带有状态代码的JSON数组，以及在result下找到的所有用户函数。 +% HTTP 200成功HTTP 200返回。 +% error：布尔值标志，指示是否发生错误（在这种情况下为false） +% code：HTTP状态码 +% result：所有函数，或与命名空间参数匹配的函数 +% name：用户功能的标准名称 +% code：函数体的字符串表示形式 +% isDeterministic：一个可选的布尔值，用于指示函数结果是否完全确定（函数返回值仅取决于输入值，并且对于具有相同输入的重复调用，返回值相同）。该isDeterministic属性是当前未使用但对于优化可以在以后使用。 +% HTTP 400如果用户功能名称格式错误，则服务器将使用HTTP 400进行响应。 +% error：布尔值标志，指示是否发生错误（在这种情况下为true） +% code：HTTP状态码 +% errorNum：服务器错误号 +% errorMessage：描述性错误消息 +getUserFuns(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/aqlfunction">>, [], undefined). + +getUserFuns(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/aqlfunction", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + + + + + + + + + + + diff --git a/src/agApi/agAsyncResultHandling.erl b/src/agApi/agAsyncResultHandling.erl new file mode 100644 index 0000000..caa812b --- /dev/null +++ b/src/agApi/agAsyncResultHandling.erl @@ -0,0 +1,140 @@ +-module(agAsyncResultHandling). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/async-results-management.html + +% 用于异步结果管理的HTTP接口 +% 请求执行 +% ArangoDB提供了执行客户端请求的各种方法。客户可以根据其吞吐量，控制流和耐用性要求，在每个请求级别上选择适当的方法。 +% +% 阻止执行 +% ArangoDB是多线程服务器，允许同时处理多个客户端请求。通信处理和实际工作可以由多个工作线程并行执行。 +% +% 尽管多个客户端可以连接并并行将其请求发送到ArangoDB，但是客户端可能需要等待其请求被处理。 +% +% 默认情况下，服务器将完全处理传入的请求，然后将结果返回给客户端。客户端必须等待服务器的响应，然后才能通过连接发送其他请求。对于单线程或非事件驱动的客户端，等待完整的服务器响应可能不是最佳的。 +% +% 此外，请注意，即使客户端关闭了HTTP连接，在服务器上运行的请求仍将继续，直到完成为止，然后注意客户端不再侦听。因此，关闭连接无助于中止长时间运行的查询！有关详细信息，请参见下面的“ 异步执行”和“结果检索” 以及HttpJobPutCancel下的内容。 +% +% 忘记并 +% 为了缓解客户端阻止问题，自版本1.4开始使用ArangoDB。提供了一种非阻塞请求的通用机制：如果客户端在请求中添加HTTP标头x-arango-async：true，则ArangoDB会将请求放入内存任务队列中，并向HTTP请求返回HTTP 202（接受）响应客户立即。服务器将异步执行队列中的任务，从而将客户端请求与实际工作分离。 +% +% 与客户端等待服务器响应相比，这可以提供更高的吞吐量。缺点是发送到客户端的响应始终是相同的（通用HTTP 202），并且客户端此时无法基于实际操作的结果做出决定。实际上，在通用响应到达客户端时，该操作甚至可能尚未执行。因此，客户不能依赖其请求已被成功处理。 +% +% 服务器上的异步任务队列不会保留，这意味着如果发生崩溃，队列中尚未处理的任务将丢失。但是，客户端将不知道它们是否已被处理。 +% +% 因此，当客户具有严格的持久性要求或依靠发送操作的结果采取进一步措施时，客户不应发送额外的标头。 +% +% 排队任务的最大数量由启动选项 --server.maximal-queue-size确定。如果已排队的任务数量超过此数量，则服务器将拒绝该请求，并显示HTTP 500错误。 +% +% 最后，请注意，无法取消这种火灾并忘记工作，因为稍后您将无法识别它。如果您需要取消请求，请使用“ 异步执行”以及更高版本的“结果检索” 和下面的HttpJobPutCancel。 +% +% 异步执行和以后的结果检索 +% 通过将HTTP标头x-arango-async：存储添加到请求中，客户端可以指示ArangoDB服务器如上所述异步执行操作，还可以将操作结果存储在内存中以供以后检索。服务器将在HTTP响应标头x-arango-async-id中返回作业ID。客户端可以将此ID与/ _api / job上的HTTP API结合使用，这在本手册中有详细说明。 +% +% 客户可以通过异步作业API询问ArangoDB服务器，哪些结果准备好检索，哪些没有准备好。客户端还可以通过将原始返回的作业ID传递给异步作业API，以获取已执行的异步作业的原始结果。然后，服务器将返回作业结果，就好像作业已正常执行一样。此外，客户端可以通过其作业ID取消运行异步作业，请参见HttpJobPutCancel。 +% +% ArangoDB将保留通过x-arango-async：存储 头启动的所有作业结果。仅当客户端明确要求服务器提供特定结果时，才会从服务器中删除结果。 +% +% 异步作业API还提供了用于垃圾回收的方法，客户端可以使用这些方法来摆脱“旧的”未获取的结果。客户应定期调用此方法，因为ArangoDB不会人为地限制尚未获取的结果的数量。 +% +% 因此，客户有责任仅存储所需的尽可能多的结果，并尽快获取可用的结果，或至少不时清理未获取的结果。 +% +% 作业队列和结果仅保存在服务器上的内存中，因此在崩溃时它们将丢失。 +% +% 取消异步作业 +% 如上所述，可以使用其作业ID取消异步运行的作业。如HttpJobPutCancel中所述，这是通过PUT请求 完成的。 +% +% 但是，要对幕后发生的事情进行一些解释。首先，一个正在运行的异步查询可以在内部由C ++代码或JavaScript代码执行。例如，CRUD操作直接在C ++中执行，而AQL查询和事务由JavaScript代码执行。作业取消仅适用于JavaScript代码，因为所使用的机制只是在JavaScript线程中触发不可捕获的异常，而该异常将在C ++级别上捕获，从而导致作业的取消。以后将无法检索到任何结果，因为有关该请求的所有数据都将被丢弃。 +% +% 如果取消在集群的协调器上运行的作业（共享），则仅停止在协调器上运行的代码，集群中可能残留了已经分配给DB-Server的任务，目前无法执行也要取消它们 +% +% 异步执行和身份验证 +% 如果请求需要身份验证，则在排队之前运行身份验证过程。仅当请求有效凭据且身份验证成功时，该请求才会排队。如果请求不包含有效的凭据，则不会将其排队，但会以与“常规”非排队请求相同的方式立即被拒绝。 + + +% 获取作业结果并将其从队列中删除 +% PUT /_api/job/{job-id} +% 路径参数 +% job-id（必填）：异步作业ID。 +% 返回由job-id标识的异步作业的结果。如果服务器上存在异步作业结果，则该结果将从结果列表中删除。这意味着可以为每个job-id调用一次此方法。该方法将返回原始作业结果的标头和正文，以及附加的HTTP标头x-arango-async-job-id。如果存在此标头，则找到作业，并且响应中包含原始作业的结果。如果标题不存在，则找不到作业，并且响应中包含来自作业管理器的状态信息。 +% 返回码 +% 204：如果通过job-id请求的作业仍在待处理（或尚未完成）的作业队列中，则返回。在这种情况下，不会返回x-arango-async-id HTTP标头。 +% 400：如果在请求中未指定作业ID，则返回。在这种情况下，不会返回x-arango-async-id HTTP标头。 +% 404：如果找不到或已经从作业结果列表中删除或提取了作业，则返回404。在这种情况下，不会返回x-arango-async-id HTTP标头。 +getAsyncJobRet(PoolNameOrSocket, JodId) -> + Path = <<"/_api/job/", (agMiscUtils:toBinary(JodId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], undefined). + + +% 取消异步作业 +% PUT /_api/job/{job-id}/cancel +% 路径参数 +% job-id（必填）：异步作业ID。 +% 取消由作业ID标识的当前正在运行的作业。请注意，实际取消正在运行的异步作业仍可能需要一些时间。 +% 返回码 +% 200：取消已启动。 +% 400：如果在请求中未指定作业ID，则返回。在这种情况下，不会返回x-arango-async-id HTTP标头。 +% 404：如果找不到或已经从作业结果列表中删除或提取了作业，则返回404。在这种情况下，不会返回x-arango-async-id HTTP标头。 +cancelAsyncJob(PoolNameOrSocket, JodId) -> + Path = <<"/_api/job/", (agMiscUtils:toBinary(JodId))/binary, "/cancel">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], undefined). + +% 删除异步作业结果 +% DELETE /_api/job/{type}#by-type +% 路径参数 +% type（必填）：要删除的作业类型。类型可以是： +% all：删除所有作业结果。当前正在执行或排队的异步作业不会被此调用停止。 +% expired：删除过期的结果。要确定结果的到期状态，请传递戳记查询参数。stamp必须是UNIX时间戳，所有在较低时间戳创建的异步作业结果都将被删除。 +% an actual job-id：在这种情况下，调用将删除指定的异步工作的结果。如果作业当前正在执行或排队，则不会中止。 +% 查询参数 +% stamp（可选）：UNIX时间戳记，用于指定类型过期时的过期阈值。 +% 删除所有作业结果，过期的作业结果或特定作业的结果。客户可以使用此方法对工作结果进行最终的垃圾收集。 +% 返回码 +% 200：如果删除操作成功执行，则返回。如果未删除任何结果，还将返回此代码。 +% 400：如果未指定type或值无效，则返回。 +% 404：如果type为job-id，但未找到具有指定id的异步作业，则返回404。 +delAsyncJobRet(PoolNameOrSocket, TypeOrJodId) -> + Path = <<"/_api/job/", (agMiscUtils:toBinary(TypeOrJodId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delAsyncJobRet(PoolNameOrSocket, TypeOrJodId, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/job/", (agMiscUtils:toBinary(TypeOrJodId))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +% 返回特定作业的状态 +% GET /_api/job/{job-id} +% 路径参数 +% job-id（必填）：异步作业ID。 +% 返回指定作业的处理状态。可以通过查看响应的HTTP响应代码来确定处理状态。 +% 返回码 +% 200：如果已经执行了通过job-id请求的作业，并且已准备好获取其结果，则返回200。 +% 204：如果通过job-id请求的作业仍在待处理（或尚未完成）的作业队列中，则返回。 +% 404：如果找不到或已经从作业结果列表中删除或提取了作业，则返回404。 +getAsyncJobStatus(PoolNameOrSocket, JodId) -> + Path = <<"/_api/job/", (agMiscUtils:toBinary(JodId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 返回具有特定状态的工作结果ID +% GET /_api/job/{type}#by-type +% 路径参数 +% type（必填）：要返回的作业类型。类型可以是 done 的或 pending 的。将类型设置为done将使该方法返回可以获取其结果的异步作业的ID。将类型设置为pending将返回尚未完成的异步作业的ID。 +% 查询参数 +% count（可选）：每次调用返回的最大ID数。如果未指定，将使用服务器定义的最大值。 +% 返回具有特定状态（已完成或未决）的异步作业的ID列表。客户端可以使用该列表获取作业系统状态的概述，并在以后检索完成的作业结果。 +% 返回码 +% 200：如果列表可以成功编译，则返回。注意：该列表可能为空。 +% 400：如果未指定type或值无效，则返回。 +getAsyncJobList(PoolNameOrSocket, Type) -> + Path = <<"/_api/job/", (agMiscUtils:toBinary(Type))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +getAsyncJobList(PoolNameOrSocket, Type, Count) -> + Path = <<"/_api/job/", (agMiscUtils:toBinary(Type))/binary, "?count=", (agMiscUtils:toBinary(Count))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + diff --git a/src/agApi/agBulkImportExport.erl b/src/agApi/agBulkImportExport.erl new file mode 100644 index 0000000..1347e49 --- /dev/null +++ b/src/agApi/agBulkImportExport.erl @@ -0,0 +1,233 @@ +-module(agBulkImportExport). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/bulk-imports.html + +% 批量导入的HTTP接口 +% ArangoDB提供了一个HTTP接口，可以一次将多个文档导入一个集合中。这称为批量导入。 +% 上传的数据必须以JSON格式提供。有两种导入数据的机制： +% 自包含的JSON文档：在这种情况下，每个文档都包含所有属性名称和值。在上传的文档中，属性名称可能完全不同 +% 属性名称加上文档数据：在这种情况下，第一个数组必须包含后面文档的属性名称。以下数组仅包含属性值。属性值将按位置映射到属性名称。 +% 两种输入机制的端点地址均为/ _api / import。必须使用HTTP POST请求将数据发送到此URL。要导入的数据必须包含在POST请求的正文中。 +% 该集合的查询参数必须用于指定目标集合导入。将数据导入到不存在的集合中将产生错误。 +% 可以将waitForSync查询参数设置为true，以仅在所有文档都已同步到磁盘后才返回导入。 +% 如果任何上传的文档无效并且无法导入，可以将complete查询参数设置为true，以使整个导入失败。在这种情况下，即使在导入结束时发生故障，导入操作也不会导入任何文档。 +% 如果complete具有除true以外的其他值，则将导入有效文档，而拒绝无效文档，这意味着可能仅导入了一些上载文档。 +% 可以将details查询参数设置为true，以使导入API返回有关无法导入的文档的详细信息。如果details为true，则结果还将包含一个details属性，该属性是详细错误消息的数组。如果将详细信息设置为false或省略，则不会返回任何详细信息。 + +% 从JSON编码的列表中导入文档 +% POST /_api/import#document +% 查询参数 +% collection （必填）：集合名称。 +% fromPrefix（可选）：_from属性中值的可选前缀。如果指定，该值将自动添加到每个_from输入值之前。这样就可以仅指定的键_from。 +% toPrefix（可选）：_to属性中值的可选前缀。如果指定，该值将自动添加到每个_to输入值之前。这样就可以仅指定的键_to。 +% overwrite （可选）：如果此参数的值为true或yes，则将在导入之前删除集合中的所有数据。请注意，任何现有的索引定义都将保留。 +% waitForSync（可选）：等待文档同步到磁盘后再返回。 +% onDuplicate（可选）：控制在违反唯一键约束的情况下执行的操作。可能的值为： +% error：由于违反唯一键约束，因此不会导入当前文档。这是默认设置。 +% update：这将使用请求中指定的数据更新数据库中的现有文档。请求中不存在的现有文档的属性将被保留。 +% replace：这将用请求中指定的数据替换数据库中的现有文档。 +% ignore：这不会更新现有文档，而只是忽略由唯一键约束冲突引起的错误。 +% 请注意，仅当请求中的导入文档包含_key属性时，update，replace和ignore才起作用。由于次要唯一键约束冲突，更新和 替换也可能失败。 +% +% complete （可选）：如果设置为true或yes，则如果发生任何错误，将使整个导入失败。否则，即使无法导入某些文档，导入也将继续。 +% details（可选）：如果设置为true或yes，结果将包括一个属性，details 其中包含有关无法导入的文档的详细信息。 +% +% 请求正文（字符串） +% 主体必须由JSON编码的属性值数组组成，每个文档一行。请求的第一行必须是JSON编码的属性名称数组。这些属性名称用于后续各行中的数据。 +% 在由标识的集合中创建文档collection-name。请求正文的第一行必须包含一个JSON编码的属性名称数组。请求正文中的以下所有行都必须包含JSON编码的属性值数组。每行都被解释为一个单独的文档，并且指定的值将映射到在第一标题行中指定的属性名称的数组。 +% +% 响应是具有以下属性的JSON对象： +% created：导入的文件数。 +% errors：由于错误而未导入的文档数。 +% empty：在输入中找到的空行数（类型documents或只能包含大于零的值auto）。 +% updated：更新/替换的文档数（如果onDuplicate 设置为update或replace）。 +% ignored：失败但被忽略的插入操作数（如果 onDuplicate设置为ignore）。 +% details：如果查询参数details设置为true，则结果将包含一个details属性，该属性是一个数组，其中包含有关无法插入哪些文档的更多详细信息。 +% +% 返回码 +% 201：如果可以成功导入所有文档，则返回。 +% 400：如果type包含无效值，未collection指定no ，文档编码错误或请求格式错误，则返回。 +% 404：如果collection或导入边的_from或_to属性引用未知集合，则返回。 +% 409：如果导入会触发唯一键冲突，complete则返回，并将 其设置为true。 +% 500：如果服务器无法为没有用户定义密钥的文档自动生成文档密钥（密钥错误），则返回500。 +docImport(PoolNameOrSocket, ListOfList, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/import", QueryBinary/binary>>, + BodyStr = <<<<(jiffy:encode(OneList))/binary, "\n">> || OneList <- ListOfList>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +% 从JSON导入文档 +% POST /_api/import#json +% 查询参数 +% type （必填）：确定如何解释请求的正文。type可以具有以下值： +% documents：使用此类型时，请求正文中的每一行都应为单独的JSON编码的文档。请求主体中的多个JSON对象需要用换行符分隔。 +% list：使用此类型时，请求主体必须包含要导入的单个对象的单个JSON编码数组。 +% auto：如果设置，它将自动确定主体类型（ documents或list）。 +% collection （必填）：集合名称。 +% fromPrefix（可选）：_from属性中值的可选前缀。如果指定，该值将自动添加到每个_from输入值之前。这样就可以仅指定的键_from。 +% toPrefix（可选）：_to属性中值的可选前缀。如果指定，该值将自动添加到每个_to输入值之前。这样就可以仅指定的键_to。 +% overwrite （可选）：如果此参数的值为true或yes，则将在导入之前删除集合中的所有数据。请注意，任何现有的索引定义都将保留。 +% waitForSync（可选）：等待文档同步到磁盘后再返回。 +% onDuplicate（可选）：控制在违反唯一键约束的情况下执行的操作。可能的值为： +% error：由于违反唯一键约束，因此不会导入当前文档。这是默认设置。 +% update：这将使用请求中指定的数据更新数据库中的现有文档。请求中不存在的现有文档的属性将被保留。 +% replace：这将用请求中指定的数据替换数据库中的现有文档。 +% ignore：这不会更新现有文档，而只是忽略由唯一键约束冲突引起的错误。 +% 请注意，仅当请求中的导入文档包含_key属性时，update，replace和ignore才起作用。由于次要唯一键约束冲突，更新和 替换也可能失败。 +% complete （可选）：如果设置为true或yes，则如果发生任何错误，将使整个导入失败。否则，即使无法导入某些文档，导入也将继续。 +% details（可选）：如果设置为true或yes，结果将包括一个属性，details 其中包含有关无法导入的文档的详细信息。 +% 请求正文（字符串） +% 主体必须是JSON编码的对象数组，或者是包含多个以换行符分隔的JSON对象的字符串。 +% 在由标识的集合中创建文档collection-name。文档的JSON表示形式必须作为POST请求的主体传递。请求主体可以由多行组成，每行都是一个独立的JSON对象，也可以是包含子对象的JSON数组。 +% +% 响应是具有以下属性的JSON对象： +% created：导入的文件数。 +% errors：由于错误而未导入的文档数。 +% empty：在输入中找到的空行数（类型documents或只能包含大于零的值auto）。 +% updated：更新/替换的文档数（如果onDuplicate 设置为update或replace）。 +% ignored：失败但被忽略的插入操作数（如果 onDuplicate设置为ignore）。 +% details：如果查询参数details设置为true，则结果将包含一个details属性，该属性是一个数组，其中包含有关无法插入哪些文档的更多详细信息。 +% 返回码 +% 201：如果可以成功导入所有文档，则返回。 +% 400：如果type包含无效值，未collection指定no ，文档编码错误或请求格式错误，则返回。 +% 404：如果collection或导入边的_from或_to属性引用未知集合，则返回。 +% 409：如果导入会触发唯一键冲突，complete则返回，并将 其设置为true。 +% 500：如果服务器无法为没有用户定义密钥的文档自动生成文档密钥（密钥错误），则返回500。 +jsonImport(PoolNameOrSocket, MapDataList, QueryPars) -> + case lists:keyfind(type, 1, QueryPars) of + {type, list} -> + BodyStr = jiffy:encode(MapDataList); + {type, documents} -> + BodyStr = <<<<(jiffy:encode(OneList))/binary, "\n">> || OneList <- MapDataList>>; + _ -> + BodyStr = MapDataList + end, + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/import", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +% 说明-------> +% 导入自包含的JSON文档 +% 此导入方法允许上传自包含的JSON文档。这些文档必须上传到HTTP POST请求的正文中。正文的每一行都将被解释为一个独立文档。正文中的空行是允许的，但将被跳过。使用此格式，文档将逐行导入。 +% +% 输入数据示例：{“ _key”：“ key1”，……} {“ _key”：“ key2”，……}… +% +% 要使用此方法，应将类型查询参数设置为documents。 +% +% 还可以上传嵌入到JSON数组中的自包含JSON文档。数组中的每个元素都将被视为文档并导入。 +% +% 这种情况下的示例输入数据： +% +% [ +% { "_key": "key1", ... }, +% { "_key": "key2", ... }, +% ... +% ] +% 此格式不需要每个文档都位于单独的行上，并且JSON数据中允许使用任何空格。它可以用于将JSON格式的结果数组（例如，从arangosh中）导入回ArangoDB中。使用此格式需要ArangoDB解析整个数组，并在导入期间将其保留在内存中。这可能比逐行处理要消耗更多的资源。 +% +% 要使用此方法，类型查询参数应设置为array。 +% +% 将类型查询参数设置为auto将使服务器自动检测数据是按行的JSON文档（类型=文档）还是JSON数组（类型=数组）。 +% +% 例子 +% +% curl --data-binary @- -X POST --dump - "http://localhost:8529/_api/import?type=documents&collection=test" +% { "name" : "test", "gender" : "male", "age" : 39 } +% { "type" : "bird", "name" : "robin" } +% +% HTTP/1.1 201 Created +% Server: ArangoDB +% Connection: Keep-Alive +% Content-type: application/json; charset=utf-8 +% +% {"error":false,"created":2,"empty":0,"errors":0} +% 如果一切顺利，服务器将以HTTP 201响应。导入的文档数将在响应的创建的属性中返回。如果任何文档被跳过或格式错误，将在errors属性中返回该文档。响应中还将有一个空属性，其中包含值为0。 +% +% 如果在请求中将details参数设置为true，则响应还将包含一个属性details，该属性是有关导入期间在服务器端发生的错误的详细信息的数组。如果没有发生错误，则此数组可能为空。 + +% 导入标题和值 +% 使用这种类型的导入时，要与实际文档值数据分开指定要导入的文档的属性名称。HTTP POST请求正文的第一行必须是JSON数组，其中包含后面文档的属性名称。以下各行被解释为文档数据。每个文档必须是值的JSON数组。此数据部分中不需要或不允许属性名称。 +% 例子 +% curl --data-binary @- -X POST --dump - "http://localhost:8529/_api/import?collection=test" +% [ "firstName", "lastName", "age", "gender" ] +% [ "Joe", "Public", 42, "male" ] +% [ "Jane", "Doe", 31, "female" ] +% +% HTTP/1.1 201 Created +% Server: ArangoDB +% Connection: Keep-Alive +% Content-type: application/json; charset=utf-8 +% +% {"error":false,"created":2,"empty":0,"errors":0} +% 如果一切顺利，服务器将再次以HTTP 201响应。导入的文档数将在响应的创建的属性中返回。如果任何文档被跳过或格式错误，将在errors属性中返回该文档。输入文件中的空行数将在empty属性中返回。 +% +% 如果在请求中将details参数设置为true，则响应还将包含一个属性details，该属性是有关导入期间在服务器端发生的错误的详细信息的数组。如果没有发生错误，则此数组可能为空。 +% +% 导入到边缘集合 +% 请注意，将文档导入 边缘集合时，必须强制所有导入的文档都包含_from和_to属性，并且这些属性必须包含对现有集合的引用。 + +% 批处理请求的HTTP接口 +% 客户端通常在单独的HTTP请求中向ArangoDB发送单独的操作。这是直接且简单的，但是具有以下缺点：如果连续发出许多小请求，则网络开销可能会很大。 +% 为了缓解此问题，ArangoDB提供了一个批处理请求API，客户端可以使用该API批量向ArangoDB发送多个操作。当客户端必须以较小的正文/有效负载发送许多HTTP请求并且各个请求的结果彼此不依赖时，此方法特别有用。 +% 客户端可以通过向URL / _api / batch处理程序发出多部分HTTP POST请求来使用ArangoDB的批处理API 。如果Content-type为multipart / form-data，则处理程序将接受请求并指定边界字符串。然后，ArangoDB将使用此边界将批处理请求分解为各个部分。这也意味着边界字符串本身不能包含在任何部分中。当ArangoDB将多部分请求分为其各个部分时，它将按顺序处理所有部分，就好像它是一个独立的请求一样。处理完所有零件后，ArangoDB将生成一个多部分HTTP响应，其中每个零件操作结果都包含一个零件。例如，如果您发送包含5个部分的多部分请求，则ArangoDB还将发送包含5个部分的多部分响应。 +% 服务器希望每个零件消息均以以下“头”开头： +% Content-type: application/x-arango-batchpart +% 您可以选择指定Content-Id “标头”以唯一标识每个零件消息。如果已指定，服务器将在其响应中返回Content-Id。否则，服务器将不会发回Content-Id“标头”。服务器将不会验证Content-Id的唯一性。在强制性Content-type和可选Content-Id标头之后，必须紧跟两个Windows换行符（即\ r \ n \ r \ n）。该结构的任何偏差都可能导致零件被拒绝或错误解释。零件请求有效载荷（格式为常规HTTP请求）必须直接遵循两个Windows换行符。 +% 请注意，从 技术上来说，文字Content-type：application / x-arango-batchpart是MIME部分的标头，而HTTP请求（包括其标头）是MIME部分的正文部分。 +% 实际的零件请求应以通常的HTTP方法，被调用的URL和HTTP协议版本开头，后跟任意的HTTP标头。它的主体应遵循通常的\ r \ n \ r \ n 文字。因此，部分请求是常规的HTTP请求，仅嵌入在多部分消息中。 +% 以下示例将发送具有3个单独文档创建操作的批处理。在此示例中使用的边界是 XXXsubpartXXX。 +% ******************************************************************* +% 批处理请求的HTTP接口 改功能不予实现支持 +% ******************************************************************* + +% 使用光标导出集合中的所有文档 +% POST /_api/export +% 查询参数 +% collection （必填）：要导出的集合的名称。 +% 具有以下属性的JSON对象是必需的： +% flush：如果设置为true，则将在导出之前执行WAL刷新操作。刷新操作将开始将文档从WAL复制到集合的数据文件中。刷新后还会有最长为flushWait秒的额外等待时间，以使WAL收集器也可以更改调整后的文档元数据以指向数据文件。默认值为false（即不刷新），因此导出中可能缺少集合中最新插入或更新的文档。 +% flushWait：刷新操作后的最大等待时间（以秒为单位）。默认值为10。仅当flush设置为true时，此选项才有效。 +% count：布尔值标志，指示是否应在结果的“ count”属性中返回结果集中的文档数（可选）。计算“ count”属性将来可能会对性能产生影响，因此默认情况下将关闭此选项，并且仅在请求时才返回“ count”。 +% batchSize：一次往返（从服务器到客户端）要传输的最大结果文档数（可选）。如果未设置此属性，则将使用服务器控制的默认值。 +% limit：可选的限制值，确定要包含在光标中的最大文档数。省略limit属性或将其设置为0将导致不使用任何限制。如果使用限制，则不确定集合中的哪些文档将包含在导出中，哪些文档将排除在外。这是因为集合中没有自然的文档顺序。 +% ttl：光标的可选生存时间（以秒为单位）。在指定的时间后，游标将自动在服务器上删除。这对于确保客户端不完全获取的游标的垃圾回收很有用。如果未设置，将使用服务器定义的值。 +% restrict：包含以下属性的对象，返回结果文档时将包含或排除这些属性名称。默认情况下，不指定 限制将返回每个文档的所有属性。 +% type：必须根据要使用的类型设置为 include or exclude +% fields：包含要包含或排除的属性名称的数组。包含或排除属性名称的匹配将仅在顶层完成。目前不支持指定嵌套属性的名称。 +% 对此方法的调用将创建一个游标，其中包含指定集合中的所有文档。与其他数据生成API相比，导出API生成的内部数据结构更轻便，因此这是从集合中检索所有文档的首选方法。 +% 以与/_api/cursorREST API中相似的方式返回文档。如果集合的所有文档都适合第一批，则不会创建任何游标，并且结果对象的hasMore属性将设置为 false。如果不是所有文档都适合第一批文档，则结果对象的hasMore属性将设置为true，并且结果的id属性将包含游标id。 +% 未指定文件退回的顺序。 +% +% 默认情况下，将仅返回集合中存储在集合数据文件中的那些文档。运行导出时在预写日志（WAL）中存在的文档将不会导出。 +% 为了也导出这些文档，调用者可以在调用导出API或设置flush属性之前发出WAL刷新请求。设置冲洗 选项将在导出之前触发WAL冲洗，以便将文档从WAL复制到集合数据文件。 +% 如果服务器可以创建结果集，则服务器将使用HTTP 201进行响应 。响应的主体将包含带有结果集的JSON对象。 +% 返回的JSON对象具有以下属性： +% error：布尔值标志，指示发生错误（ 在这种情况下为false） +% code：HTTP状态码 +% result：结果文档数组（如果集合为空，则可能为空） +% hasMore：一个布尔指示器，指示服务器上的光标是否还有更多结果可用 +% count：可用结果文档总数（仅当查询是在设置了count属性的情况下执行的） +% id：在服务器上创建的临时光标的ID（可选，请参见上文） +% 如果JSON格式不正确或请求中缺少查询规范，则服务器将使用HTTP 400进行响应。 +% 响应的主体将包含带有其他错误详细信息的JSON对象。该对象具有以下属性： +% error：布尔值标志，指示发生错误（在这种情况下为true） +% code：HTTP状态码 +% errorNum：服务器错误号 +% errorMessage：描述性错误消息 +% 客户端应该始终尽早删除导出游标结果，因为缠结的导出游标会阻止基础集合被压缩或卸载。默认情况下，未使用的游标将在服务器定义的空闲时间后自动删除，并且客户端可以通过设置ttl值来调整此空闲时间。 +% 注意：群集协调器当前不支持此API。 +% 返回码 +% 201：如果服务器可以创建结果集，则返回。 +% 400：如果JSON表示格式错误或请求中缺少查询规范，则返回。 +% 404：如果查询中访问了不存在的集合，服务器将以HTTP 404进行响应。 +% 405：如果使用了不受支持的HTTP方法，则服务器将以HTTP 405进行响应。 +% 501：如果在群集协调器上调用此API，则服务器将使用HTTP 501进行响应。 +docExport(PoolNameOrSocket, CollName, MapData) -> + Path = <<"/_api/export?collection=", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). \ No newline at end of file diff --git a/src/agApi/agCluster.erl b/src/agApi/agCluster.erl new file mode 100644 index 0000000..b2eb8fe --- /dev/null +++ b/src/agApi/agCluster.erl @@ -0,0 +1,107 @@ +-module(agCluster). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +%% doc_address:https://www.arangodb.com/docs/stable/http/cluster.html + +% 集群的HTTP接口 +% 本章介绍了ArangoDB群集的REST API。 +% 服务器ID +% 服务器角色 +% 集群统计 +% 集群健康 +% 集群维护 +% 机构 +% 如何修复与坏簇distributeShardsLike集在描述修理章节。 + + +% 了解服务器的内部ID +% GET /_admin/server/id +% 返回集群中服务器的ID。如果服务器未在集群模式下运行，则请求将失败。 +% 返回码 +% 200：当服务器以群集模式运行时返回。 +% 500：当服务器未在群集模式下运行时返回。 +serverId(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/server/id">>, [], undefined). + +% 返回集群中服务器的角色 +% GET /_admin/server/role +% 返回集群中服务器的角色。该角色在结果的role属性中返回。角色的可能返回值是： +% SINGLE：服务器是没有集群的独立服务器 +% COORDINATOR：服务器是集群中的协调器 +% PRIMARY：服务器是集群中的DB-Server +% SECONDARY：不再使用此角色 +% AGENT：服务器是集群中的代理节点 +% UNDEFINED：在集群中，如果无法确定服务器角色，则返回UNDEFINED。 +% 在所有情况下均返回HTTP 200。 +% error：始终为假 +% code：HTTP状态码，始终为200 +% errorNum：服务器错误号 +% role：之一[ SINGLE，COORDINATOR，PRIMARY，SECONDARY，AGENT，UNDEFINED ] +serverRole(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/server/role">>, [], undefined). + +% 数据库服务器的查询统计信息 +% 允许查询集群中DB-Server的统计信息 +% GET /_admin/clusterStatistics +% 查询参数 +% DBserver（必填）：查询给定DB-Server的统计信息 +% 返回码 +% 200： +% 400：数据库服务器的ID +% 403： +clusterStats(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/clusterStatistics", QueryBinary/binary>>, [], undefined). + +% 返回监督（机构）评估的集群的运行状况 +% GET /_admin/cluster/health +% 查询群集的运行状况以进行监视。该响应是一个JSON对象，包含标准code，error，errorNum，和errorMessage字段适当。特定于端点的字段如下： +% ClusterId：标识集群的UUID字符串 +% Health：一个对象，该对象包含群集中每个节点的描述性子对象。 +% ：中的每个条目Health将由节点ID键入，并包含以下属性： +% Endpoint：代表服务器网络端点的字符串。 +% Role：服务器扮演的角色。可能的值是"AGENT"，"COORDINATOR"和"DBSERVER"。 +% CanBeDeleted：布尔值，表示是否可以安全地从群集中删除节点。 +% Version：该节点使用的ArangoDB的版本字符串。 +% Engine：该节点使用的存储引擎。 +% Status：指示监督（机构）评估的节点运行状况的字符串。对于协调器和DB-Servers节点运行状况，应将其视为真实的主要来源。如果节点正常响应请求，则为"GOOD"。如果错过了一个心跳，那就是"BAD"。如果在缺少心跳约15秒钟后通过监督宣布它失败，则会对其进行标记"FAILED"。 +% 此外，它还将具有以下属性： +% 协调器和数据库服务器 +% SyncStatus：节点上次报告的同步状态。该值主要用于确定的值Status。可能的值包括"UNKNOWN"，"UNDEFINED"，"STARTUP"，"STOPPING"，"STOPPED"，"SERVING"，"SHUTDOWN"。 +% LastAckedTime：ISO 8601时间戳记，指定接收到的最后一个心跳。 +% ShortName：代表服务器的简称的字符串，例如"Coordinator0001"。 +% Timestamp：ISO 8601时间戳记，指定接收到的最后一个心跳。（已弃用） +% Host：可选字符串，指定主机（如果已知）。 +% 仅协调员 +% AdvertisedEndpoint：表示已播报端点的字符串（如果已设置）。（例如，外部IP地址或负载平衡器，可选） +% 代理商 +% Leader：此节点视为领导者的代理的ID。 +% Leading：此座席是否为领导者（true）或不是（false）。 +% LastAckedTime：自上次以来的时间（acked以秒为单位）。 +% 返回码 +% 200： +clusterHealth(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_admin/cluster/health">>, [], undefined). + +% 启用或禁用集群监督（代理）维护模式 +% PUT /_admin/cluster/maintenance +% 通过此API，您可以临时启用监督维护模式。请注意，启用维护模式后，不会进行任何类型的自动故障转移。该集群监控会自动重新激活自身60分钟禁用后。 +% 要启用维护模式，请求正文必须包含字符串"on"。要禁用它，请发送字符串"off"（请注意，该字符串 必须为小写并包括引号）。 +% 返回码 +% 200： +% 400： +% 501： +% 504： +setClusterMaintenance(PoolNameOrSocket, OnOrOff) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, <<"/_admin/cluster/maintenance">>, [], OnOrOff). + +%%%%%%%%%%%%%%% Agency ?????????????????????????? + + + + + diff --git a/src/agApi/agCollections.erl b/src/agApi/agCollections.erl new file mode 100644 index 0000000..4746d22 --- /dev/null +++ b/src/agApi/agCollections.erl @@ -0,0 +1,482 @@ +-module(agCollections). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/collection.html + +% 集合的HTTP接口 +% 这是ArangoDB集合的HTTP接口的简介。 +% +% 收藏 +% 集合由文档组成。它由其集合标识符唯一 标识。它也有一个唯一的名称，客户端应该使用它来标识和访问它。集合可以重命名。这将更改集合名称，但不会更改集合标识符。集合具有创建集合时用户指定的类型。当前有两种类型：文档和边。默认类型是document。 +% +% 集合标识符 +% 集合标识符使您可以引用数据库中的集合。它是一个字符串值，在数据库中是唯一的。直到包括ArangoDB 1.1为止，集合标识符一直是客户端访问集合的主要手段。从ArangoDB 1.2开始，客户端应改为使用集合的唯一名称访问集合，而不是其标识符。ArangoDB当前使用64位无符号整数值在内部维护集合ID。当将集合ID返回给客户端时，ArangoDB会将它们放入字符串中，以确保不支持不支持大整数的客户端不截取集合ID。客户端在本地存储或使用它们时，应将ArangoDB返回的集合ID视为不透明字符串。 +% +% 注意：集合ID已返回为整数，包括ArangoDB 1.1在内 +% +% 集合名称 +% 集合名称标识数据库中的集合。它是一个字符串，在数据库中是唯一的。与集合标识符不同，它由集合的创建者提供。集合名称必须仅由字母，数字和_（下划线）和-（破折号）字符组成。有关有效集合名称的更多信息，请参考ArangoDB中的命名约定。 +% +% 密钥生成器 +% ArangoDB允许为每个集合使用密钥生成器。如果用户未指定键生成器，则其目的是为文件的_key属性自动生成值。默认情况下，ArangoDB将使用传统的密钥生成器。传统的密钥生成器将自动生成数字不断增加的字符串形式的密钥值。它使用的增量值是不确定的。 +% +% 相反，自动递增密钥生成器将自动生成确定性密钥值。创建集合时，可以定义起始值和增量值。默认起始值​​为0，默认增量为1，这意味着它将默认创建的键值为： +% +% 1，2，3，4，5，… +% +% 使用自动增量键生成器并以5增量创建集合时，生成的键将为： +% +% 1，6，11，16，21，… +% +% 自动增量值会增加，并在每次插入文档时分发。即使插入失败，也不会回滚自动增量值。这意味着，如果插入失败，则在分配的自动增量值序列中可能存在间隙。 +% +% 文档的基本操作（创建，读取，更新，删除）被映射到标准HTTP方法（POST，GET，PUT，DELETE）。 +% +% 集合地址 +% ArangoDB中的所有集合都具有唯一的标识符和唯一的名称。ArangoDB在内部使用集合的唯一标识符来查找集合。但是，此标识符由ArangoDB管理，并且用户无法对其进行控制。为了允许用户使用自己的名称，每个集合还具有一个由用户指定的唯一名称。要从用户角度访问集合，应使用集合名称，即： +% +% http://server:port/_api/collection/collection-name +% 例如：假设集合标识符为7254820，集合名称为demo，则该集合的URL为： +% +% http://localhost:8529/_api/collection/demo + + +%创建一个集合 +%POST /_api/collection +% +%查询参数 +% waitForSyncReplication（可选）：默认为1，这意味着如果所有副本都创建了集合，则服务器将仅向客户端报告成功。如果您想要更快的服务器响应并且不关心完全复制，则设置为0。 +% forceReplicationFactor（可选）：默认值为1，这意味着服务器将在创建时检查是否有足够的副本，否则将进行紧急救助。设置为0可禁用此额外检查。 +% +%具有以下属性的JSON对象是必需的： +% name：集合的名称。 +% waitForSync：如果为true，则在从文档创建，更新，替换或删除操作返回之前，将数据同步到磁盘。（默认值：false） +% doCompact：是否压缩集合（默认为true），此选项仅对MMFiles存储引擎有意义。 +% journalSize：日志或数据文件的最大大小，以字节为单位。该值必须至少为1048576（1 MiB）。（默认值为配置参数）此选项仅对MMFiles存储引擎有意义。 +% isSystem：如果为true，则创建一个系统集合。在这种情况下，collection-name 应该以下划线开头。最终用户通常应仅创建非系统集合。在非常特殊的情况下，可能需要API实现者来创建系统集合，但通常会使用常规集合。（默认为false） +% isVolatile：如果为true，则收集数据仅保留在内存中，而不是持久的。卸载集合将导致集合数据被丢弃。停止或重新启动服务器也将导致集合中的数据完全丢失。设置此选项将使结果集合比常规集合快一点，因为ArangoDB不会对磁盘​​执行任何同步，也不会为数据文件计算任何CRC校验和（因为没有数据文件）。因此，此选项应仅用于高速缓存类型的集合，而不应用于无法通过其他方式重新创建的数据。（默认值为false）此选项仅对MMFiles存储引擎有意义。 +% schema：指定文档的收集级别架构的可选对象。属性键rule，level并且message必须遵循文档架构验证中记录的规则 +% keyOptions：密钥生成的其他选项。如果指定，则keyOptions 应该是包含以下属性的JSON数组或者JSON对象： +% type：指定密钥生成器的类型。当前可用的生成器是 传统的，自动递增的，uuid的和填充的。 +% 在传统的密钥生成器生成升序数字键。在自动增量密钥发生器以上升顺序生成的数字键时，初始偏移量和间隔可以被配置成在填充密钥发生器以上升辞书排序顺序生成的固定长度（16个字节）的密钥。这是与RocksDB配合使用的理想选择 引擎，这将稍微有利于按字典顺序升序插入的键。密钥生成器可以在单服务器或群集中使用。的UUID密钥生成器生成通用唯一的128位密钥，这被存储在十六进制人类可读的格式。该密钥生成器可用于单服务器或群集中，以生成“看似随机的”密钥。此密钥生成器生成的密钥未按字典顺序排序。 +% allowUserKeys：如果设置为true，则允许在文档的_key属性中提供自己的键值 。如果设置为false，那么密钥生成器将仅负责生成密钥，并且在文档的_key属性中提供自己的密钥值被视为错误。 +% 增量：自动增量密钥生成器的增量值。不适用于其他密钥生成器类型。 +% offset：自动增量密钥生成器的初始偏移值。不适用于其他密钥生成器类型。 +% type：（默认值为2）：要创建的集合的类型。以下type值有效： +% 2：文件收集 +% 3：边缘收集 +% numberOfShards：（默认值为1）：在集群中，此值确定要为集合创建的分片数。在单服务器设置中，此选项没有意义。 +% shardKeys：（默认值为[“ _key”]）：在集群中，此属性确定用于确定文档目标分片的文档属性。文档根据其分片键属性的值发送到分片。对文档中所有分片键属性的值进行哈希处理，并将哈希值用于确定目标分片。 注意：分片键属性的值一旦设置就无法更改。在单个服务器设置中，此选项没有意义。 +% plicationFactor：（默认值为1）：在集群中，此属性确定每个分片在不同DB-Server上保留多少个副本。值1表示仅保留一个副本（无同步复制）。k的值表示保留k-1个副本。它也可以"satellite"是SatelliteCollection 的字符串，其中复制因子与DB-Servers的数量匹配。 +% 任何两个副本驻留在不同的DB服务器上。它们之间的复制是同步的，也就是说，在报告写入操作成功之前，对“ leader”副本的每个写入操作都会复制到所有“ follower”副本。 +% 如果服务器发生故障，则会自动检测到故障，并且其中一台拥有副本的服务器将接管业务，通常不会报告错误。 +% writeConcern：为此集合写关注点（默认值：1）。它确定在不同的DB服务器上同步每个分片需要多少个副本。如果集群中的副本数量很少，那么分片将拒绝写入。但是，具有足够最新副本的分片写入将同时成功。writeConcern的值 不能大于ReplicationFactor。（仅集群） +% DistributionShardsLike：（默认值为“”）：在企业版集群中，此属性将新创建的集合的分片详细信息绑定到指定的现有集合中。 注意：使用此参数会对原型集合产生影响。在删除分片模仿集合之前，不能再删除它。同样，仅模拟集合的备份和还原将生成有关丢失分片原型的警告（可以被覆盖）。 +% shardingStrategy：此属性指定用于集合的分片策略的名称。从ArangoDB 3.4开始，创建新集合时可以选择不同的分片策略。所选的shardingStrategy 值对于集合将保持固定，此后无法更改。这对于使集合保持其分片设置并始终使用相同的初始分片算法查找已分发到分片的文档非常重要。 +% 可用的分片策略为： +% community-compat：版本3.4之前的ArangoDB社区版使用的默认分片 +% enterprise-compat：版本3.4之前的ArangoDB企业版使用的默认分片 +% enterprise-smart-edge-compat：版本3.4之前的ArangoDB Enterprise Edition中的智能边缘集合使用的默认分片 +% hash：从3.4版开始用于新集合的默认分片（不包括智能边缘集合） +% enterprise-hash-smart-edge：从版本3.4开始，用于新的智能边缘集合的默认分片 +% 如果未指定分片策略，则所有集合的默认值将为哈希，所有智能边缘集合的默认值将为enterprise-hash-smart-edge（需要ArangoDB 企业版）。手动覆盖分片策略尚不能提供好处，但是稍后可能会添加其他分片策略。 +% smartJoinAttribute：在企业版集群中，此属性确定集合的属性，该属性必须包含引用的SmartJoin集合的分片键值。此外，此集合中文档的分片键必须包含此属性的值，后跟冒号，然后是文档的实际主键。 +% 此功能只能在企业版中使用，并且需要将集合的 distributedShardsLike属性设置为另一个集合的名称。它还要求将集合的shardKeys属性设置为单个shard key属性，并在末尾添加一个附加的“：”。进一步的限制是，无论何时在集合中存储或更新文档，smartJoinAttribute中存储的值都必须是字符串。 +% 用给定名称创建一个新集合。该请求必须包含具有以下属性的对象。 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则返回HTTP 404。 +% HTTP 200 + +newColl(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, <<"/_api/collection">>, [], BodyStr). + +newColl(PoolNameOrSocket, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/collection", QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +% 删除收藏 +% DELETE /_api/collection/{collection-name} +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必填）：要删除的集合的名称。 +% 查询参数 +% isSystem（可选）：要删除的集合是否为系统集合。必须将此参数设置为true才能删除系统集合。 +% 删除由collection-name标识的集合。 +% 如果成功删除了该集合，则返回具有以下属性的对象： +% 错误：假 +% id：删除的集合的标识符。 +% 返回码 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则返回HTTP 404。 +delColl(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delColl(PoolNameOrSocket, CollName, IsSystem) -> + case IsSystem of + true -> + Path = <<"/_api/collection/", CollName/binary, "?isSystem=true">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined); + _ -> + Path = <<"/_api/collection/", CollName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined) + end. + +% 清除集合 +% PUT /_api/collection/{collection-name}/truncate +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必填）：集合的名称。 +% 从集合中删除所有文档，但保留索引不变。 +% 返回码 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则 返回HTTP 404。 +clearColl(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary, "/truncate">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], undefined). + +% 返回有关集合的信息 +% GET /_api/collection/{collection-name} +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必填）：集合的名称。 +% 结果是一个对象，该对象描述具有以下属性的集合： +% id：集合的标识符。 +% name：集合的名称。 +% status：集合状态为数字。 +% 1：新出生的收藏 +% 2：已卸载 +% 3：已加载 +% 4：在卸载过程中 +% 5：已删除 +% 6：加载 +% 其他每个状态都表示集合已损坏。 +% type：集合的类型，以数字表示。 +% 2：文件收集（正常情况） +% 3：边缘收集 +% isSystem：如果为true，则该集合为系统集合。 +% 返回码 +% 404：如果集合名称未知，则返回HTTP 404。 +collInfo(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + + +% 读取指定集合的属性 +% GET /_api/collection/{collection-name}/properties +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必填）：集合的名称。 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则 返回HTTP 404。 +% HTTP 200 +collProps(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", (CollName)/binary, "/properties">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 计算集合中的文档数量 +% GET /_api/collection/{collection-name}/count +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必填）：集合的名称。 +% 除上述内容外，结果还包含文档数。 请注意，这将始终将集合加载到内存中。 +% count：集合内的文档数。 +% 返回码 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则 返回HTTP 404。 +collCount(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary, "/count">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 获取集合的统计信息 +% GET /_api/collection/{collection-name}/figures +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必填）：集合的名称。 +% 除上述内容外，结果还包含文档数量和有关集合的其他统计信息。 +% HTTP 200返回有关集合的信息： +% count：集合中当前存在的文档数。 +% figures：收集指标 +% indexes： +% count：为集合定义的索引总数，包括预定义的索引（例如主索引）。 +% size：为索引分配的总内存，以字节为单位。 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则 返回HTTP 404。 +collFigures(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary, "/figures">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 返回负责文档的分片 +% PUT /_api/collection/{collection-name}/responsibleShard +% 路径参数 +% collection-name（必填）：集合的名称。 +% 请求正文（json） +% 主体必须包含一个JSON对象，且至少将分片键属性设置为某些值。 +% 返回负责给定文档（如果存在）或如果存在该文档将负责的分片的ID。 +% 该请求必须正文必须包含一个JSON文档，该文档至少将集合的分片键属性设置为某些值。 +% 响应是一个具有shardId属性的JSON对象，其中将包含负责的分片的ID。 +% 注意：此方法仅在群集协调器中可用。 +% 返回码 +% 200：返回负责的分片的ID。 +% 400：如果缺少集合名称，则返回HTTP 400。另外，如果输入文档中不存在所有集合的分片键属性，那么 也会返回HTTP 400。 +% 404：如果集合名称未知，则 返回HTTP 404。 +% 501：如果在单个服务器上调用该方法，则返回HTTP 501。 +% eg: MapData = #{'_key' => testkey, value => 23} +collResponsibleShard(PoolNameOrSocket, CollName, MapData) -> + Path = <<"/_api/collection/", CollName/binary, "/responsibleShard">>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], BodyStr). + +% 返回集合的分片ID +% GET /_api/collection/{collection-name}/shards +% 路径参数 +% collection-name（必填）：集合的名称。 +% 查询参数 +% 详细信息（可选）：如果设置为true，则返回值还将包含集合碎片的负责服务器。 +% 默认情况下，返回带有集合的分片ID的JSON数组。 +% 如果details参数设置为true，它将返回一个以分片ID作为对象属性键的JSON对象，并将每个分片的负责服务器映射到它们。在详细的响应中，领导者碎片将排在阵列的首位。 +% 注意：此方法仅在群集协调器中可用。 +% 返回码 +% 200：返回集合的分片。 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则 返回HTTP 404。 +% 501：如果在单个服务器上调用该方法，则返回HTTP 501。 +collShards(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary, "/shards">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +collShards(PoolNameOrSocket, CollName, IsDetails) -> + case IsDetails of + true -> + Path = <<"/_api/collection/", CollName/binary, "/shards?details=true">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined); + _ -> + Path = <<"/_api/collection/", CollName/binary, "/shards">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined) + end. + +% 返回集合修订版ID +% GET /_api/collection/{collection-name}/revision +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必填）：集合的名称。 +% 除上述内容外，结果还将包含集合的修订版ID。修订ID是服务器生成的字符串，客户端可以使用该字符串检查自上次修订检查以来集合中的数据是否已更改。 +% revision：集合修订版本ID的字符串形式。 +% 返回码 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则 返回HTTP 404。 +collRev(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary, "/revision">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 返回指定集合的校验和 +% GET /_api/collection/{collection-name}/checksum +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必填）：集合的名称。 +% 查询参数 +% withRevisions（可选）：在校验和计算中是否包括文档修订版ID。 +% withData（可选）：是否在校验和计算中包括文档主体数据。 +% 将计算集合中元数据（键和可选的修订ID）以及文档数据的校验和。 +% 校验和可用于比较不同ArangoDB实例上的两个集合是否包含相同的内容。集合的当前修订版也会返回，因此可以确保针对相同数据状态计算校验和。 +% 默认情况下，校验和将仅根据集合中包含的文档的_key系统属性来计算。对于边缘集合，系统属性_from和_to也将包含在计算中。 +% 通过将可选查询参数withRevisions设置为true，则校验和中将包含修订版ID（_rev系统属性）。 +% 通过为可选查询参数withData提供值为true的值，用户定义的文档属性也将包括在计算中。 注意：包括用户定义的属性将使校验和变慢。 +% 响应是具有以下属性的JSON对象： +% checksum：计算得出的校验和（以数字形式）。 +% 版本：集合修订版本ID的字符串形式。 +% 注意：此方法在群集中不可用。 +% 返回码 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则 返回HTTP 404。 +collChecksum(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary, "/checksum">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +collChecksum(PoolNameOrSocket, CollName, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/collection/", CollName/binary, "/checksum", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 返回所有集合列表 +% GET /_api/collection +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 查询参数 +% excludeSystem（可选）：是否应从结果中排除系统集合。 +% 返回带有属性集合的对象，该属性集合包含所有集合描述的数组。在名称中还可以使用对象作为对象，在集合名称中作为键使用相同的信息。 +% 通过为可选查询参数excludeSystem提供值为true的值， 将从响应中排除所有系统集合。 +% 返回码 +% 200：收藏列表 +collList(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/collection">>, [], undefined). + +collList(PoolNameOrSocket, IsExcludeSystem) -> + case IsExcludeSystem of + false -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/collection">>, [], undefined); + _ -> + Path = <<"/_api/collection?excludeSystem=true">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined) + end. + +% 加载集合 +% PUT /_api/collection/{collection-name}/load +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必填）：集合的名称。 +% 将集合加载到内存中。成功返回集合。 +% 请求主体对象可以选择包含以下属性： +% count：如果设置，则控制返回值是否应包括集合中的文档数。将count设置为 false可以加快加载集合的速度。为默认值 数为真。 +% 成功后，将返回具有以下属性的对象： +% id：集合的标识符。 +% name：集合的名称。 +% count：集合内的文档数。仅当count输入参数设置为true或未指定时才返回。 +% status：集合状态为数字。 +% type：集合类型。有效类型为： +% 2：文件收集 +% 3：边缘收集 +% isSystem：如果为true，则该集合为系统集合。 +% 返回码 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则 返回HTTP 404。 +loadColl(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary, "/load">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], undefined). + +loadColl(PoolNameOrSocket, CollName, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, <<"/_api/collection/", CollName/binary, "/load">>, [], BodyStr). + +% 卸载集合 +% PUT /_api/collection/{collection-name}/unload +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必需）：从内存中删除一个集合。此调用不会删除任何文档。您可以随后使用该集合；在这种情况下，它将再次加载到内存中。成功后，将返回具有以下属性的对象： +% id：集合的标识符。 +% name：集合的名称。 +% status：集合状态为数字。 +% type：集合类型。有效类型为： +% 2：文件收集 +% 3：边缘收集 +% isSystem：如果为true，则该集合为系统集合。 +% 返回码 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则返回HTTP 404。 +unloadColl(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary, "/unload">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], undefined). + +% 将索引加载到内存中 +% PUT /_api/collection/{collection-name}/loadIndexesIntoMemory +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必填）：此路由尝试将这个collection的所有索引条目缓存到主内存中。因此，它将遍历集合的所有索引，并将索引值而不是整个文档数据存储在内存中。可以在缓存中找到的所有查找都比未存储在缓存中的查找要快得多，因此可以提高性能。还可以保证缓存与存储的数据一致。 +% 目前，此功能仅在RocksDB存储引擎上有用，因为在MMFiles引擎中，所有索引无论如何都在内存中。 +% 在RocksDB上，此函数将遵守所有内存限制，如果要加载的索引小于您的内存限制，则此函数可确保大多数索引值都已缓存。如果索引大于您的内存限制，则此函数将填满直至达到此限制的值，并且暂时无法控制集合中的哪些索引应优先于其他索引。 +% 成功后，此函数返回属性result设置为的对象true +% 返回码 +% 200：如果所有索引都已加载 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则返回HTTP 404。 +collLoadIndexesIntoMemory(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary, "/loadIndexesIntoMemory">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], undefined). + +% 更改集合的属性 +% PUT /_api/collection/{collection-name}/properties +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必填）：集合的名称。 +% 更改集合的属性。需要具有属性的对象 +% waitForSync：如果为true，则创建或更改文档将等待，直到数据已同步到磁盘。 +% journalSize：日志或数据文件的最大大小，以字节为单位。该值必须至少为1048576（1 MB）。请注意，更改journalSize值时，它仅对创建的其他日志或数据文件有效。现有的日志或数据文件将不受影响。 +% schema：指定文档的收集级别架构的对象。属性键rule，level并且message必须遵循文档架构验证中记录的规则 +% +% 成功后，将返回具有以下属性的对象： +% id：集合的标识符。 +% name：集合的名称。 +% waitForSync：新值。 +% journalSize：新值。 +% status：集合状态为数字。 +% type：集合类型。有效类型为： +% 2：文件收集 +% 3：边缘收集 +% isSystem：如果为true，则该集合为系统集合。 +% isVolatile：如果为true，则收集数据将仅保留在内存中，并且ArangoDB不会将数据写入或同步到磁盘。 +% doCompact：是否将压缩集合。 +% keyOptions：JSON对象，其中包含密钥生成选项： +% type：指定密钥生成器的类型。当前可用的生成器是传统的，自动递增的，uuid的 和填充的。 +% allowUserKeys：如果设置为true，则允许在文档的_key属性中提供自己的键值。如果设置为 false，那么密钥生成器将独自负责生成密钥，并且在文档的_key属性中提供自己的密钥值被视为错误。 +% schema（可选，默认为null）：指定文档的收集级别架构的对象。属性键rule，level并且message必须遵循文档架构验证中记录的规则 +% 注意：除了waitForSync，journalSize和name之外，创建集合后就无法更改集合属性。要重命名集合，必须使用重命名端点。 +% 返回码 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则 返回HTTP 404。 +collChangeProps(PoolNameOrSocket, CollName, MapData) -> + Path = <<"/_api/collection/", CollName/binary, "/properties">>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +% 重命名集合 +% PUT /_api/collection/{collection-name}/rename +% 从版本3.4.0开始，不建议使用按其数字ID访问集合。您应该通过它们的名称来引用它们。 +% 路径参数 +% collection-name（必填）：要重命名的集合的名称。 +% 重命名集合。需要具有属性的对象 +% name：新名称。 +% 它返回具有属性的对象 +% id：集合的标识符。 +% name：集合的新名称。 +% status：集合状态为数字。 +% type：集合类型。有效类型为： +% 2：文件收集 +% 3：边缘收集 +% isSystem：如果为true，则该集合为系统集合。 +% 如果重命名集合成功，那么该集合还将_graphs在当前数据库中该集合内的所有图形定义中重命名。 +% 注意：此方法在群集中不可用。 +% 返回码 +% 400：如果缺少集合名称，则返回HTTP 400。 +% 404：如果集合名称未知，则 返回HTTP 404。 +renameColl(PoolNameOrSocket, OldName, NewName) -> + Path = <<"/_api/collection/", OldName/binary, "/rename">>, + NameStr = jiffy:encode(NewName), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], <<"{\"name\":", NameStr/binary, "}">>). + +% 旋转收藏夹的日记 +% PUT /_api/collection/{collection-name}/rotate +% 路径参数 +% collection-name（必填）：集合的名称。 +% 旋转集合的日记帐。集合的当前日志将关闭，并成为只读数据文件。Rotate方法的目的是使文件中的数据可用于压缩（压缩仅对只读数据文件而不对日志执行）。 +% 如果没有当前日志，随后将新数据保存在集合中将自动创建一个新的日志文件。 +% 它返回具有属性的对象 +% 结果：如果旋转成功，则为true +% 注意：此方法特定于MMFiles存储引擎，并且在群集中不可用。 +% 返回码 +% 400：如果该集合当前没有日记，则返回HTTP 400。 +% 404：如果集合名称未知，则返回HTTP 404。 +% 3.7中删掉了该方法 +collRotate(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary, "/rotate">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], undefined). + +% 重新计算集合的文档数 +% PUT /_api/collection/{collection-name}/recalculateCount +% 路径参数 +% collection-name（必填）：集合的名称。 +% 重新计算集合的文档计数（如果不一致）。 +% 它返回具有属性的对象 +% 结果：如果重新计算文档计数成功，则为true。 +% 注意：此方法特定于RocksDB存储引擎 +% 返回码 +% 200：如果文档计数成功重新计算，则返回HTTP 200。 +% 404：如果集合名称未知，则返回HTTP 404。 +collRecount(PoolNameOrSocket, CollName) -> + Path = <<"/_api/collection/", CollName/binary, "/recalculateCount">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], undefined). \ No newline at end of file diff --git a/src/agApi/agDbMgr.erl b/src/agApi/agDbMgr.erl new file mode 100644 index 0000000..e435cb1 --- /dev/null +++ b/src/agApi/agDbMgr.erl @@ -0,0 +1,98 @@ +-module(agDbMgr). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +%% doc_address:https://www.arangodb.com/docs/stable/http/database-database-management.html + +% 使用HTTP管理数据库 +% 这是ArangoDB用于管理数据库的HTTP接口的简介。 +% 数据库的HTTP接口提供创建和删除单个数据库的操作。这些映射到标准HTTP方法POST 和DELETE。还有GET方法来检索现有数据库的数组。 +% 请注意，所有数据库管理操作只能通过默认数据库（_system）访问，而不能通过其他数据库访问。 + +% 关于数据库的注意事项 +% 请记住，每个数据库都包含其自己的系统集合，创建数据库时需要对其进行设置。这将使数据库创建花费一些时间。 +% 复制是在 每个数据库级别 或在服务器级别配置的。在每个数据库的设置中，必须在创建新数据库后显式配置任何复制日志记录或申请新数据库，而在使用全局复制应用程序进行服务器级设置的情况下，将自动复制所有数据库。 +% Foxx应用程序也仅在已安装数据库的上下文中可用。新数据库将仅提供对ArangoDB附带的系统应用程序（即当前的Web界面）的访问，而其他的Foxx应用程序则无法访问。为特定数据库明确安装。 + +% 数据库信息 +% 检索有关当前数据库的信息 +% GET /_api/database/current +% 检索有关当前数据库的信息 +% 响应是具有以下属性的JSON对象： +% name：当前数据库的名称 +% id：当前数据库的ID(字符串格式) +% path：当前数据库的文件系统路径(字符串格式, mmfiles引擎有效) +% isSystem：当前数据库是否为_system数据库 +% sharding：此数据库中创建的集合的默认分片方法(用于新集合的分片方法（仅适用于集群）) +% ReplicationFactor：此数据库中集合的默认复制因子（仅适用于 集群） +% writeConcern：此数据库中集合的默认写关注点 如果同步的副本数量少于此数量，则碎片将拒绝写入（仅适用于集群） +% 返回码 +% 200：如果成功检索到信息，则返回。 +% 400：如果请求无效，则返回。 +% 404：如果找不到数据库，则返回。 +curDbInfo(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/database/current">>, [], undefined). + +% 检索当前用户可以访问的所有数据库的列表 +% GET /_api/database/user +% 检索当前用户可以访问的所有数据库的列表，而无需指定其他用户名或密码。 +% 返回码 +% 200：如果数据库列表编译成功，则返回。 +% 400：如果请求无效，则返回。 +visitDbs(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/database/user">>, [], undefined). + +% 检索所有现有数据库的列表 +% GET /_api/database +% 检索所有现有数据库的列表 +% 注意：只能从_system数据库中检索数据库列表。 +% 注意：您现在应该使用GET用户API来获取可用数据库的列表。 +% 返回码 +% 200：如果数据库列表编译成功，则返回。 +% 400：如果请求无效，则返回。 +% 403：如果请求未在_system数据库中执行，则返回。 +allDbs(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/database">>, [], undefined, true). + +% 创建一个新的数据库 +% POST /_api/database +% 具有以下属性的JSON对象是必需的： +% name：必须包含一个有效的数据库名称。 +% options：可选对象，可以包含以下属性： +% sharding：用于此数据库中新集合的分片方法。有效值为：“”，“ flexible”或“ single”。前两个是等效的。（仅集群） +% ReplicationFactor：在此数据库中创建的新集合的默认复制因子。特殊值包括“ satellite”（卫星），它将复制集合到每个DB-Server；以及1（禁用复制）。（仅集群） +% writeConcern：在此数据库中创建的新集合的默认写关注。它确定在不同的DB服务器上同步每个分片需要多少个副本。如果集群中的副本数量很少，那么分片将拒绝写入。但是，具有足够最新副本的分片写入将同时成功。writeConcern的值 不能大于ReplicationFactor。（仅集群）users：必须是最初为新数据库创建的用户对象数组。对于已经存在的用户，不会更改用户信息。如果未指定users或不包含任何用户，则将使用空字符串密码创建默认用户 root。这确保了新数据库在创建后将可访问。每个用户对象可以包含以下属性： +% users：必须是最初为新数据库创建的用户对象数组。对于已经存在的用户，不会更改用户信息。如果未指定users或不包含任何用户，则将使用空字符串密码创建默认用户 root。这确保了新数据库在创建后将可访问。每个用户对象可以包含以下属性 +% username：要创建的用户的登录名 +% passwd：用户密码（字符串）。如果未指定，则默认为空字符串。 +% active：一个标志，指示是否应该激活用户帐户。默认值为true。如果设置为false，则用户将无法登录数据库。 +% extra：带有额外用户信息的JSON对象。Extra中包含的数据 将为用户存储，但ArangoDB不会进一步解释。 +% 创建一个新的数据库 +% 响应是一个JSON对象，其属性结果设置为true。 +% 注意：仅可以在_system数据库中创建新数据库。 +% 返回码 +% 201：如果数据库创建成功，则返回。 +% 400：如果请求参数无效或具有指定名称的数据库已存在，则返回。 +% 403：如果请求未在_system数据库中执行，则返回。 +% 409：如果具有指定名称的数据库已经存在，则返回。 +newDb(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, <<"/_api/database">>, [], BodyStr, true). + +% 删除现有数据库 +% DELETE /_api/database/{database-name} +% 路径参数 +% database-name（必填）：数据库的名称 +% 删除数据库以及其中存储的所有数据。 +% 注意：只能从_system数据库中删除数据库。该_SYSTEM数据库本身不能被丢弃。 +% 返回码 +% 200：如果成功删除数据库，则返回。 +% 400：如果请求格式错误，则返回。 +% 403：如果请求未在_system数据库中执行，则返回。 +% 404：如果找不到数据库，则返回。 +delDb(PoolNameOrSocket, Name) -> + Path = <<"/_api/database/", Name/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined, true). diff --git a/src/agApi/agDocuments.erl b/src/agApi/agDocuments.erl new file mode 100644 index 0000000..5364bb1 --- /dev/null +++ b/src/agApi/agDocuments.erl @@ -0,0 +1,500 @@ +-module(agDocuments). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +%% doc_address:https://www.arangodb.com/docs/stable/http/document.html + +% 文档的HTTP接口 + +% 基础和术语 +% 文件，密钥，句柄和修订 +% ArangoDB中的文档是JSON对象。这些对象可以嵌套（任何深度），并且可以包含列表。每个文档都有一个唯一的 主键，可以在其集合中对其进行标识。此外，每个文档都由其文档句柄 跨同一数据库中所有集合唯一标识。同一文档的不同修订版（由其句柄标识）可以通过其文档修订版来区分 。任何交易都只能看到文档的单个修订版。 +% 这是一个示例文件： +% { +% "_id" : "myusers/3456789", +% "_key" : "3456789", +% "_rev" : "14253647", +% "firstName" : "John", +% "lastName" : "Doe", +% "address" : { +% "street" : "Road To Nowhere 1", +% "city" : "Gotham" +% }, +% "hobbies" : [ +% {"name": "swimming", "howFavorite": 10}, +% {"name": "biking", "howFavorite": 6}, +% {"name": "programming", "howFavorite": 4} +% ] +% } +% 所有文档都包含特殊属性： 文档句柄以字符串形式存储在中_id， 文档主键存储在中 _key， 文档修订版本存储在中 _rev。_key创建文档时，用户可以指定属性的值。创建文档后_id，_key值是不可变的。该_rev值由ArangoDB自动维护。 +% 文件把手 +% 文档句柄唯一标识数据库中的文档。它是一个字符串，由集合名称和文档键（_key属性）组成，以分隔/。 +% +% 文件金钥 +% 文档密钥可以唯一地标识存储在其集合中的文档。查询特定文档时，客户端可以并且应该使用该文档密钥。文档密钥存储在_key每个文档的属性中。键值由ArangoDB自动在集合的主索引中建立索引。因此，通过其键查找文档是快速的操作。创建文档后，文档的_key值是不变的。默认情况下，如果未指定_key属性，则ArangoDB将自动生成文档密钥，否则使用用户指定的_key。 +% +% 通过使用keyOptions属性创建集合，可以在每个集合级别更改此行为。 +% +% 使用keyOptions它可以完全禁止用户指定的键，或者强制使用特定机制来自动生成_key 值。 +% +% 文件修订 +% ArangoDB中的每个文档都有一个修订版本，存储在system属性中 _rev。它由服务器完全管理，对用户只读。 +% +% 它的值应视为不透明的，不保证其格式和属性，但在文档更新后其值将有所不同。更具体地说，_rev值在单个服务器设置中的所有文档和所有集合中都是唯一的。在群集设置中，_rev即使在同一毫秒内编写，一个分片内也可以确保两个不同的文档修订版具有不同的字符串。 +% +% 该_rev属性可以用作查询的前提，以避免 丢失更新情况。也就是说，如果客户端从服务器获取文档，在本地对其进行修改（但未更改_rev属性），然后将其发送回服务器以更新文档，但是与此同时，该文档已被其他操作更改，则修订不会匹配，服务器将取消该操作。如果没有这种机制，客户端将不知不觉地覆盖对文档所做的更改。 +% +% 当更新或替换现有文档时，ArangoDB会将该文档的新版本写入预写日志文件（与存储引擎无关）。写入新版本的文档后，旧版本仍然存在，至少在磁盘上。删除现有文档（版本）时也是如此：文档的旧版本加上删除操作将在磁盘上保留一段时间。 +% +% 因此，在磁盘上可能同时_key存在同一文档的多个修订版（由相同的值标识）。但是，无法访问过时的修订。文档成功更新或删除后，用户将无法再执行查询或其他数据检索操作。此外，一段时间后，内部将删除旧修订。这是为了避免磁盘使用量不断增长。 +% +% 从用户的角度来看，每个时间点仅存在一个文档修订版本_key。没有内置的系统来自动保留对文档所做的所有更改的历史记录，并且无法通过该_rev值恢复文档的旧版本。 +% +% 文件标签 +% ArangoDB尝试尽可能遵守现有的HTTP标准。为此，单文档查询的结果将HTTP标头Etag设置为使用双引号括起来的文档修订版。 +% +% 文档的基本操作（创建，读取，存在，替换，更新，删除）被映射到标准HTTP方法（POST，GET， HEAD，PUT，PATCH和DELETE）。 +% +% 如果修改文档，则可以使用“ 如果匹配”字段来检测冲突。可以使用HTTP方法HEAD检查文档的修订。 +% +% 单个请求中包含多个文档 +% 从ArangoDB 3.0开始，基本文档API已扩展为不仅可以处理单个文档，而且可以在单个请求中处理多个文档。这对于性能至关重要，尤其是在集群情况下，在这种情况下，单个请求可能涉及集群中的多个网络跃点。另一个优点是，它减少了HTTP协议的开销以及客户端和服务器之间的各个网络往返。在单个请求中执行多个文档操作的总体思路是使用JSON对象数组代替单个文档。因此，必须将前提条件的文档密钥，句柄和修订内容嵌入到给定的各个文档中。多个文档操作仅限于单个文档或边集合。看到有关详细信息的API描述。 +% +% 请注意，GET，HEAD和DELETE HTTP操作通常不允许传递消息正文。因此，它们不能用于在一个请求中执行多个文档操作。但是，还有其他端点可以在一个请求中请求和删除多个文档。请参阅批量文档操作。 +% +% 文件的URI +% 可以使用其唯一的URI检索任何文档： +% +% http://server:port/_api/document/ +% 例如，假设文档句柄为demo/362549736，则该文档的URL为： +% +% http://localhost:8529/_api/document/demo/362549736 +% 上面的URL架构未明确指定 数据库名称 ，因此_system将使用默认数据库。要明确指定数据库上下文，请使用以下URL模式： +% +% http://server:port/_db//_api/document/ +% 例： +% +% http://localhost:8529/_db/mydb/_api/document/demo/362549736 +% 注意：以下示例为了简短起见使用短URL格式。 +% +% 请求文档时，文档修订版本将在“ Etag” HTTP标头中返回。 +% +% 如果使用GET获取文档，并且要检查是否有较新的修订版本，则可以使用If-None-Match标头。如果文档未更改，则返回HTTP 412（前提条件失败）错误。 +% +% 如果要查询，替换，更新或删除文档，则可以使用If-Match标头。如果文档已更改，则操作将中止，并返回HTTP 412错误。 + +% 读取单个文档 +% GET /_api/document/{collection}/{key} +% 路径参数 +% collection（必填）：要从中读取文档的集合的名称。 +% key （必填）：文档密钥。 +% 标头参数 +% If-None-Match（可选）：如果给出了“ If-None-Match”标头，则它必须恰好包含一个Etag。如果文档版本与给定的Etag不同，则返回文档。否则，返回HTTP 304。 +% If-Match（可选）：如果给出了“ If-Match”标头，则它必须恰好包含一个Etag。如果文档的版本与给定的Etag相同，则返回文档。否则，返回HTTP 412。 +% 返回由document-id标识的文档。返回的文档包含三个特殊属性：_id包含文档标识符，_key包含唯一标识给定集合中的文档的键，_rev包含修订版。 +% 返回码 +% 200：如果找到文档，则返回 +% 304：如果给出“ If-None-Match”标题并且文档具有相同版本，则返回 +% 404：如果找不到文档或集合，则返回 +% 412：如果给出“ If-Match”标头并且找到的文档具有不同版本，则返回412。响应还将在_rev属性中包含找到的文档的当前修订。此外，将返回属性_id和_key。 +getDoc(PoolNameOrSocket, CollName, Key) -> + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +getDoc(PoolNameOrSocket, CollName, Key, Headers) -> + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, Headers, undefined). + +% 读取单个文档头 +% HEAD /_api/document/{collection}/{key} +% 路径参数 +% collection （必填）：要从中读取文档的集合的名称。 +% key （必填）：文档密钥。 +% 标头参数 +% If-None-Match（可选）：如果给出了“ If-None-Match”标头，则它必须恰好包含一个Etag。如果当前文档修订版不等于指定的Etag，则返回HTTP 200响应。如果当前文档修订版与指定的Etag相同，则返回HTTP 304。 +% If-Match（可选）：如果给出了“ If-Match”标头，则它必须恰好包含一个Etag。如果文档的版本与给定的Etag相同，则返回文档。否则，返回HTTP 412。 +% 类似于GET，但仅返回标头字段，而不返回正文。您可以使用此调用来获取文档的当前版本，或检查文档是否已删除。 +% 返回码 +% 200：如果找到文档，则返回 +% 304：如果给出“ If-None-Match”标题并且文档具有相同版本，则返回 +% 404：如果找不到文档或集合，则返回 +% 412：如果给出“ If-Match”标头并且找到的文档具有不同版本，则返回412。响应还将在Etag标头中包含找到的文档的当前版本。 +getDocHead(PoolNameOrSocket, CollName, Key) -> + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgHead, Path, [], undefined). + +getDocHead(PoolNameOrSocket, CollName, Key, Headers) -> + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgHead, Path, Headers, undefined). + +% 创建文档 +% POST /_api/document/{collection} +% 路径参数 +% collection （必填）：要在其中创建文档的集合的名称。 +% 查询参数 +% collection （可选）：集合的名称。这仅是为了向后兼容。在ArangoDB版本<3.0中，URL路径为/ _api / document，并且此查询参数是必需的。这种组合仍然有效，但是建议的方法是在URL路径中指定集合。 +% waitForSync（可选）：等待文档已同步到磁盘。 +% returnNew（可选）：另外 ，在结果的new属性下返回完整的新文档。 +% returnOld（可选）：另外 ，在结果的old属性下返回完整的旧文档。仅在使用覆盖选项时可用。 +% silent（可选）：如果设置为true，则将返回一个空对象作为响应。创建的文档将不返回任何元数据。此选项可用于节省一些网络流量。 +% overwrite（可选）：如果设置为true，则插入将成为替换插入。如果已经存在具有相同_key的文档，则不会由于违反唯一约束而拒绝新文档，而是将替换旧文档。 +% overwriteMode（可选）：此选项取代覆盖并提供以下模式： +% "ignore"：如果已经存在具有指定_key值的文档，则不会执行任何操作，也不会执行任何写操作。在这种情况下，插入操作将返回成功。此模式不支持使用来返回旧文档版本RETURN OLD。使用时 RETURN NEW，如果文档已经存在，则将返回null。 +% "replace"：如果已经存在具有指定_key值的文档，则该文档将被指定的文档值覆盖。当未指定overwrite模式但覆盖 标志设置为true时，也将使用此模式。 +% "update"：如果已经存在具有指定_key值的文档，则将使用指定的文档值对其进行修补（部分更新）。可以通过keepNull和 mergeObjects参数进一步控制覆盖模式。 +% "conflict"：如果已经存在具有指定_key值的文档，则返回唯一的违反约束错误，以使插入操作失败。如果未设置覆盖模式，并且覆盖标志为false或未设置，这也是默认行为。 +% keepNull（可选）：如果要使用update-insert命令删除现有属性，则可以将URL查询参数keepNull与 false一起使用。这将修改patch命令的行为，以从属性文档中删除属性文件值为null的现有文档。此选项仅控制更新插入行为。 +% mergeObjects（可选）：控制如果现有文档和更新插入文档中都存在对象（不是数组），是否将合并对象。如果设置为false，则修补程序文档中的值将覆盖现有文档的值。如果设置为true，则对象将被合并。默认值为true。此选项仅控制更新插入行为。 +% 请求正文（json） +% 单个文档的JSON表示形式。 +% 从正文中给定的文档创建一个新文档，除非已经有给定_key的文档。如果未提供_key，则会自动生成一个新的唯一_key。 +% 正文中可能始终给定的_id和_rev属性被忽略，URL部分或查询参数集合分别计数。 +% 如果成功创建了文档，则Location标头将包含新创建的文档的路径。该Etag的头字段包含了文档的修订。两者都仅在单个文档的情况下设置。 +% 如果silent未设置为true，则响应的主体包含具有以下属性的JSON对象： +% _id包含新创建的文档的文档标识符 +% _key包含文档密钥 +% _rev包含文档修订版 +% 如果collection参数waitForSync为false，则该调用将在文档被接受后立即返回。直到文档同步到磁盘后，它才会等待。 +% 可选地，即使已为整个集合禁用了waitForSync标志，查询参数waitForSync也可用于强制将文档创建操作同步到磁盘。因此，waitForSync查询参数可用于强制执行此特定操作的同步。要使用此功能，请将waitForSync参数设置为true。如果 未指定waitForSync参数或将其设置为false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync值为true。 +% 如果查询参数returnNew为true，则对于每个生成的文档，将在结果中的new属性下返回完整的新文档。 +% 返回码 +% 201：如果文档创建成功并且waitForSync为true，则返回 。 +% 202：如果文档创建成功并且waitForSync为false，则返回 。 +% 400：如果正文不包含一个文档的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果collection指定的collection未知，则返回。在这种情况下，响应主体包含一个错误文档。 +% 409：如果在索引属性中具有相同限定词的文档与现有文档发生冲突并因此违反了该唯一约束，则在单个文档的情况下返回409。在这种情况下，响应主体包含一个错误文档。 +newDoc(PoolNameOrSocket, CollName, MapData) -> + Path = <<"/_api/document/", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +newDoc(PoolNameOrSocket, CollName, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +% 替换文档 +% PUT /_api/document/{collection}/{key} +% 路径参数 +% collection（必需）：要在其中替换文档的集合的名称。 +% key（必填）：文档密钥。 +% 查询参数 +% waitForSync（可选）：等待文档已同步到磁盘。 +% ignoreRevs（可选）：默认情况下，或者如果将其设置为true，则忽略给定文档中的_rev属性。如果将其设置为false，则将正文文档中给定的_rev属性作为前提。仅当当前版本是指定的版本时，才替换该文档。 +% returnOld（可选）：在结果的old属性下，还返回更改后的文档的完整先前修订。 +% returnNew（可选）： 在结果的new属性下还返回完整的新文档。 +% silent（可选）：如果设置为true，则将返回一个空对象作为响应。对于已替换的文档，不会返回任何元数据。此选项可用于节省一些网络流量。 +% 标头参数 +% If-Match（可选）：您可以使用if-match HTTP标头有条件地根据目标修订版ID替换文档。 +% 请求正文（json） +% 单个文档的JSON表示形式。 +% 将指定的文档替换为正文中的文档，前提是存在这样的文档并且不违反任何前提条件。 +% 该_key属性的值以及用作分片键的属性均不得更改。 +% 如果指定了If-Match标头，并且数据库中文档的修订版与给定的修订版不相等，则将违反先决条件。 +% 如果未给出If-Match且ignoreRevs为false，并且主体中存在_rev属性，并且其值与数据库中文档的修订版不匹配，则将违反先决条件。 +% 如果违反了前提条件，则返回HTTP 412。 +% 如果文档存在并且可以更新，则返回HTTP 201或HTTP 202（取决于waitForSync，请参见下文），Etag标头字段包含文档的新修订版，而Location标头包含完整的URL，在该URL下，可以查询文件。 +% 仅限群集：替换文档可能包含集合的预定义分片键的值。分片键的值被视为提高性能的提示。如果分片键值不正确，ArangoDB可能会回答“ 未找到”错误。 +% 可选地，即使已为整个集合禁用了waitForSync标志，查询参数waitForSync仍可用于强制将文档替换操作同步到磁盘。因此，waitForSync查询参数可用于强制特定操作的同步。要使用此功能，请将waitForSync参数设置为true。如果未指定waitForSync参数或将其设置为 false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync值为true。 +% 如果silent未设置为true，则响应的主体包含一个JSON对象，其中包含有关标识符和修订版的信息。属性 _id包含更新的文档的已知文档ID，_key 包含用于唯一标识给定集合中的文档的键，而属性_rev包含新文档的修订版。 +% 如果查询参数returnOld为true，那么将在结果的old属性下返回文档的完整先前修订版。 +% 如果查询参数returnNew为true，那么将在结果中的new属性下返回完整的新文档。 +% 如果该文档不存在，则返回HTTP 404，并且响应的正文包含错误文档。 +% 返回码 +% 201：如果成功替换了文档并且waitForSync为true，则返回 。 +% 202：如果成功替换了文档并且waitForSync为false，则返回 。 +% 400：如果正文不包含文档的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果找不到集合或文档，则返回。 +% 412：如果违反了前提条件，则返回。该响应还将在_rev 属性中包含找到的文档的当前修订。此外，将返回属性_id和_key。 +replaceDoc(PoolNameOrSocket, CollName, Key, MapData) -> + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +replaceDoc(PoolNameOrSocket, CollName, Key, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +replaceDoc(PoolNameOrSocket, CollName, Key, MapData, QueryPars, Headers) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, Headers, BodyStr). + +% 更新文档 +% PATCH /_api/document/{collection}/{key} +% 路径参数 +% collection（必填）：要在其中更新文档的集合的名称。 +% key（必填）：文档密钥。 +% 查询参数 +% keepNull（可选）：如果要使用patch命令删除现有属性，则可以将URL查询参数keepNull与false一起使用。这将修改patch命令的行为，以从属性文档中删除属性文件值为null的现有文档。 +% mergeObjects（可选）：控制如果现有文档和修补程序文档中都存在对象（不是数组），是否将合并对象。如果设置为false，则修补程序文档中的值将覆盖现有文档的值。如果设置为true，则对象将被合并。默认值为 true。 +% waitForSync（可选）：等待文档已同步到磁盘。 +% ignoreRevs（可选）：默认情况下，或者如果将其设置为true，则忽略给定文档中的_rev属性。如果将其设置为false，则将正文文档中给定的_rev属性作为前提。仅当当前版本是指定的版本时，文档才会更新。 +% returnOld（可选）：在结果的old属性下，还返回更改后的文档的完整先前修订。 +% returnNew（可选）： 在结果的new属性下还返回完整的新文档。 +% silent（可选）：如果设置为true，则将返回一个空对象作为响应。更新后的文档将不返回任何元数据。此选项可用于节省一些网络流量。 +% 标头参数 +% If-Match（可选）：您可以使用if-match HTTP标头有条件地根据目标修订版ID更新文档。 +% 请求正文（json） +% 文档更新的JSON表示形式作为对象。 +% 部分更新document-id标识的文档。请求的正文必须包含具有要修补的属性的JSON文档（补丁文档）。修补程序文档中的所有属性（如果尚不存在）将被添加到现有文档中，如果存在的话将被覆盖在现有文档中。 +% 该_key属性的值以及用作分片键的属性均不得更改。 +% 在补丁文档中将属性值设置为null会导致默认情况下为该属性保存null值。 +% 如果指定了If-Match标头，并且数据库中文档的修订版与给定的修订版不相等，则将违反先决条件。 +% 如果未给出If-Match且ignoreRevs为false，并且主体中存在_rev属性，并且其值与数据库中文档的修订版不匹配，则将违反先决条件。 +% 如果违反了前提条件，则返回HTTP 412。 +% 如果文档存在并且可以更新，则返回HTTP 201或HTTP 202（取决于waitForSync，请参见下文），Etag标头字段包含文档的新修订版（双引号），而Location标头包含一个可以查询文档的完整URL。 +% 仅限群集：修补程序文档可能包含集合的预定义分片键的值。分片键的值被视为提高性能的提示。如果分片键值不正确，ArangoDB可能会以未发现的错误回答 +% 可选地，即使已为整个集合禁用了waitForSync标志，查询参数waitForSync仍可用于强制将更新的文档操作同步到磁盘。因此，waitForSync查询参数可用于强制特定操作的同步。要使用此功能，请将waitForSync参数设置为true。如果未指定waitForSync参数或将其设置为 false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync值为true。 +% 如果silent未设置为true，则响应的主体包含一个JSON对象，其中包含有关标识符和修订版的信息。属性 _id包含更新的文档的已知文档ID，_key 包含用于唯一标识给定集合中的文档的键，而属性_rev包含新文档的修订版。 +% 如果查询参数returnOld为true，那么将在结果的old属性下返回文档的完整先前修订版。 +% 如果查询参数returnNew为true，那么将在结果中的new属性下返回完整的新文档。 +% 如果该文档不存在，则返回HTTP 404，并且响应的正文包含错误文档。 +% 返回码 +% 201：如果文档更新成功并且waitForSync为true，则返回 。 +% 202：如果文档更新成功且waitForSync为false，则返回 。 +% 400：如果正文不包含文档的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果找不到集合或文档，则返回。 +% 412：如果违反了前提条件，则返回。该响应还将在_rev 属性中包含找到的文档的当前修订。此外，将返回属性_id和_key。 +updateDoc(PoolNameOrSocket, CollName, Key, MapData) -> + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, [], BodyStr). + +updateDoc(PoolNameOrSocket, CollName, Key, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, [], BodyStr). + +updateDoc(PoolNameOrSocket, CollName, Key, MapData, QueryPars, Headers) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, Headers, BodyStr). + +% 删除文档 +% DELETE /_api/document/{collection}/{key} +% 路径参数 +% collection（必填）：要在其中删除文档的集合的名称。 +% key（必填）：文档密钥。 +% 查询参数 +% waitForSync（可选）：等待删除操作已同步到磁盘。 +% returnOld（可选）：在结果的old属性下，还返回更改后的文档的完整先前修订。 +% silent（可选）：如果设置为true，则将返回一个空对象作为响应。对于已删除的文档，不会返回任何元数据。此选项可用于节省一些网络流量。 +% 标头参数 +% If-Match（可选）：您可以使用if-match HTTP标头有条件地根据目标修订版ID删除文档。 +% 如果silent未设置为true，则响应的主体包含一个JSON对象，其中包含有关标识符和修订版的信息。属性 _id包含已删除文档的已知文档ID，_key 包含用于唯一标识给定集合中文档的键，属性_rev包含文档修订版。 +% 如果未指定waitForSync参数或将其设置为false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync 的价值真。 +% 如果查询参数returnOld为true，那么将在结果的old属性下返回文档的完整先前修订版。 +% 返回码 +% 200：如果文档已成功删除并且waitForSync为true，则返回 。 +% 202：如果文档已成功删除并且waitForSync为false，则返回 。 +% 404：如果找不到集合或文档，则返回。在这种情况下，响应主体包含一个错误文档。 +% 412：如果“如果-match”标头或返回转，并给出找到的文件有不同的版本。响应还将在_rev属性中包含找到的文档的当前修订。此外，将返回属性_id和_key。 +delDoc(PoolNameOrSocket, CollName, Key) -> + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delDoc(PoolNameOrSocket, CollName, Key, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delDoc(PoolNameOrSocket, CollName, Key, QueryPars, Headers) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, Headers, undefined). + +% 批量文件操作 +% ArangoDB支持批量处理文档。批量操作影响 单个集合。使用此API变体可使客户端分摊整批文档中的单个请求的开销。不能保证批量操作可以串行执行，ArangoDB 可以并行执行这些操作。这可以转化为大幅的性能提升，尤其是在集群部署中。 +% 如果在处理一个操作期间发生错误，ArangoDB将继续处理其余操作。错误将作为错误文档在响应正文中内联返回（有关更多详细信息，请参见下文）。此外，X-Arango-Error-Codes标头将包含发生的错误代码及其多重性的映射，例如 1205:10,1210:17，这意味着在10种情况下，错误1205 非法文档句柄；在17种情况下，错误1210 违反了唯一约束。。 +% 通常，批量操作期望输入数组，并且结果主体将包含相同长度的JSON数组。 + +% 读取单个文档 +% PUT /_api/document/{collection}#get +% 路径参数 +% collection（必需）：要从中读取文档的集合的名称。 +% 查询参数 +% onlyget（必需）：该参数必须为true，否则将执行替换操作！ +% ignoreRevs（可选）：如果该值为true（默认值）：如果搜索文档包含_rev字段的值，则仅当文档具有相同的修订值时才返回该文档。否则，将返回前提条件失败错误。 +% 返回正文对象中由_key标识的文档。请求的正文必须包含字符串（要查找的_key值）或搜索文档的JSON数组。 +% 搜索文档必须至少包含_key字段的值。一种用于值_rev 可被指定以验证文档是否具有相同的修订值，除非ignoreRevs设置为false。 +% 仅限群集：搜索文档可能包含集合的预定义分片键的值。分片键的值被视为提高性能的提示。如果分片键值不正确，ArangoDB可能会回答“ 未找到”错误。 +% 返回的文档数组包含三个特殊属性：_id包含文档标识符，_key包含唯一标识给定集合中的文档的键，_rev包含修订版。 +% 返回码 +% 200：如果没有发生错误则返回 +% 400：如果正文不包含文档数组的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果找不到集合，则返回。 +% 对于该操作的返回 列表 如果文档不存在 或者_rev条件不满足 则返回列表的中包含相关的错误 可能需要在使用的时候过滤正确和非正确的返回文档 +getDocs(PoolNameOrSocket, CollName, KeyOrMapDataList) -> + QueryBinary = agMiscUtils:spellQueryPars([{onlyget, true}]), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(KeyOrMapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +getDocs(PoolNameOrSocket, CollName, KeyOrMapDataList, QueryPars) -> + LastQueryPars = + case lists:keyfind(onlyget, 1, QueryPars) of + {onlyget, true} -> + QueryPars; + _ -> + lists:keystore(onlyget, 1, QueryPars, {onlyget, true}) + end, + QueryBinary = agMiscUtils:spellQueryPars(LastQueryPars), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(KeyOrMapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +% 创建多个文档 +% POST /_api/document/{collection}#multiple +% 路径参数 +% collection（必填）：要在其中创建文档的集合的名称。 +% 查询参数 +% collection（可选）：集合的名称。这仅是为了向后兼容。在ArangoDB版本<3.0中，URL路径为/ _api / document，并且此查询参数是必需的。这种组合仍然有效，但是建议的方法是在URL路径中指定集合。 +% waitForSync（可选）：等待文档已同步到磁盘。 +% returnNew（可选）：另外 ，在结果的new属性下返回完整的新文档。 +% returnOld（可选）：另外 ，在结果的old属性下返回完整的旧文档。仅在使用覆盖选项时可用。 +% silent（可选）：如果设置为true，则将返回一个空对象作为响应。创建的文档将不返回任何元数据。此选项可用于节省一些网络流量。 +% overwrite（可选）：如果设置为true，则插入将成为替换插入。如果已经存在具有相同_key的文档，则不会由于违反唯一约束而拒绝新文档，而是将替换旧文档。 +% 请求正文（json） +% 要创建的文档数组。 +% 从正文中给定的文档创建新文档，除非已经有给定_key的文档。如果未提供_key，则会自动生成一个新的唯一_key。 +% 结果主体将包含一个长度与输入数组相同的JSON数组，并且每个条目都包含对应输入的运算结果。如果发生错误，则该条目是一个文档，其属性error设置为true，errorCode设置为发生的错误代码。 +% 正文中可能始终给定的_id和_rev属性被忽略，URL部分或查询参数集合分别计数。 +% 如果silent未设置为true，则响应的主体包含具有以下属性的JSON对象数组： +% _id包含新创建的文档的文档标识符 +% _key包含文档密钥 +% _rev包含文档修订版 +% 如果collection参数waitForSync为false，则在文档被接受后，调用将立即返回。直到文档同步到磁盘后，它才会等待。 +% 可选地，即使已为整个集合禁用了waitForSync标志，查询参数waitForSync也可用于强制将文档创建操作同步到磁盘。因此，waitForSync查询参数可用于强制执行此特定操作的同步。要使用此功能，请将waitForSync参数设置为true。如果 未指定waitForSync参数或将其设置为false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync值为true。 +% 如果查询参数returnNew为true，则对于每个生成的文档，将在结果中的new属性下返回完整的新文档。 +% 应与一些附加的HTTP头的文件已经发生了错误的X阿朗戈-差错代码：被设置，其中包含一个地图，与它们的重数一起发生的错误代码，如在1205：10,1210：17，其意味着在10种情况下发生了错误1205“非法文档句柄”，在17种情况下发生了错误1210“违反唯一约束”。 +% 返回码 +% 201：如果waitForSync为true，并且已处理操作，则返回。 +% 202：如果waitForSync为false并且已处理操作，则返回。 +% 400：如果正文不包含文档数组的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果collection指定的collection未知，则返回。在这种情况下，响应主体包含一个错误文档。 +% 按照MapDataList的顺序返回执行结果 正确或者错误 +newDocs(PoolNameOrSocket, CollName, MapDataList) -> + Path = <<"/_api/document/", CollName/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +newDocs(PoolNameOrSocket, CollName, MapDataList, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +% 替换多个文件 +% PUT /_api/document/{collection} +% 路径参数 +% collection（必填）：此URL参数是替换文档的集合的名称。 +% 查询参数 +% waitForSync（可选）：等待新文档同步到磁盘。 +% ignoreRevs（可选）：默认情况下，或者如果将其设置为true，则忽略给定文档中的_rev属性。如果将其设置为false，则将正文文档中给定的_rev属性作为前提。仅当当前版本是指定的版本时，才替换该文档。 +% returnOld（可选）：在结果的old属性下还返回更改后的文档的完整先前修订。 +% returnNew（可选）： 在结果的new属性下还返回完整的新文档。 +% 请求正文（json） +% 文档数组的JSON表示形式。 +% 用主体中的文档替换指定集合中的多个文档，替换后的文档由 主体文档中的_key属性指定。 +% 该_key属性的值以及用作sharding keys的属性均不得更改。 +% 如果ignoreRevs为false，并且正文中的文档中存在_rev属性，并且其值与数据库中相应文档的修订版不匹配，则将违反先决条件。 +% 仅限群集：替换文档可能包含集合的预定义分片键的值。分片键的值被视为提高性能的提示。如果分片键值不正确，ArangoDB可能会回答“ 未找到”错误。 +% 可选地，即使已为整个集合禁用了waitForSync标志，查询参数waitForSync仍可用于强制将文档替换操作同步到磁盘。因此，waitForSync查询参数可用于强制特定操作的同步。要使用此功能，请将waitForSync参数设置为true。如果未指定waitForSync参数或将其设置为 false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync值为true。 +% 响应的主体包含一个与输入数组长度相同的JSON数组，其中包含有关标识符和替换文档的修订版的信息。在每个条目中，属性 _id包含每个更新文档的已知文档ID， _key包含用于唯一标识给定集合中的文档的键，而属性_rev包含新文档修订版。如果发生错误或违反先决条件，则会构建一个错误对象，该错误对象的属性error设置为true，属性 errorCode设置为错误代码。 +% 如果查询参数returnOld为true，则对于每个生成的文档，将在结果的old属性下返回文档的完整先前修订版。 +% 如果查询参数returnNew为true，则对于每个生成的文档，将在结果中的new属性下返回完整的新文档。 +% 请注意，如果违反任何前提条件或某些文档发生错误，则返回代码仍为201或202，但是会设置其他HTTP标头X-Arango-Error-Codes，其中包含错误代码的映射，与它们的多重性一起发生，如：1200：17,1205：10，这意味着在17种情况下发生了错误1200“修订冲突”，在10种情况下发生了错误1205“非法文档句柄”。 +% 返回码 +% 201：如果waitForSync为true，并且已处理操作，则返回。 +% 202：如果waitForSync为false并且已处理操作，则返回。 +% 400：如果正文不包含文档数组的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果找不到集合，则返回。 +replaceDocs(PoolNameOrSocket, CollName, MapDataList) -> + Path = <<"/_api/document/", CollName/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +replaceDocs(PoolNameOrSocket, CollName, MapDataList, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +% 更新多个文件 +% PATCH /_api/document/{collection} +% 路径参数 +% collection（必填）：要在其中更新文档的集合的名称。 +% 查询参数 +% keepNull（可选）：如果要使用patch命令删除现有属性，则可以将URL查询参数keepNull与false一起使用。这将修改patch命令的行为，以从属性文档中删除属性文件值为null的现有文档。 +% mergeObjects（可选）：控制如果现有文档和修补程序文档中都存在对象（不是数组），是否将合并对象。如果设置为false，则修补程序文档中的值将覆盖现有文档的值。如果设置为true，则对象将被合并。默认值为 true。 +% waitForSync（可选）：等待新文档同步到磁盘。 +% ignoreRevs（可选）：默认情况下，或者如果将其设置为true，则忽略给定文档中的_rev属性。如果将其设置为false，则将正文文档中给定的_rev属性作为前提。仅当当前版本是指定的版本时，文档才会更新。 +% returnOld（可选）：在结果的old属性下还返回更改后的文档的完整先前修订。 +% returnNew（可选）： 在结果的new属性下还返回完整的新文档。 +% 请求正文（json） +% 文档更新数组的JSON表示形式是对象。 +% 部分更新文档，要更新的文档由主体对象中的_key属性指定。请求的正文必须包含文档更新的JSON数组，其中包含要修补的属性（补丁文档）。修补程序文档中的所有属性（如果尚不存在）将被添加到现有文档中，如果存在的话将被覆盖在现有文档中。 +% 该_key属性的值以及用作分片键的属性均不得更改。 +% 在补丁文档中将属性值设置为null会导致默认情况下为该属性保存null值。 +% 如果ignoreRevs为false，并且正文中的文档中存在_rev属性，并且其值与数据库中相应文档的修订版不匹配，则将违反先决条件。 +% 仅限群集：修补程序文档可能包含集合的预定义分片键的值。分片键的值被视为提高性能的提示。如果分片键值不正确，ArangoDB可能会以未发现的错误回答 +% 可选地，即使已为整个集合禁用了waitForSync标志，查询参数waitForSync仍可用于强制将文档替换操作同步到磁盘。因此，waitForSync查询参数可用于强制特定操作的同步。要使用此功能，请将waitForSync参数设置为true。如果未指定waitForSync参数或将其设置为 false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync值为true。 +% 响应的主体包含一个与输入数组长度相同的JSON数组，其中包含有关标识符和已更新文档的修订的信息。在每个条目中，属性 _id包含每个更新文档的已知文档ID， _key包含用于唯一标识给定集合中的文档的键，而属性_rev包含新文档修订版。如果发生错误或违反先决条件，则会构建一个错误对象，该错误对象的属性error设置为true，属性 errorCode设置为错误代码。 +% 如果查询参数returnOld为true，则对于每个生成的文档，将在结果的old属性下返回文档的完整先前修订版。 +% 如果查询参数returnNew为true，则对于每个生成的文档，将在结果中的new属性下返回完整的新文档。 +% 请注意，如果违反任何前提条件或某些文档发生错误，则返回代码仍为201或202，但是会设置其他HTTP标头X-Arango-Error-Codes，其中包含错误代码的映射，与它们的多重性一起发生，如：1200：17,1205：10，这意味着在17种情况下发生了错误1200“修订冲突”，在10种情况下发生了错误1205“非法文档句柄”。 +% 返回码 +% 201：如果waitForSync为true，并且已处理操作，则返回。 +% 202：如果waitForSync为false并且已处理操作，则返回。 +% 400：如果正文不包含文档数组的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果找不到集合，则返回。 +updateDocs(PoolNameOrSocket, CollName, MapDataList) -> + Path = <<"/_api/document/", CollName/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, [], BodyStr). + +updateDocs(PoolNameOrSocket, CollName, MapDataList, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, [], BodyStr). + +% 删除多个文件 +% DELETE /_api/document/{collection} +% 路径参数 +% collection（必填）：从中删除文档的集合。 +% 查询参数 +% waitForSync（可选）：等待删除操作已同步到磁盘。 +% returnOld（可选）：在结果的old属性下，还返回更改后的文档的完整先前修订。 +% ignoreRevs（可选）：如果设置为true，则忽略选择器中的任何_rev属性。不执行任何修订检查。 +% 请求正文（json） +% 字符串或文档的JSON数组。 +% 请求的主体是一个由文档选择器组成的数组。选择器可以是带键的字符串，带文档标识符的字符串或带_key属性的对象。此API调用从collection中删除所有指定的文档。如果选择器是一个对象并具有_rev属性，则前提是集合中已删除文档的实际修订版是指定的。 +% 响应的主体是一个与输入数组长度相同的数组。对于每个输入选择器，输出都包含一个JSON对象，其中包含有关操作结果的信息。如果未发生错误，则构建一个对象，其中属性_id包含已删除文档的已知文档ID，_key包含用于唯一标识给定集合中的文档的键，而属性_rev包含文档修订版。在发生错误的情况下，与属性的对象错误设置为真和 的errorCode集到的错误代码被构建的。 +% 如果未指定waitForSync参数或将其设置为false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync 的价值真。 +% 如果查询参数returnOld为true，那么将在结果的old属性下返回文档的完整先前修订版。 +% 请注意，如果违反任何先决条件或某些文档发生错误，则返回代码仍为200或202，但是会设置其他HTTP标头X-Arango-Error-Codes，其中包含错误代码的映射，与它们的多重性一起发生，如：1200：17,1205：10，这意味着在17种情况下发生了错误1200“修订冲突”，在10种情况下发生了错误1205“非法文档句柄”。 +% 返回码 +% 200：如果waitForSync为true，则返回。 +% 202：如果waitForSync为false，则返回。 +% 404：如果找不到集合，则返回。在这种情况下，响应主体包含一个错误文档。 +delDocs(PoolNameOrSocket, CollName, KeyOrMapDataList) -> + Path = <<"/_api/document/", CollName/binary, "/">>, + BodyStr = jiffy:encode(KeyOrMapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], BodyStr). + +delDocs(PoolNameOrSocket, CollName, KeyOrMapDataList, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(KeyOrMapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], BodyStr). diff --git a/src/agApi/agEdges.erl b/src/agApi/agEdges.erl new file mode 100644 index 0000000..898d9f4 --- /dev/null +++ b/src/agApi/agEdges.erl @@ -0,0 +1,43 @@ +-module(agEdges). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +%% doc_address:https://www.arangodb.com/docs/stable/http/edge.html + +% 边的地址和标签 +% ArangoDB中的所有文档都有一个文档句柄。该句柄唯一地标识一个文档。可以使用其唯一的URI检索任何文档： +% +% http://server:port/_api/document/ +% 边缘是文档的特殊变体。要访问边缘，请使用与文档相同的URL格式： +% +% http://server:port/_api/document/ +% 例如，假定存储在 边缘的_id属性中的文档句柄是demo / 362549736，则该边缘的URL为： +% +% http://localhost:8529/_api/document/demo/362549736 +% 上面的URL方案没有明确指定数据库名称，因此将使用默认数据库。要明确指定数据库上下文，请使用以下URL模式： +% +% http://server:port/_db//_api/document/ +% 范例： +% +% http://localhost:8529/_db/mydb/_api/document/demo/362549736 +% 注意：为了简洁起见，以下示例使用简短的URL格式。 + +% 获取边 +% GET /_api/edges/{collection-id} +% 路径参数 +% collection-id（必填）：边集合的ID或者边集合名。 +% 查询参数 +% vertex（必填）：起始顶点的ID。 +% direction（可选）：选择 in or out 为边缘方向。如果未设置，则返回任何边。 +% 返回以vertex标识的顶点开始或结束的边数组 。 +% 返回码 +% 200：如果找到边缘集合并检索到边缘，则返回。 +% 400：如果请求包含无效参数，则返回。 +% 404：如果未找到边缘集合，则返回。 +getEdges(PoolNameOrSocket, CollName, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/edges/", CollName/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). \ No newline at end of file diff --git a/src/agApi/agEndPoints.erl b/src/agApi/agEndPoints.erl new file mode 100644 index 0000000..bb7c619 --- /dev/null +++ b/src/agApi/agEndPoints.erl @@ -0,0 +1,43 @@ +-module(agEndPoints). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/endpoints.html + +% 端点的HTTP接口 +% 该API /_api/endpoint已弃用。对于集群模式，/_api/cluster/endpoints可以找到所有当前的Coordinator端点（请参见下文）。 +% +% ArangoDB服务器可以在多个端点上侦听传入的请求。 +% +% 通常使用“ --server.endpoint”选项在ArangoDB的配置文件或命令行中指定端点。ArangoDB的默认终结点是tcp：//127.0.0.1：8529或 tcp：// localhost：8529。 +% +% 请注意，所有端点管理操作只能通过默认数据库（_system）访问，而不能通过其他任何数据库访问。 + +% 获取有关所有协调器端点的信息固定链接 +% 此API调用返回有关所有协调器终结点的信息（仅集群）。 +% GET /_api/cluster/endpoints +% 返回带有属性endpoints的对象，该对象包含一个对象数组，每个对象都有一个属性endpoint，其值是带有端点描述的字符串。集群中的每个协调器都有一个条目。此方法仅适用于群集模式下的协调器。如果发生错误，则将error属性设置为 true。 +% HTTP 200 +% error：布尔值标志，指示是否发生错误（在这种情况下为true） +% code：HTTP状态码-200 +% 端点：活动集群端点的列表。 +% 端点：协调器的绑定，例如tcp://[::1]:8530 +% 501： +getClusterEndpoints(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/cluster/endpoints">>, [], undefined, true). + +% 所有端点的返回列表永久链接 +% 此API调用返回所有端点（单个服务器）的列表。 +% GET /_api/endpoint +% 此路由不应再使用。从3.4.0版开始，它被视为已弃用。 +% 返回服务器正在侦听的所有已配置端点的数组。 +% 结果是一个JSON对象的JSON数组，每个对象均带有“ entrypoint”作为唯一属性，并且值是描述端点的字符串。 +% 注意：仅在系统数据库中允许检索所有端点的数组。在任何其他数据库中调用此操作将使服务器返回错误。 +% 返回码 +% 200：可以成功确定端点数组时返回。 +% 400：如果未在系统数据库中执行该操作，则返回。 +% 405：如果使用了不受支持的HTTP方法，则服务器将以HTTP 405进行响应。 + diff --git a/src/agApi/agFoxxServices.erl b/src/agApi/agFoxxServices.erl new file mode 100644 index 0000000..00f25f9 --- /dev/null +++ b/src/agApi/agFoxxServices.erl @@ -0,0 +1,399 @@ +-module(agFoxxServices). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/foxx.html + +% Foxx HTTP API +% 这些路由允许操作数据库中安装的Foxx服务。 +% +% 有关Foxx及其JavaScript API的更多信息，请参见主要文档的Foxx章节。 + +% Foxx服务管理 +% 这是用于管理Foxx服务的ArangoDB HTTP接口的简介。 + +% 列出已安装的服务 +% GET /_api/foxx +% 查询参数 +% excludeSystem（可选）：是否应从结果中排除系统服务。 +% 获取当前数据库中安装的服务列表。 +% 返回具有以下属性的对象列表： +% mount：服务的安装路径 +% development：如果服务以开发模式运行，则为true +% legacy：如果服务以2.8旧版兼容模式运行，则为true +% 提供：服务清单的提供值或空对象 +% 此外，如果在清单上设置了以下对象，则该对象可能包含以下属性： +% name：标识服务类型的字符串 +% version：与semver兼容的版本字符串 +% 返回码 +% 200：如果请求成功，则返回。 +getFoxxList(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/foxx">>, [], undefined). + +getFoxxList(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/foxx", QueryBinary/binary>>, [], undefined). + +% 服务说明 +% 服务元数据 +% GET /_api/foxx/service +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 在给定的安装路径中获取服务的详细信息。 +% 返回具有以下属性的对象： +% mount：服务的安装路径 +% path：服务的本地文件系统路径 +% development：如果服务以开发模式运行，则为true +% legacy：如果服务以2.8旧版兼容模式运行，则为true +% manifest：服务的规范化JSON清单 +% 此外，如果在清单上设置了以下对象，则该对象可能包含以下属性： +% name：标识服务类型的字符串 +% version：与semver兼容的版本字符串 +% 返回码 +% 200：如果请求成功，则返回。 +% 400：如果安装路径未知，则返回。 +getFoxxService(PoolNameOrSocket, Mount) -> + Path = <<"/_api/foxx/service?mount=", (agMiscUtils:toBinary(Mount))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 安装新服务 +% POST /_api/foxx +% 查询参数 +% mount（必需）：应在其中安装服务的安装路径。 +% 开发（可选）：设置true为启用开发模式。 +% 安装程序（可选）：设置为false不运行服务的安装脚本。 +% legacy（可选）：设置为true以2.8旧版兼容性模式安装服务。 +% 在给定的安装路径上安装给定的新服务。 +% 请求主体可以是以下任何格式： +% application/zip：包含服务的原始zip捆绑包 +% application/javascript：独立的JavaScript文件 +% application/json：服务定义为JSON +% multipart/form-data：服务定义为多部分形式 +% 服务定义是具有以下属性或字段的对象或表单： +% configuration：描述配置值的JSON对象 +% 依赖项：一个描述依赖项设置的JSON对象 +% source：服务器文件系统上的标准URL或绝对路径 +% 使用多部分数据时，源字段也可以是包含zip捆绑包或独立JavaScript文件的文件字段。 +% 使用独立的JavaScript文件时，将执行给定的文件来定义我们服务的HTTP端点。main与在服务清单字段中定义的相同。 +% 如果源是URL，则必须可以从服务器访问该URL。如果source是文件系统路径，则该路径将在服务器上解析。在任何情况下，路径或URL都应解析为zip包，JavaScript文件或（如果是文件系统路径）目录。 +% 请注意，在具有多个协调器的群集中使用文件系统路径时，文件系统路径必须解析为每个协调器上的等效文件。 +% 返回码 +% 201：如果请求成功，则返回。 +installFoxx(PoolNameOrSocket, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx", QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +% 卸载服务 +% DELETE /_api/foxx/service +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% teardown （可选）：设置为false不运行服务的拆卸脚本。 +% 从数据库和文件系统中删除给定安装路径中的服务。 +% 成功返回空响应。 +% 返回码 +% 204：如果请求成功，则返回。 +uninstallFoxx(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/service", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +% 更换服务 +% PUT /_api/foxx/service +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% teardown （可选）：设置为false不运行旧服务的拆卸脚本。 +% setup （可选）：设置为false不运行新服务的安装脚本。 +% legacy（可选）：设置为true以2.8 Legacy兼容模式安装新服务。 +% force （可选）：设置为true强制安装服务，即使在给定的安装下未安装任何服务也是如此。 +% 从数据库和文件系统中删除给定安装路径中的服务。然后在相同的安装路径上安装给定的新服务。 +% 这与执行旧服务的卸载，然后安装新服务的安全性等效。在删除旧服务之前，将检查新服务的主文件和脚本文件（如果有）是否存在基本语法错误。 +% 请求主体可以是以下任何格式： +% application/zip：包含服务的原始zip捆绑包 +% application/javascript：独立的JavaScript文件 +% application/json：服务定义为JSON +% multipart/form-data：服务定义为多部分形式 +% 服务定义是具有以下属性或字段的对象或表单： +% configuration：描述配置值的JSON对象 +% 依赖项：一个描述依赖项设置的JSON对象 +% source：服务器文件系统上的标准URL或绝对路径 +% 使用多部分数据时，源字段也可以是包含zip捆绑包或独立JavaScript文件的文件字段。 +% 使用独立的JavaScript文件时，将执行给定的文件来定义我们服务的HTTP端点。main与在服务清单字段中定义的相同。 +% 如果源是URL，则必须可以从服务器访问该URL。如果source是文件系统路径，则该路径将在服务器上解析。在任何情况下，路径或URL都应解析为zip包，JavaScript文件或（如果是文件系统路径）目录。 +% 请注意，在具有多个协调器的群集中使用文件系统路径时，文件系统路径必须解析为每个协调器上的等效文件。 +% 返回码 +% 200：如果请求成功，则返回。 +replaceFoxx(PoolNameOrSocket, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/service", QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +% 升级服务 +% PATCH /_api/foxx/service +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% teardown（可选）：设置为true运行旧服务的拆卸脚本。 +% setup（可选）：设置为false不运行新服务的安装脚本。 +% legacy（可选）：设置为true以2.8 Legacy兼容模式安装新服务。 +% force（可选）：设置为true强制安装服务，即使在给定的安装下未安装任何服务也是如此。 +% 将给定的新服务安装在给定的安装路径上当前安装的服务之上。仅建议在同一服务的不同版本之间进行切换时使用。 +% 与替换服务不同，升级服务会保留旧服务的配置和依赖关系（如果有），因此仅应用于将现有服务迁移到新服务或等效服务。 +% 请求主体可以是以下任何格式： +% application/zip：包含服务的原始zip捆绑包 +% application/javascript：独立的JavaScript文件 +% application/json：服务定义为JSON +% multipart/form-data：服务定义为多部分形式 +% 服务定义是具有以下属性或字段的对象或表单： +% configuration：描述配置值的JSON对象 +% 依赖项：一个描述依赖项设置的JSON对象 +% source：服务器文件系统上的标准URL或绝对路径 +% 使用多部分数据时，源字段也可以是包含zip捆绑包或独立JavaScript文件的文件字段。 +% 使用独立的JavaScript文件时，将执行给定的文件来定义我们服务的HTTP端点。main与在服务清单字段中定义的相同。 +% 如果源是URL，则必须可以从服务器访问该URL。如果source是文件系统路径，则该路径将在服务器上解析。在任何情况下，路径或URL都应解析为zip包，JavaScript文件或（如果是文件系统路径）目录。 +% 请注意，在具有多个协调器的群集中使用文件系统路径时，文件系统路径必须解析为每个协调器上的等效文件。 +% 返回码 +% 200：如果请求成功，则返回。 +upgradeFoxx(PoolNameOrSocket, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/service", QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, [], BodyStr). + +% Foxx服务配置/依赖关系 +% 这是用于管理Foxx服务配置和依赖关系的ArangoDB HTTP接口的简介。 +% +% 获取配置选项 +% GET /_api/foxx/configuration +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 在给定的安装路径中获取服务的当前配置。 +% 返回一个对象，该对象将配置选项名称映射到其定义，包括易于理解的标题和当前值（如果有）。 +% 返回码 +% 200：如果请求成功，则返回。 +getFoxxConfig(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/configuration", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 更新配置选项 +% PATCH /_api/foxx/configuration +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 请求正文（json） +% JSON对象映射配置选项名称为其新值。任何省略的选项将被忽略。 +% 替换给定服务的配置。 +% 返回一个将所有配置选项名称映射到其新值的对象。 +% 返回码 +% 200：如果请求成功，则返回。 +updateFoxxConfig(PoolNameOrSocket, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/configuration", QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, [], BodyStr). + +% 替换配置选项 +% PUT /_api/foxx/configuration +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 请求正文（json） +% JSON对象映射配置选项名称为其新值。任何省略的选项将重置为默认值或标记为未配置。 +% 完全替换给定服务的配置。 +% 返回一个将所有配置选项名称映射到其新值的对象。 +% 返回码 +% 200：如果请求成功，则返回。 +replaceFoxxConfig(PoolNameOrSocket, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/configuration", QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +% 获取依赖项选项 +% GET /_api/foxx/dependencies +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 在给定的安装路径中获取服务的当前依赖关系。 +% 返回一个对象，该对象将依赖项名称映射到它们的定义，包括易于理解的标题和当前的安装路径（如果有）。 +% 返回码 +% 200：如果请求成功，则返回。 +getFoxxDependencies(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/dependencies", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + + +% 更新依赖项选项 +% PATCH /_api/foxx/dependencies +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 请求正文（json） +% 映射依赖项名称到其新安装路径的JSON对象。任何省略的依赖项将被忽略。 +% 替换给定服务的依赖项。 +% 返回一个将所有依赖项名称映射到其新安装路径的对象。 +% 返回码 +% 200：如果请求成功，则返回。 +updateFoxxDependencies(PoolNameOrSocket, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/dependencies", QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, [], BodyStr). + +% 替换依赖项选项 +% PUT /_api/foxx/dependencies +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 请求正文（json） +% 映射依赖项名称到其新安装路径的JSON对象。任何省略的依赖项将被禁用。 +% 完全替换给定服务的依赖项。 +% 返回一个将所有依赖项名称映射到其新安装路径的对象。 +% 返回码 +% 200：如果请求成功，则返回。 +replaceFoxxDependencies(PoolNameOrSocket, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/dependencies", QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +% Foxx服务杂项 +% +% 列出服务脚本 +% GET /_api/foxx/scripts +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 获取服务定义的脚本列表。 +% 返回一个将原始脚本名称映射到人类友好名称的对象。 +% 返回码 +% 200：如果请求成功，则返回。 +getFoxxScripts(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/scripts", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 运行服务脚本 +% POST /_api/foxx/scripts/{name} +% 路径参数 +% 名称（必填）：要运行的脚本的名称。 +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 请求正文（json） +% 一个任意的JSON值，将被解析并作为第一个参数传递给脚本。 +% 在给定的安装路径上为服务运行给定的脚本。 +% 返回脚本的导出（如果有）。 +% 返回码 +% 200：如果请求成功，则返回。 +runFoxxScripts(PoolNameOrSocket, ScriptName, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/scripts/", ScriptName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +% 运行服务测试 +% POST /_api/foxx/tests +% 查询参数 +% mount （必需）：已安装服务的安装路径。 +% reporter （可选）：测试记者使用。 +% idiomatic （可选）：与报告器使用匹配的格式，而与Accept标头无关。 +% filter（可选）：仅运行全名（包括完整的测试套件和测试用例）与该字符串匹配的测试。 +% 在给定的安装路径上运行该服务的测试并返回结果。 +% 支持的测试报告者为： +% default：测试用例的简单列表 +% suite：嵌套在套件中的测试用例的对象 +% stream：测试结果的原始流 +% xunit：与XUnit / JUnit兼容的结构 +% tap：原始TAP兼容流 +% 该接受请求报头可以被用于进一步控制的响应格式： +% 使用流报告器时，application/x-ldjson将导致响应主体被格式化为以换行符分隔的JSON流。 +% 使用点击报告程序text/plain或时，text/*将导致响应正文被格式化为纯文本TAP报告。 +% 使用xunit报告程序时，application/xml或text/xml将导致响应正文被格式化为XML而不是JSONML。 +% 否则，响应主体将被格式化为非prettyprinted JSON。 +% 返回码 +% 200：如果请求成功，则返回。 +runFoxxTest(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/tests", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], undefined). + +% 启用开发模式 +% POST /_api/foxx/development +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 将服务置于开发模式。 +% 当服务在开发模式下运行时，每次服务处理请求时，将从文件系统重新加载服务，并且将重新执行其设置脚本（如果有）。 +% 在具有多个协调器的集群中运行ArangoDB时，请注意，一个协调器上文件系统的更改不会在其他协调器上反映出来。这意味着只要任何服务都在开发模式下运行，就应该将协调器视为不一致。 +% 返回码 +% 200：如果请求成功，则返回。 +enableFoxxDevelopment(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/development", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], undefined). + +% 禁用开发模式 +% DELETE /_api/foxx/development +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 将给定安装路径上的服务置于生产模式。 +% 在具有多个协调器的集群中运行ArangoDB时，这会将所有其他协调器上的服务替换为该协调器上的版本。 +% 返回码 +% 200：如果请求成功，则返回。 +disableFoxxDevelopment(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/development", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +% 服务自述文件 +% GET /_api/foxx/readme +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 获取服务的README或README.md文件的内容（如果有）。 +% 返回码 +% 200：如果请求成功，则返回。 +% 204：如果未找到自述文件，则返回。 +getFoxxReadme(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/readme", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 招摇说明 +% GET /_api/foxx/swagger +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 在给定的安装路径中获取服务的Swagger API描述。 +% 响应主体将是服务API的与OpenAPI 2.0兼容的JSON描述。 +% 返回码 +% 200：如果请求成功，则返回。 +getFoxxSwagger(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/swagger", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 下载服务包 +% POST /_api/foxx/download +% 查询参数 +% mount（必需）：已安装服务的安装路径。 +% 下载服务目录的zip捆绑包。 +% 启用开发模式后，将始终创建一个新捆绑包。 +% 否则，捆绑软件将代表该ArangoDB实例上安装的服务的版本。 +% 返回码 +% 200：如果请求成功，则返回。 +% 400：如果安装路径未知，则返回。 +downloadFoxxBundle(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/download", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], undefined). + +% 提交本地服务状态 +% POST /_api/foxx/commit +% 查询参数 +% replace（可选）：覆盖数据库中的现有服务文件，即使它们已经存在也是如此。 +% 将协调器的本地服务状态提交到数据库。 +% 这可用于解决由于数据丢失而无法自动修复的协调器之间的服务冲突。 +% 返回码 +% 204：如果请求成功，则返回。 +commitFoxxState(PoolNameOrSocket, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/foxx/commit", QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], undefined). \ No newline at end of file diff --git a/src/agApi/agGeneralGraphs.erl b/src/agApi/agGeneralGraphs.erl new file mode 100644 index 0000000..ce3af8e --- /dev/null +++ b/src/agApi/agGeneralGraphs.erl @@ -0,0 +1,961 @@ +-module(agGeneralGraphs). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +%% doc_address:https://www.arangodb.com/docs/stable/http/gharial.html + +% 通用图 +% 本章介绍了多集合图形模块的REST接口。它允许您定义分布在多个边缘和文档集合中的图形。无需在查询中包括引用的集合，此模块将为您处理。 + +% 管理图表 +% 列出图形模块已知的所有图形。 +% GET /_api/gharial +% 列出此数据库中存储的所有图形。 +% 如果模块可用并且可以列出图形，则返回HTTP 200。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% 图表： +% graph：有关新创建的图的信息 +% name：图形名称 +% edgeDefinitions：图形关系的定义数组。每个都有以下类型： +% orphanCollections：其他顶点集合的数组。这些集合中的文档在此图中没有边。 +% numberOfShards：为图中的每个新集合创建的分片数。 +% _id：此图的内部ID值。 +% _rev：此图的修订版。可用于确保不覆盖对该图的并发修改。 +% ReplicationFactor：图形中每个新集合使用的复制因子。 +% isSmart：标记图形是否为SmartGraph（仅限企业版）。 +% smartGraphAttribute：智能图例中的分片属性名称（仅企业版） +graphList(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, <<"/_api/gharial">>, [], undefined). + +% 创建一个图 +% 在图形模块中创建一个新图形。 +% POST /_api/gharial +% 查询参数 +% waitForSync（可选）：定义请求是否应该等待，直到所有内容都同步到光盘。将更改成功响应代码。 +% 具有以下属性的JSON对象是必需的： +% name：图形名称。 +% edgeDefinitions：图形关系的定义数组。每个都有以下类型： +% collection : 边集合名 +% from: from 顶点集合名数组、 +% to : to 顶点集合名数组 +% orphanCollections：其他顶点集合的数组。这些集合中的文档在此图中没有边。 +% isSmart：定义创建的图形是否应该是智能的。这仅在企业版中有效。 +% options：一个JSON对象，用于定义用于在此图中创建集合的选项。它可以包含以下属性： +% smartGraphAttribute：仅在企业版中有效，如果isSmart为true，则为必需。用于聪明地分割图的顶点的属性名称。此SmartGraph中的每个顶点都必须具有此属性。以后无法修改。 +% numberOfShards：此图中每个集合使用的分片数。以后无法修改。 +% replicationFactor：最初为此图创建集合时使用的复制因子。可以设置为"satellite"创建SatelliteGraph，将忽略 numberOfShards，minReplicationFactor和writeConcern。 +% writeConcern：对图中的新集合进行关注。它确定在不同的DB服务器上同步每个分片需要多少个副本。如果集群中的副本数量很少，那么分片将拒绝写入。但是，具有足够最新副本的分片写入将同时成功。writeConcern的值 不能大于ReplicationFactor。（仅集群） +% 图的创建需要图的名称和其边缘的定义。 另请参见边缘定义。 +% 如果可以创建图形并且为_graphs集合启用了waitForSync 或在请求中指定了图形，则返回HTTP 201。响应主体包含已存储的图形配置。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关新创建的图的信息。 +% 如果可以创建图形并且为该_graphs集合禁用了waitForSync，并且未在请求中给出，则返回HTTP 202。响应主体包含已存储的图形配置。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关新创建的图的信息。 +% HTTP 400如果请求的格式错误，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 403如果您的用户权限不足，则返回。为了创建图，您至少需要具有以下特权： +% Administrate 访问数据库。 +% Read Only +% 访问此图中使用的每个集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 409如果存储图形时发生冲突，则返回。如果已经存储了具有该名称的图形，或者存在一个边缘定义具有相同的边缘集合但在任何其他图形中使用了不同的签名，则可能会发生这种情况 。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +newGraph(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, <<"/_api/gharial">>, [], BodyStr). + +newGraph(PoolNameOrSocket, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial", QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +% 获取图表 +% GET /_api/gharial/{graph} +% 路径参数 +% 图（必填）：图的名称。 +% 选择给定图的信息。将返回边缘定义以及孤立集合。或如果图形不存在，则返回404。 +% HTTP 200如果可以找到该图，则返回该图。结果将具有以下格式： +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关新创建的图的信息 +% HTTP 404如果找不到具有该名称的图形，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +getGraph(PoolNameOrSocket, GraphName) -> + Path = <<"/_api/gharial/", GraphName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 删除现有图 +% DELETE /_api/gharial/{graph} +% 路径参数 +% 图（必填）：图的名称。 +% 查询参数 +% dropCollections（可选）：也删除该图的集合。只有在其他图形中未使用集合时，集合才会被删除。 +% 按名称删除现有图形对象。（可选）也可以删除其他图未使用的所有集合。 +% 201：如果可以删除该图并为该_graphs集合启用了waitForSync ，或者在请求中给出了该图，则返回该值。 +% 202：如果可以删除该图并且为该_graphs集合禁用了waitForSync，并且未在请求中给出，则返回该值。 +% HTTP 403如果您的用户权限不足，则返回。为了删除图，您至少需要具有以下特权： +% Administrate 访问数据库。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 404如果找不到具有该名称的图形，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +delGraph(PoolNameOrSocket, GraphName) -> + Path = <<"/_api/gharial/", GraphName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delGraph(PoolNameOrSocket, GraphName, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +% 列出此图中使用的所有顶点集合。 +% GET /_api/gharial/{graph}/vertex +% 路径参数 +% graph（必填）：图的名称。 +% 列出此图中的所有顶点集合。 +% 如果可以列出集合，则返回HTTP 200。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% collections：此图中所有顶点集合的列表。在edgeDefinitions和孤儿中包括集合。 +% HTTP 404如果找不到具有该名称的图形，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +vertexCollList(PoolNameOrSocket, GraphName) -> + Path = <<"/_api/gharial/", GraphName/binary, "/vertex">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 向图中添加一个额外的顶点集合。 +% POST /_api/gharial/{graph}/vertex +% 路径参数 +% graph（必填）：图的名称。 +% 将顶点集合添加到图形的孤立集合中。如果该集合不存在，则将创建它。 +% 如果可以创建集合并为该_graphs集合启用waitForSync 或在请求中指定了HTTP，则返回HTTP 201。响应主体包含已存储的图形配置。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关修改后的图的信息。 +% 如果可以创建集合并且为该_graphs集合禁用了waitForSync 或在请求中指定了HTTP，则返回HTTP 202。响应主体包含已存储的图形配置。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关新创建的图的信息 +% HTTP 400如果请求的格式无效，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 403如果您的用户权限不足，则返回。为了修改图，您至少需要具有以下特权： +% Administrate 访问数据库。 +% Read Only 访问此图中使用的每个集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 404如果找不到具有该名称的图形，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 + +%% MapData = #{"collection" => "otherVertices"} +addVertexColl(PoolNameOrSocket, GraphName, MapData) -> + Path = <<"/_api/gharial/", GraphName/binary, "/vertex">>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +% 从图形中删除额外顶点集合。 +% DELETE /_api/gharial/{graph}/vertex/{collection} +% 路径参数 +% graph（必填）：图的名称。 +% collection（必填）：顶点集合的名称。 +% 查询参数 +% dropCollection（可选）：也删除集合。只有在其他图形中未使用集合时，集合才会被删除。 +% 如果未在其他任何图中使用顶点集合，则从图中删除顶点集合，并有选择地删除该集合。如果边缘定义中不再使用这些顶点集合，则只能删除不再属于这些定义的顶点集合。 +% HTTP 200如果成功从图形中删除了顶点集合并且waitForSync为true，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关新创建的图的信息 +% HTTP 202如果请求成功，但waitForSync为false，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关新创建的图的信息 +% HTTP 400如果顶点集合仍在边缘定义中使用，则返回。在这种情况下，它仍不能从图形中删除，必须先从边定义中删除。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 403如果您的用户权限不足，则返回。为了删除顶点，您至少需要具有以下特权： +% Administrate 访问数据库。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 404如果找不到具有该名称的图形，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +delVertexColl(PoolNameOrSocket, GraphName, CollName) -> + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delVertexColl(PoolNameOrSocket, GraphName, CollName, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +% 列出所有边缘定义 +% GET /_api/gharial/{graph}/edge +% 路径参数 +% graph（必填）：图的名称。 +% 列出此图中的所有边集合。 +% 如果可以列出边缘定义，则返回HTTP 200。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% collections：此图中所有顶点集合的列表。在edgeDefinitions和孤儿中包括集合。 +% HTTP 404如果找不到具有该名称的图形，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +edgeDefList(PoolNameOrSocket, GraphName) -> + Path = <<"/_api/gharial/", GraphName/binary, "/edge">>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +% 向图添加新的边定义 +% POST /_api/gharial/{graph}/edge +% 路径参数 +% graph（必填）：图的名称。 +% 具有以下属性的JSON对象是必需的： +% collection：要使用的边缘集合的名称。 +% from：一个或多个可以包含源顶点的顶点集合。 +% to：一个或多个可以包含目标顶点的顶点集合。 +% 向图形添加其他边定义。 +% 这个边缘清晰度必须包含一个集合，并且每个的阵列从和到顶点集合。仅当未在任何其他图形中使用该定义或将其与完全相同的定义一起使用时，才可以添加边定义。在一个图中不可能存储从“ v1”到“ v2”的定义“ e”，而在另一张图中存储从“ v2”到“ v1”的定义“ e”。 +% HTTP 201如果可以成功添加定义并且为_graphs集合启用了waitForSync，则返回。响应主体包含已存储的图形配置。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关修改后的图的信息。 +% HTTP 202如果可以成功添加定义并且对该_graphs集合禁用了waitForSync，则返回。响应主体包含已存储的图形配置。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关修改后的图的信息。 +% HTTP 400如果无法添加定义，则返回。这可能是因为其格式错误，或者是在其他具有不同签名的图形中使用了该定义。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 403如果您的用户权限不足，则返回。为了修改图，您至少需要具有以下特权： +% Administrate 访问数据库。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 404如果找不到具有该名称的图形，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +addEdgeDef(PoolNameOrSocket, GraphName, MapData) -> + Path = <<"/_api/gharial/", GraphName/binary, "/edge">>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +% 替换现有的边缘定义 +% PUT /_api/gharial/{graph}/edge/{definition}#definition +% 路径参数 +% graph（必填）：图的名称。 +% definition（必填）：定义中使用的边集合的名称。 +% +% 查询参数 +% waitForSync（可选）：定义请求是否应等待直到同步到磁盘。 +% dropCollections（可选）：也删除集合。只有在其他图形中未使用集合时，集合才会被删除。 +% 具有以下属性的JSON对象是必需的： +% collection：要使用的边缘集合的名称。 +% from：一个或多个可以包含源顶点的顶点集合。 +% to：一个或多个可以包含目标顶点的顶点集合。 +% 更改一个特定的边定义。这将修改数据库中所有已知图中所有出现的该定义。 +% HTTP 201如果请求成功并且waitForSync为true，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关修改后的图的信息。 +% HTTP 202如果请求成功，但waitForSync为false，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关修改后的图的信息。 +% HTTP 400如果在图形中未找到具有此名称的边定义，或者新定义的格式不正确且无法使用，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 403如果您的用户权限不足，则返回。为了删除顶点，您至少需要具有以下特权： +% Administrate 访问数据库。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 404如果找不到具有该名称的图形，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% EdgeDefName 名字 要在定义列表中存在 MapData中的collection 也要存在 只是替换 from to 中的集合 +replaceEdgeDef(PoolNameOrSocket, GraphName, EdgeDefName, MapData) -> + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", EdgeDefName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +replaceEdgeDef(PoolNameOrSocket, GraphName, EdgeDefName, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", EdgeDefName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +% 从图形中删除边缘定义 +% DELETE /_api/gharial/{graph}/edge/{definition}#definition +% 路径参数 +% graph（必填）：图的名称。 +% definition（必填）：定义中使用的边集合的名称。 +% 查询参数 +% waitForSync（可选）：定义请求是否应等待直到同步到磁盘。 +% dropCollections（可选）：也删除集合。只有在其他图形中未使用集合时，集合才会被删除。 +% 从图形中删除一个边缘定义。这只会删除边缘集合，顶点集合保持不变，并且仍可以在查询中使用。 +% HTTP 201如果可以从图形中删除边缘定义并且waitForSync为true，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关修改后的图的信息。 +% HTTP 202如果可以从图形中删除边缘定义并且waitForSync为false，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关修改后的图的信息。 +% HTTP 403如果您的用户权限不足，则返回。为了删除顶点，您至少需要具有以下特权： +% Administrate 访问数据库。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 404如果找不到该名称的图形，或者在图形中找不到此名称的边定义，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +delEdgeDef(PoolNameOrSocket, GraphName, EdgeDefName) -> + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", EdgeDefName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delEdgeDef(PoolNameOrSocket, GraphName, EdgeDefName, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", EdgeDefName/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +% 处理顶点 + +% 创建一个新顶点 +% POST /_api/gharial/{graph}/vertex/{collection} +% 路径参数 +% graph（必填）：图的名称。 +% collection（必填）：顶点应插入的顶点集合的名称。 +% 查询参数 +% waitForSync（可选）：定义请求是否应等待直到同步到磁盘。 +% returnNew（可选）：定义响应是否应包含文档的完整新版本。 +% 请求正文（对象） +% 主体必须是要存储的JSON对象。 +% 将顶点添加到给定的集合。 +% HTTP 201如果可以添加顶点并且waitForSync为true，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% vertex：顶点的内部属性。 +% new：完整的新编写的顶点文档。包括请求主体中的所有书面属性以及ArangoDB生成的所有内部属性。仅在returnNew为true时存在。 +% HTTP 202如果请求成功，但waitForSync为false，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% vertex：存储顶点时生成的内部属性。不包括请求正文中给定的任何属性。 +% new：完整的新编写的顶点文档。包括请求主体中的所有书面属性以及ArangoDB生成的所有内部属性。仅在returnNew为true时存在。 +% HTTP 403如果您的用户权限不足，则返回。为了将顶点插入到图中，您至少需要具有以下特权： +% Read Only 访问数据库。 +% Write 访问给定的集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 404如果找不到具有该名称的图形，则返回。或者，如果找到了图，但是此集合不是图的一部分。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +newVertex(PoolNameOrSocket, GraphName, CollName, MapData) -> + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +newVertex(PoolNameOrSocket, GraphName, CollName, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +% 获取现有顶点 +% GET /_api/gharial/{graph}/vertex/{collection}/{vertex} +% 路径参数 +% graph（必填）：图的名称。 +% collection（必需）：顶点所属的顶点集合的名称。 +% vertex（必填）：顶点的_key属性。 +% 查询参数 +% rev（可选）：必须包含修订。如果设置了此选项，则仅在具有此修订版本的情况下才返回文档。另请参见if-match标头作为替代方法。 +% 标头参数 +% if-match（可选）：如果给出了“ If-Match”标头，则它必须恰好包含一个Etag。如果文档的版本与给定的Etag相同，则返回文档。否则，返回HTTP 412。或者，您可以在查询参数rev中提供Etag 。 +% if-none-match（可选）：如果给出了“ If-None-Match”标头，则它必须恰好包含一个Etag。仅当文档的版本与给定的Etag不同时，才返回文档。否则，返回HTTP 304。 +% 从给定的集合中获取一个顶点。 +% HTTP 200如果可以找到顶点，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% vertex：完整的顶点。 +% HTTP 304如果给出了if-none-match标头，并且当前存储的顶点仍具有此修订值，则返回。因此，在上一次调用者获取顶点之间没有更新。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 403如果您的用户权限不足，则返回。为了更新图中的顶点，您至少需要具有以下特权： +% Read Only 访问数据库。 +% Read Only 访问给定的集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% 在以下情况下返回HTTP 404： +% 找不到具有该名称的图。 +% 该集合不属于图形。 +% 顶点不存在。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 412如果给出了if-match标头，则返回，但是存储的文档版本不同。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +getVertex(PoolNameOrSocket, GraphName, CollName, VertexKey) -> + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, "/", (agMiscUtils:toBinary(VertexKey))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +getVertex(PoolNameOrSocket, GraphName, CollName, VertexKey, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, "/", (agMiscUtils:toBinary(VertexKey))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +getVertex(PoolNameOrSocket, GraphName, CollName, VertexKey, QueryPars, Headers) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, "/", (agMiscUtils:toBinary(VertexKey))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, Headers, undefined). + +% 更新现有顶点 +% PATCH /_api/gharial/{graph}/vertex/{collection}/{vertex} +% 路径参数 +% graph（必填）：图的名称。 +% collection（必需）：顶点所属的顶点集合的名称。 +% vertex（必填）：顶点的_key属性。 +% 查询参数 +% waitForSync（可选）：定义请求是否应等待直到同步到磁盘。 +% keepNull（可选）：定义是否应存储设置为null的值。默认情况下（true），给定的documents（s）属性将设置为null。如果此参数为false，则将属性从文档中删除。 +% returnOld（可选）：定义是否应在响应对象内返回已删除文档的表示。 +% returnNew（可选）：定义是否应在响应对象中返回新文档的表示形式。 +% 标头参数 +% if-match（可选）：如果给出了“ If-Match”标头，则它必须恰好包含一个Etag。如果文档的版本与给定的Etag相同，则文档将被更新。否则，返回HTTP 412。或者，您可以在URL的属性rev中提供Etag。 +% 请求正文（对象） +% 主体必须包含一个JSON对象，该对象完全包含应被覆盖的属性，所有其他属性保持不变。 +% 更新集合中特定顶点的数据。 +% HTTP 200如果可以更新顶点且waitForSync为true，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% vertex：顶点的内部属性。 +% new：完整的新编写的顶点文档。包括请求主体中的所有书面属性以及ArangoDB生成的所有内部属性。仅在returnNew为true时存在。 +% old：完整的覆盖顶点文档。包括此操作之前存储的所有属性。仅在returnOld为true时存在。 +% HTTP 202如果请求成功，则返回，并且waitForSync为false。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% vertex：顶点的内部属性。 +% new：完整的新编写的顶点文档。包括请求主体中的所有书面属性以及ArangoDB生成的所有内部属性。仅在returnNew为true时存在。 +% old：完整的覆盖顶点文档。包括此操作之前存储的所有属性。仅在returnOld为true时存在。 +% HTTP 403如果您的用户权限不足，则返回。为了更新图中的顶点，您至少需要具有以下特权： +% Read Only 访问数据库。 +% Write 访问给定的集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% 在以下情况下返回HTTP 404： +% 找不到具有该名称的图。 +% 该集合不属于图形。 +% 要更新的顶点不存在。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 412如果给出了if-match标头，则返回，但是存储的文档版本不同。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +updateVertex(PoolNameOrSocket, GraphName, CollName, VertexKey, MapData) -> + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, "/", (agMiscUtils:toBinary(VertexKey))/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, [], BodyStr). + +updateVertex(PoolNameOrSocket, GraphName, CollName, VertexKey, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, "/", (agMiscUtils:toBinary(VertexKey))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, [], BodyStr). + +updateVertex(PoolNameOrSocket, GraphName, CollName, VertexKey, MapData, QueryPars, Headers) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, "/", (agMiscUtils:toBinary(VertexKey))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, Headers, BodyStr). + +% 替换现有的顶点 +% PUT /_api/gharial/{graph}/vertex/{collection}/{vertex} +% 路径参数 +% graph（必填）：图的名称。 +% collection（必需）：顶点所属的顶点集合的名称。 +% vertex（必填）：顶点的_key属性。 +% 查询参数 +% waitForSync（可选）：定义请求是否应等待直到同步到磁盘。 +% keepNull（可选）：定义是否应存储设置为null的值。默认情况下，密钥不会从文档中删除。 +% returnOld（可选）：定义是否应在响应对象内返回已删除文档的表示。 +% returnNew（可选）：定义是否应在响应对象中返回新文档的表示形式。 +% 标头参数 +% if-match（可选）：如果给出了“ If-Match”标头，则它必须恰好包含一个Etag。如果文档的版本与给定的Etag相同，则文档将被更新。否则，返回HTTP 412。或者，您可以在URL的属性rev中提供Etag。 +% 请求正文（对象） +% 主体必须是要存储的JSON对象。 +% 替换集合中顶点的数据。 +% HTTP 200如果可以替换顶点且waitForSync为true，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% vertex：顶点的内部属性。 +% new：完整的新编写的顶点文档。包括请求主体中的所有书面属性以及ArangoDB生成的所有内部属性。仅在returnNew为true时存在。 +% old：完整的覆盖顶点文档。包括此操作之前存储的所有属性。仅在returnOld为true时存在。 +% HTTP 202如果可以替换顶点且waitForSync为false，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% vertex：顶点的内部属性。 +% new：完整的新编写的顶点文档。包括请求主体中的所有书面属性以及ArangoDB生成的所有内部属性。仅在returnNew为true时存在。 +% old：完整的覆盖顶点文档。包括此操作之前存储的所有属性。仅在returnOld为true时存在。 +% HTTP 403如果您的用户权限不足，则返回。为了替换图中的顶点，您至少需要具有以下特权： +% Read Only 访问数据库。 +% Write 访问给定的集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% 在以下情况下返回HTTP 404： +% 找不到具有该名称的图。 +% 该集合不属于图形。 +% 要替换的顶点不存在。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 412如果给出了 if -match标头，则返回，但是存储的文档版本不同。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +replaceVertex(PoolNameOrSocket, GraphName, CollName, VertexKey, MapData) -> + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, "/", (agMiscUtils:toBinary(VertexKey))/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +replaceVertex(PoolNameOrSocket, GraphName, CollName, VertexKey, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, "/", (agMiscUtils:toBinary(VertexKey))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +replaceVertex(PoolNameOrSocket, GraphName, CollName, VertexKey, MapData, QueryPars, Headers) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, "/", (agMiscUtils:toBinary(VertexKey))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, Headers, BodyStr). + +% 从图中删除顶点 +% DELETE /_api/gharial/{graph}/vertex/{collection}/{vertex} +% 路径参数 +% graph（必填）：图的名称。 +% collection（必需）：顶点所属的顶点集合的名称。 +% vertex（必填）：顶点的_key属性。 +% 查询参数 +% waitForSync（可选）：定义请求是否应等待直到同步到磁盘。 +% returnOld（可选）：定义是否应在响应对象内返回已删除文档的表示。 +% 标头参数 +% if-match（可选）：如果给出了“ If-Match”标头，则它必须恰好包含一个Etag。如果文档的版本与给定的Etag相同，则文档将被更新。否则，返回HTTP 412。或者，您可以在URL的属性rev中提供Etag。 +% 从集合中删除一个顶点。 +% HTTP 200如果可以删除顶点，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% removed：设置为true，如果删除成功。 +% old：完整的删除的顶点文档。包括此操作之前存储的所有属性。仅在returnOld为true时存在。 +% HTTP 202如果请求成功，但waitForSync为false，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% removed：设置为true，如果删除成功。 +% old：完整的删除的顶点文档。包括此操作之前存储的所有属性。仅在returnOld为true时存在。 +%HTTP 403如果您的用户权限不足，则返回。为了删除图中的顶点，您至少需要具有以下特权： +% Read Only 访问数据库。 +% Write 访问给定的集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% 在以下情况下返回HTTP 404： +% 找不到具有该名称的图。 +% 该集合不属于图形。 +% 要删除的顶点不存在。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 412如果给出了if-match标头，则返回，但是存储的文档版本不同。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +delVertex(PoolNameOrSocket, GraphName, CollName, VertexKey) -> + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, "/", (agMiscUtils:toBinary(VertexKey))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delVertex(PoolNameOrSocket, GraphName, CollName, VertexKey, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, "/", (agMiscUtils:toBinary(VertexKey))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delVertex(PoolNameOrSocket, GraphName, CollName, VertexKey, QueryPars, Headers) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/vertex/", CollName/binary, "/", (agMiscUtils:toBinary(VertexKey))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, Headers, undefined). + +% 处理边缘 +% 在现有图形中创建边 +% POST /_api/gharial/{graph}/edge/{collection} +% 路径参数 +% graph（必填）：图的名称。 +% collection（必填）：边缘所属的边缘集合的名称。 +% 查询参数 +% waitForSync（可选）：定义请求是否应等待直到同步到磁盘。 +% returnNew（可选）：定义响应是否应包含文档的完整新版本。 +% 具有以下属性的JSON对象是必需的： +% _from：此边的源顶点。必须在使用的边定义内有效。 +% _to：此边的目标顶点。必须在使用的边定义内有效。 +% 在集合中创建新边缘。在主体内，边缘必须包含一个_from和_to值，以引用图中的有效顶点。此外，边缘在所使用的边缘集合的定义中必须有效 。 +% HTTP 201如果可以创建边缘并且waitForSync为true，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% edge：边缘的内部属性。 +% new：完整的新编写的边缘文档。包括请求主体中的所有书面属性以及ArangoDB生成的所有内部属性。仅在returnNew为true时存在。 +% HTTP 202如果请求成功，但waitForSync为false，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% edge：边缘的内部属性。 +% new：完整的新编写的边缘文档。包括请求主体中的所有书面属性以及ArangoDB生成的所有内部属性。仅在returnNew为true时存在。 +% HTTP 400如果输入文档无效，则返回。例如，这可以是如果_from或_to丢失。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 403如果您的用户权限不足，则返回。为了将边插入图形中，您至少需要具有以下特权： +% Read Only 访问数据库。 +% Write 访问给定的集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% 在以下任何一种情况下返回的HTTP 404： +% 找不到具有该名称的图形。 +% 该边缘集合不是图形的一部分。 +% 无论是_from或_to顶点不存在。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +newEdge(PoolNameOrSocket, GraphName, CollName, MapData) -> + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +newEdge(PoolNameOrSocket, GraphName, CollName, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPost, Path, [], BodyStr). + +% 获得边 +% GET /_api/gharial/{graph}/edge/{collection}/{edge} +% 路径参数 +% graph（必填）：图的名称。 +% collection（必填）：边缘所属的边缘集合的名称。 +% edge（必填）：边缘的_key属性。 +% 查询参数 +% rev（可选）：必须包含修订。如果设置了此选项，则仅在具有此修订版本的情况下才返回文档。另请参见if-match标头作为替代方法。 +% 标头参数 +% if-match（可选）：如果给出了“ If-Match”标头，则它必须恰好包含一个Etag。如果文档的版本与给定的Etag相同，则返回文档。否则，返回HTTP 412。或者，您可以在URL的属性rev中提供Etag。 +% if-none-match（可选）：如果给出了“ If-None-Match”标头，则它必须恰好包含一个Etag。仅当文档的版本与给定的Etag不同时，才返回文档。否则，返回HTTP 304。 +% 从给定的集合中获取一条边。 +% HTTP 200如果可以找到边缘，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% edge：完整的边缘。 +% HTTP 304如果给出了if-none-match标头，并且当前存储的边缘仍具有此修订值，则返回。因此，调用者上一次获取边缘之间没有更新。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 403如果您的用户权限不足，则返回。为了更新图中的顶点，您至少需要具有以下特权： +% Read Only 访问数据库。 +% Read Only 访问给定的集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% 在以下情况下返回HTTP 404： +% 找不到具有该名称的图。 +% 该集合不属于图形。 +% 边不存在。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 412如果给出了if-match标头，则返回，但是存储的文档版本不同。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +getEdge(PoolNameOrSocket, GraphName, CollName, EdgeKey) -> + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, "/", (agMiscUtils:toBinary(EdgeKey))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +getEdge(PoolNameOrSocket, GraphName, CollName, EdgeKey, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, "/", (agMiscUtils:toBinary(EdgeKey))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, [], undefined). + +getEdge(PoolNameOrSocket, GraphName, CollName, EdgeKey, QueryPars, Headers) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, "/", (agMiscUtils:toBinary(EdgeKey))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgGet, Path, Headers, undefined). + +% 修改现有边 +% PATCH /_api/gharial/{graph}/edge/{collection}/{edge} +% 路径参数 +% graph（必填）：图的名称。 +% collection（必填）：边缘所属的边缘集合的名称。 +% edge（必填）：顶点的_key属性。 +% 查询参数 +% waitForSync（可选）：定义请求是否应等待直到同步到磁盘。 +% keepNull（可选）：定义是否应存储设置为null的值。默认情况下（true），给定的documents（s）属性将设置为null。如果此参数为false，则将从文档中删除该属性。 +% returnOld（可选）：定义是否应在响应对象内返回已删除文档的表示。 +% returnNew（可选）：定义是否应在响应对象中返回新文档的表示形式。 +% 标头参数 +% if-match（可选）：如果给出了“ If-Match”标头，则它必须恰好包含一个Etag。如果文档的版本与给定的Etag相同，则文档将被更新。否则，返回HTTP 412。或者，您可以在URL的属性rev中提供Etag。 +% 请求正文（对象） +% 主体必须包含一个JSON对象，该对象完全包含应被覆盖的属性，所有其他属性保持不变。 +% 更新集合中特定边的数据。 +% HTTP 200如果可以更新边缘，并且waitForSync为false，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% edge：边缘的内部属性。 +% new：完整的新编写的边缘文档。包括请求主体中的所有书面属性以及ArangoDB生成的所有内部属性。仅在returnNew为true时存在。 +% old：完整的覆盖边缘文档。包括此操作之前存储的所有属性。仅在returnOld为true时存在。 +% HTTP 202如果请求成功，但waitForSync为false，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% edge：边缘的内部属性。 +% new：完整的新编写的边缘文档。包括请求主体中的所有书面属性以及ArangoDB生成的所有内部属性。仅在returnNew为true时存在。 +% old：完整的覆盖边缘文档。包括此操作之前存储的所有属性。仅在returnOld为true时存在。 +% HTTP 403如果您的用户权限不足，则返回。为了更新图中的边，您至少需要具有以下特权： +% Read Only 访问数据库。 +% Write 访问给定的集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% 在以下情况下返回HTTP 404： +% 找不到具有该名称的图。 +% 该集合不属于图形。 +% 要更新的边缘不存在。 +% 无论是_from或_to顶点不存在（如果更新）。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 412如果给出了if-match标头，则返回，但是存储的文档版本不同。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +updateEdge(PoolNameOrSocket, GraphName, CollName, EdgeKey, MapData) -> + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, "/", (agMiscUtils:toBinary(EdgeKey))/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, [], BodyStr). + +updateEdge(PoolNameOrSocket, GraphName, CollName, EdgeKey, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, "/", (agMiscUtils:toBinary(EdgeKey))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, [], BodyStr). + +updateEdge(PoolNameOrSocket, GraphName, CollName, EdgeKey, MapData, Headers, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, "/", (agMiscUtils:toBinary(EdgeKey))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPatch, Path, Headers, BodyStr). + + +% 替换现有边的内容 +% PUT /_api/gharial/{graph}/edge/{collection}/{edge} +% 路径参数 +% graph（必填）：图的名称。 +% collection（必填）：边缘所属的边缘集合的名称。 +% edge（必填）：顶点的_key属性。 +% 查询参数 +% waitForSync（可选）：定义请求是否应等待直到同步到磁盘。 +% keepNull（可选）：定义是否应存储设置为null的值。默认情况下，密钥不会从文档中删除。 +% returnOld（可选）：定义是否应在响应对象内返回已删除文档的表示。 +% returnNew（可选）：定义是否应在响应对象中返回新文档的表示形式。 +% 标头参数 +% if-match（可选）：如果给出了“ If-Match”标头，则它必须恰好包含一个Etag。如果文档的版本与给定的Etag相同，则文档将被更新。否则，返回HTTP 412。或者，您可以在URL的属性rev中提供Etag。 +% 具有以下属性的JSON对象是必需的： +% _from：此边的源顶点。必须在使用的边定义内有效。 +% _to：此边的目标顶点。必须在使用的边定义内有效。 +% 替换集合中边的数据。 +% HTTP 201如果请求成功但waitForSync为true，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% edge：边的内部属性 +% new：完整的新编写的边缘文档。包括请求主体中的所有书面属性以及ArangoDB生成的所有内部属性。仅在returnNew为true时存在。 +% old：完整的覆盖边缘文档。包括此操作之前存储的所有属性。仅在returnOld为true时存在。 +% HTTP 202如果请求成功，但waitForSync为false，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% edge：边的内部属性 +% new：完整的新编写的边缘文档。包括请求主体中的所有书面属性以及ArangoDB生成的所有内部属性。仅在returnNew为true时存在。 +% old：完整的覆盖边缘文档。包括此操作之前存储的所有属性。仅在returnOld为true时存在。 +% HTTP 403如果您的用户权限不足，则返回。为了替换图中的边，您至少需要具有以下特权： +% Read Only 访问数据库。 +% Write 访问给定的集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% 在以下情况下返回HTTP 404： +% 找不到具有该名称的图。 +% 该集合不属于图形。 +% 替换的边不存在。 +% 无论是_from或_to顶点不存在。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 412如果给出了if-match标头，则返回，但是存储的文档版本不同。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +replaceEdge(PoolNameOrSocket, GraphName, CollName, EdgeKey, MapData) -> + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, "/", (agMiscUtils:toBinary(EdgeKey))/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +replaceEdge(PoolNameOrSocket, GraphName, CollName, EdgeKey, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, "/", (agMiscUtils:toBinary(EdgeKey))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, [], BodyStr). + +replaceEdge(PoolNameOrSocket, GraphName, CollName, EdgeKey, MapData, QueryPars, Headers) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, "/", (agMiscUtils:toBinary(EdgeKey))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?AgPut, Path, Headers, BodyStr). + +% 从图形中删除边 +% DELETE /_api/gharial/{graph}/edge/{collection}/{edge} +% 路径参数 +% graph（必填）：图的名称。 +% collection（必填）：边缘所属的边缘集合的名称。 +% edge（必填）：边缘的_key属性。 +% 查询参数 +% waitForSync（可选）：定义请求是否应等待直到同步到磁盘。 +% returnOld（可选）：定义是否应在响应对象内返回已删除文档的表示。 +% 标头参数 +% if-match（可选）：如果给出了“ If-Match”标头，则它必须恰好包含一个Etag。如果文档的版本与给定的Etag相同，则文档将被更新。否则，返回HTTP 412。或者，您可以在URL的属性rev中提供Etag。 +% 从集合中删除边缘。 +% HTTP 200如果可以删除边缘，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% removed：设置为true，如果删除成功。 +% old：完整的已删除边缘文档。包括此操作之前存储的所有属性。仅在returnOld为true时存在。 +% HTTP 202如果请求成功，但waitForSync为false，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% removed：设置为true，如果删除成功。 +% old：完整的已删除边缘文档。包括此操作之前存储的所有属性。仅在returnOld为true时存在。 +% HTTP 403如果您的用户权限不足，则返回。为了删除图中的顶点，您至少需要具有以下特权： +% Read Only 访问数据库。 +% Write 访问给定的集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% 在以下情况下返回HTTP 404： +% 找不到具有该名称的图。 +% 该集合不属于图形。 +% 要删除的边缘不存在。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 412如果给出了if-match标头，则返回，但是存储的文档版本不同。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +delEdge(PoolNameOrSocket, GraphName, CollName, EdgeKey) -> + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, "/", (agMiscUtils:toBinary(EdgeKey))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delEdge(PoolNameOrSocket, GraphName, CollName, EdgeKey, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, "/", (agMiscUtils:toBinary(EdgeKey))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, [], undefined). + +delEdge(PoolNameOrSocket, GraphName, CollName, EdgeKey, Headers, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/gharial/", GraphName/binary, "/edge/", CollName/binary, "/", (agMiscUtils:toBinary(EdgeKey))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?AgDelete, Path, Headers, undefined). + + diff --git a/src/agApi/agHotBackup.erl b/src/agApi/agHotBackup.erl new file mode 100644 index 0000000..78623e3 --- /dev/null +++ b/src/agApi/agHotBackup.erl @@ -0,0 +1,116 @@ +-module(agHotBackup). +-include("erlArango.hrl"). + +-compile(inline). +-compile({inline_size, 128}). +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/hot-backup.html + +% HTTP接口进行热备份和还原 +% 在v3.5.1中引入 +% 这是用于热备份和还原的ArangoDB HTTP接口的简介。 +% 热备份仅在企业版中可用 。 +% 热备份 +% 热备份接近整个 ArangoDB服务的即时一致快照 。这包括在任何给定时间的所有数据库，集合，索引，视图定义和用户。 +% 对于创建，可以指定标签，如果省略，则将其替换为生成的UUID。然后，此标签与时间戳组合以为创建的热备份生成标识符。随后，所有其他API在这些标识符上运行。 +% 以下API专用于处理POST操作。 +% 使用API​​之前，请确保了解热备份的所有方面，以及所有要求和限制。 + +% 创建本地备份 +% POST /_admin/backup/create +% 具有以下属性的JSON对象是必需的： +% label：此备份的标签。该标签与时间戳字符串一起使用，创建唯一的备份标识符_