Create Download Request¶

Create a file download task.

Prerequisites¶

A read channel has been already created and started, and the channel is not a cross-source channel.

Request Format¶

POST https://{apigw-address}/data-federation/v2.0/channels/read/{channelId}/download-request

Request Parameters (URI)¶

Name	Location (Path/Query)	Required/Optional	Data Type	Description
channelId	Path	Required	String	The channel ID which the file download task is using.
orgId	Query	Required	String	The OU ID which the application belongs to. How to get orgId >>

Request Parameters (Body)¶

Name	Required/Optional	Data Type	Description
taskName	Required	String	Specify the name of the file download task.
sourceName	Required	String	Specifies the data source bound to the read channel. Supports the Hive(EnOS) data source only, with the value of `hive_enos`.
querySql	Required	String	Specify the SQL query to customize the data content and format for the files.
filePackageName	Required	String	Specify name of the downloaded file.
files	Optional	List<JSON Object>	Configure the information for the downloaded file, including the file encoding method, whether to enable partition download file, etc. File Struct
callbackURL	Optional	String	Specify the URL to receive callback messages. After the download task is completed, the download result notification will be sent to the specified URL address through an HTTP POST request. For details on the response parameters, see CallBackURL Response Parameters.

File Struct¶

Name	Required/Optional	Data Type	Description
split	Required	Boolean	Specify whether to enable the partition download. `true` means to enable partition, `false` means not to enable partition. If enabled, you can use other parameters (such as `fileRename`) to specify which partitions of data to download.
encoding	Required	String	Specify the file encoding method. Supports `utf-8` and `gbk`.
delimiter	String	Boolean	Specify the field delimiter in the file. Supports `\t`, `,`, and `;`.
fileHeader	Required	List<String>	Specify the table header of the file. The fields of the header are separated by `,`.
fileRename	Optional	List<JSON Object>	When the partition download function is enabled (`split` parameter value is `true`), you can rename the file for each partition. The system will download the file of each partition according to the specified names. The structure is `{"key": "value"}`, in which the key is the partition number (only supports integers), and the value is the user-defined partition file name. For example, `"fileRename": {"1": "group1","2": "group2"}` means that the data of partition 1 is downloaded and named `group1`, and the data of partition 2 is downloaded and named `group2`.

Response Parameters¶

Name	Data Type	Description
taskId	String	ID of the created file download task.

CallBackURL Response Parameters¶

After the Hive data download task is completed, the system sends an HTTP POST request to the URL address, and the request body contains the following return fields:

Name	Data Type	Description
id	String	The download task ID.
returnCode	String	The status code of the download task. `0` means download successful, in which case the `download_url` field will return the download path of the file. Other values mean download failed, in which case the `log_url` field will return the download path of the error log.
download_url	String	When the download is successful (`returnCode` value is `0`), the download path of the file is returned.
log_url	String	When the download fails (`returnCode` value is not `0`), the download path of the error log is returned.
dataSize	String	The size of the downloaded data file, in bytes.

Samples¶

Request Sample¶

url: https://{apigw-address}/data-federation/v2.0/channels/read/yourchannelId/download-request?orgId=yourOrgId
method: POST
requestBody:
{
  "taskName": "Test_download_openapi",
  "sourceName": "hive_enos"
  "querySql": "select * from students",
  "filePackageName": "studentsOpenAPI",
  "callbackURL":"http://localhost:8080",
  "files": {
    "split": true,
    "encoding": "utf-8",
    "delimiter": ",",
    "fileHeader": [
      "c1",
      "c2",
      "c3",
      "c4",
      "c5",
      "c6"
    ],
    "fileRename": {
      "1": "group1",
      "2": "group2",
      "3": "group3",
      "4": "group4"
    }
  }
}

Return Sample¶

{
  "msg": "OK",
  "code": 0,
  "data": {
    "taskId": "yourtaskId"
  }
}