Data processing

You can add, update, and delete documents, and perform these operations in batches.

• URL

  /v3/openapi/apps/$app_name/$table_name/actions/bulk

  • $app_name specifies the name of the application that you want to manage.

  • $table_name specifies the name of the table in the application to which you want to push data.

  • The preceding URL omits request header parameters and encoding.

  • The preceding URL omits the host address used to access the application.

Supported format: JSON

HTTP request method: POST

Request parameters

For information about the signatures and request headers required for push operations, see the v3 API signature mechanism topic.

Document data format

The following example shows the data format:

[
    {
        "cmd": "add",
        "timestamp": 1401342874777,
        "fields": {
            "id": "1",
            "title": "This is the title",
            "body": "This is the body"
        }
    },
    {
        "cmd": "delete",
        "fields": {
            "id": "2"
        }
    }
]

• cmd: required. Specifies the operation to perform on the document. Valid values: "add" and "delete". We recommend that you perform batch updates in a single request to improve network interaction and processing efficiency. "add" adds a document. If a document with the same primary key already exists, the system first performs "delete" and then "add". "delete" deletes a document. If no document corresponds to the primary key, the deletion is considered successful.

• fields: required. The content of the document to be processed. The primary key field is required because all system operations are performed based on primary keys. For "delete", you only need to provide the primary key of the document.

• Array-type fields must be specified as JsonArray, for example, [{“fields”: { “id”: “0”,”int_array”: [14,85],”string_array”: [“abc”,”xyz”]},”cmd”: “ADD”}].

• Note: The outermost layer is of the JsonArray type, which supports batch operations on multiple documents.

Response

Example

Request (request header parameters and encoding are omitted):

http://host/v3/openapi/apps/app_schema_demo/tab/actions/bulk

//The following data to be uploaded must be placed in the request body
[{"cmd":"ADD","fields":{"id":1,"name":"Test Data Push"}}]

Success response

{
    "errors": [],
    "request_id": "150116724719940316170289",
    "status": "OK",
    "result": true
}

Error response

{
    "errors": [
        {
            "code": 2001,
            "message": "待查应用不存在.待查应用不存在。",
            "params": {
                "friendly_message": "待查应用不存在。"
            }
        }
    ],
    "request_id": "150116732819940316116461",
    "status": "FAIL"
}

Usage notes

• When you push data by using APIs or SDKs, application field names are case-insensitive.

• Data pushes by using APIs or SDKs are subject to limits on the number of pushes and data size, and the limits vary by application. For more information, see Limits.

• After you upload data, you must check the return value and retry the request for the relevant error codes (especially error 3007). Otherwise, data may be lost. In addition, data processing is asynchronous. A returned "OK" only indicates that the system has successfully received the data. Errors that occur during data processing are displayed in the error information in the console. Check them in a timely manner.

• The size of POST data is limited. If the total size of the documents that you upload is too large (2 MB before encoding), the server rejects all parameters and returns an exception.

• If the body of a POST push request contains Chinese characters, the data must be UTF-8 encoded. The same applies to the Content-MD5 parameter in the header: the data must be UTF-8 encoded before its MD5 value is calculated. Otherwise, push errors occur.