# Creating a Log Transfer Task

#### Function

This API is used to transfer logs of one or more specified log streams to Object Storage Service (OBS).

#### URI

POST /v2/{project_id}/log-dump/obs

Table 1 URI parameter
Parameter | Mandatory | Type | Description
--- | --- | --- | ---
project_id | Yes | String | Project ID. For details about how to obtain the ID, see Obtaining the AccountID, Project ID, Log Group ID, and Log Stream ID. Default value: None Value length: 32 characters

#### Request Parameters

Table 2 Request header parameters
Parameter | Mandatory | Type | Description
--- | --- | --- | ---
X-Auth-Token | Yes | String | User token obtained from IAM. Default value: None Minimum length: 1000 characters Maximum length: 2000 characters
Content-Type | Yes | String | Set this parameter to application/json;charset=UTF-8. Default value: None Minimum length: 30 characters Maximum length: 30 characters

Table 3 Request body parameters
Parameter | Mandatory | Type | Description
--- | --- | --- | ---
log_group_id | Yes | String | Log group ID. Value length: 36 characters

log_stream_ids

Yes

Array of strings

Indicates IDs of log streams whose logs are to be periodically transferred to OBS. You can specify one or more log streams.

Example value:

- 7bb6b1e7-xxxx-4255-87f9-b3dc7fb2xxxx

obs_bucket_name | Yes | String | Indicates the name of an OBS bucket. Minimum length: 3 characters Maximum length: 63 characters
type | Yes | String | Set this parameter to cycle, which indicates that the log transfer is periodic. Value length: 5 characters
storage_format | Yes | String | Indicates whether the logs are stored in raw or JSON format. The default value is RAW. Minimum length: 3 characters Maximum length: 4 characters
switch_on | No | Boolean | Indicates whether the log transfer is enabled. The value is true (default) or false.
prefix_name | No | String | Indicates the file name prefix of the log files transferred to an OBS bucket. Minimum length: 0 characters Maximum length: 64 characters
dir_prefix_name | No | String | Indicates a custom path to store the log files. Minimum length: 0 characters Maximum length: 64 characters
period | Yes | Integer | Indicates the length of the log transfer interval. Example values: 1, 2, 3, 5, 6, 12, and 30
period_unit | Yes | String | Indicates the unit of the log transfer interval. Example values: min and hour Minimum length: 3 characters Maximum length: 4 characters NOTE: The log transfer interval is specified by the combination of the values of period and period_unit, and must be set to one of the following: 2 min, 5 min, 30 min, 1 hour, 3 hours, 6 hours, and 12 hours.

#### Response Parameters

Status code: 201

Table 4 Response body parameter
Parameter | Type | Description
--- | --- | ---
log_dump_obs_id | String | Transfer task ID. Default value: None Value length: 36 characters

Status code: 400

Table 5 Response body parameters
Parameter | Type | Description
--- | --- | ---

error_code

String

Error code.

Example value:

- LTS.0007

error_msg

String

Error message.

Example value:

- The request body format must be json

Status code: 403

Table 6 Response body parameters
Parameter | Type | Description
--- | --- | ---

error_code

String

Error code.

Example value:

- LTS.0403

error_msg

String

Error message.

Example value:

- Invalid projectId

Status code: 500

Table 7 Response body parameters
Parameter | Type | Description
--- | --- | ---

error_code

String

Error code.

Example value:

- LTS.0403

error_msg

String

Error message.

Example value:

- Invalid projectId

#### Example Request

    POST https://{endpoint}/v2/{project_id}/log-dump/obs

    /v2/{project_id}/log-dump/obs
    {
      "log_group_id": "d9dba9f3-xxxx-48bd-xxxx-xxxxa24a8053",
      "log_stream_ids": ["45e7f609-xxxx-4cd3-835b-xxxx4a124718"],
      "obs_bucket_name": "lts-test",
      "type": "cycle",
      "storage_format": "RAW",
      "switch_on": "true",
      "prefix_name": "fileprefixname",
      "dir_prefix_name": "dirprefixname",
      "period": 5,
      "period_unit": "min"
    }

#### Example Response

Status code: 200

- The log group does not exist.

      {
        "error_code": "LTS.0201",
        "error_msg": "The log group does not existed"
      }

- The log stream does not exist.

      {
        "error_code": "LTS.0208",
        "error_msg": "Log stream id does not exist: 632b9bdc-5afd-4666-a5de-2579f8b80314-"
      }

- The OBS bucket does not exist.

      {
        "error_code": "LTS.0416",
        "error_msg": "obs bucket does not exist: zhuanchu"
      }

- The log stream ID has been associated with a transfer task.

      {
        "error_code": "LTS.0207",
        "error_msg": "Log stream id is associated by transfer: 632b9bdc-5afd-4666-a5de-2579f8b80314"
      }

- Invalid transfer type.

      {
        "error_code": "LTS.1901",
        "error_msg": "type is not in the list [cycle]"
      }

- Invalid storage format.

      {
        "error_code": "LTS.1901",
        "error_msg": "storage_format is not in the list [RAW, JSON]"
      }

- Invalid log transfer interval.

      {
        "error_code": "LTS.1901",
        "error_msg": "period+period_unit is not in the list [2min, 5min, 30min, 1hour, 3hour, 6hour, 12hour]"
      }

- Invalid unit of the log transfer interval.

      {
        "error_code": "LTS.1901",
        "error_msg": "period_unit is not in the list [min, hour]"
      }

- Invalid file name prefix.

      {
         "error_code": "LTS.1902",
         "error_msg": "prefix_name is invalid, please verify if it's provided as required"
      }

- Invalid custom path to store log files.

      {
        "error_code": "LTS.1902",
        "error_msg": "dir_prefix_name is invalid, please verify if it's provided as required"
      }

Status code: 201

    {
      "log_dump_obs_id" : "45fdc36b-xxxx-4567-xxxx-559xxxxdf968"
    }

Status code: 400

- The request is invalid. Modify the request based on the description in error_msg before a retry.

      {
        "error_code" : "LTS.0009",
        "error_msg" : "Failed to validate the request body"
      }

- The request is invalid. Modify the request based on the description in error_msg before a retry.

      {
        "error_code": "LTS.0007",
        "error_msg": "The request body format must be json"
      }

Status code: 403

The server understood the request but refused to authorize it. The client should not repeat the request without modifications.

    {
      "error_code" : "LTS.0001",
      "error_msg" : "Invalid projectId"
    }

Status code: 500

- The server has received the request but encountered an internal error.

      {
        "error_code" : "LTS.0202",
        "error_msg" : "Failed to query lts struct log"
      }

- The server has received the request but encountered an internal error.

      {
        "error_code": "LTS.0010",
        "error_msg": "Internal Server Error"
      }

#### Status Codes

Status Code | Description
--- | ---
200 | The request has succeeded.
201 | The request has succeeded. The transfer task has been created.
400 | The request is invalid. Modify the request based on the description in error_msg before a retry.
403 | The server understood the request but refused to authorize it. The client should not repeat the request without modifications.
500 | The server has received the request but encountered an internal error.
503 | The requested service is unavailable.

#### Error Codes

For details, see Error Codes.

Parent topic: Log Transfer