CreateRealtimeLogDeliveryTask
1. API Description
Domain name for API request: teo.intl.tencentcloudapi.com.
This API is used to create a real-time log delivery task.
Restrictions
An entity (a Layer 7 domain name, a Layer 4 proxy instance, or an Edge Function instance) under the same combination of LogType and Area can only have one task created for each TaskType. The mutual exclusion rules for different LogType values are as follows:
| LogType | Conflicting TaskType |
|---|---|
| Layer 4 proxy logs, Edge Function execution logs | Choose one of custom_endpoint, s3, and aws_s3 |
When TaskType is log_analysis:
- Only
LogType=l7-access-logsorweb-attackis supported. - Under the same combination of
ZoneIdandArea, only one task can be created for eachLogType.
Recommendation: Before creating a task, call the DescribeRealtimeLogDeliveryTasks API to query existing tasks and avoid duplicate additions.
A maximum of 20 requests can be initiated per second for this API.
2. Input Parameters
The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| Action | Yes | String | Common Params. The value used for this API: CreateRealtimeLogDeliveryTask. |
| Version | Yes | String | Common Params. The value used for this API: 2022-09-01. |
| Region | No | String | Common Params. This parameter is not required. |
| ZoneId | Yes | String | Site ID. |
| Area | Yes | String | Data delivery area. Valid values:
|
| LogType | Yes | String | Data delivery type. Valid values:
The following log types have been merged into
|
| TaskName | Yes | String | Name of a real-time log delivery task, which can contain up to 200 characters, including digits, English letters, hyphens (-) and underscores (_). |
| TaskType | Yes | String | Type of the real-time log delivery task. Valid values:
|
| EntityList.N | Yes | Array of String | List of entities that the real-time log delivery task applies to. Examples:
|
| Fields.N | Yes | Array of String | List of preset fields to deliver. For valid values, see: For valid values, see alsoDescribeLogFields. |
| CustomFields.N | No | Array of CustomField | List of custom fields to deliver. You can extract specified content from HTTP request headers, response headers, cookies, and request bodies. Custom field names must be unique. Custom fields can be added only for Layer 7 access logs ( The number of custom fields you can configure is subject to a quota. If the quota is insufficient, contact us. |
| CustomExpressionFields.N | No | Array of CustomExpressionField | List of custom expression fields to deliver. By defining the field name and value expression for log delivery, you can deliver personalized real-time log content. For details, see Custom Log Field Expressions. Custom fields can be added only for Layer 7 access logs ( The number of custom fields you can configure is subject to a quota. If the quota is insufficient, contact us. Note: If a field in |
| DeliveryConditions.N | No | Array of DeliveryCondition | Filter conditions for log delivery. If left empty, all logs are delivered. |
| Sample | No | Integer | Sampling ratio, in per mille. Value range: 1-1000. For example, 605 means a sampling ratio of 60.5%. If left empty, the sampling ratio is 100%. |
| LogFormat | No | LogFormat | Output format for log delivery. For usage details, see Custom Log Output Format. If left blank, the default format applies. The default format logic is as follows:
Particularly, when |
| CLS | No | CLSTopic | CLS configuration. This parameter is required when |
| CustomEndpoint | No | CustomEndpoint | Configuration of the custom HTTP service. This parameter is required when |
| S3 | No | S3 | Configuration of the S3-compatible (SigV4 authentication algorithm compatible) object storage. This parameter is required when |
| AWSS3 | No | AWSS3 | Configuration of the AWS S3 object storage. It uses IAM role authorization, requires no long-term key, and applies only to AWS native S3. This parameter is required when |
3. Output Parameters
| Parameter Name | Type | Description |
|---|---|---|
| TaskId | String | ID of the successfully created task. |
| RequestId | String | The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem. |
4. Example
Example1 Create a log delivery task with the push destination as EdgeOne log analytics
Create a log delivery task with the destination as EdgeOne log analytics. The data scope is the L7 access logs generated by domain.example.com within the Chinese mainland. The fields included are RequestID, ClientIP, and RequestTime, with a sampling ratio of 60.5%.
Input Example
POST / HTTP/1.1
Host: teo.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateRealtimeLogDeliveryTask
<Common request parameters>
{
"ZoneId": "zone-2z55fgysdtmc",
"TaskName": "test_log_task",
"TaskType": "log_analysis",
"EntityList": [
"domain.example.com"
],
"LogType": "l7-access-logs",
"Area": "mainland",
"Fields": [
"RequestID",
"ClientIP",
"RequestTime"
],
"Sample": 605
}Output Example
{
"Response": {
"TaskId": "26580056-1187-43ed-b2c7-ecdb5bae0b46",
"RequestId": "5e0a2b4e-df6d-4d2a-ac39-1706cbf8a703"
}
}Example2 Creating a Log Delivery Task with AWS S3 as the Destination Using IAM Role-based Authorization Configuration
This example shows you how to create a log delivery task with the destination configured as AWS S3 object storage, delivering L7 access logs generated for domain.example.com within the Chinese mainland.
Input Example
POST / HTTP/1.1
Host: teo.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateRealtimeLogDeliveryTask
<Common request parameters>
{
"ZoneId": "zone-3qcox8or8ccl",
"Area": "mainland",
"LogType": "l7-access-logs",
"TaskName": "awss3_test_log_task",
"TaskType": "aws_s3",
"EntityList": [
"domain.example.com"
],
"Fields": [
"RequestID"
],
"CustomFields": [],
"CustomExpressionFields": [],
"DeliveryConditions": [],
"Sample": 0,
"LogFormat": {
"FormatType": "json",
"BatchPrefix": "",
"BatchSuffix": "",
"RecordPrefix": "{",
"RecordSuffix": "}",
"RecordDelimiter": "\n",
"RecordTemplate": "",
"FieldDelimiter": ","
},
"AWSS3": {
"Endpoint": "s3.ap-south-1.amazonaws.com",
"BucketName": "example-bucket",
"Path": "edgeone/realtime-log/l7-access-logs",
"RoleARN": "arn:aws:iam::123456789101:role/EdgeOneRealtimeLogRole",
"CompressType": "gzip"
}
}Output Example
{
"Response": {
"TaskId": "e5556fff-63ce-4dec-9d89-0520d1352433",
"RequestId": "5ae35a33-fb0f-499d-8ec1-2c5b8719d308"
}
}Example3 Create a log delivery task with the destination set to S3-compatible object storage (compatible with SigV4 authentication algorithm), delivering Layer 7 Access Logs generated by domain.example.com within the Chinese mainland.
This example shows you how to create a log delivery task with the destination configured as S3-compatible object storage compatible with the SigV4 authentication algorithm. The task delivers Layer 7 Access Logs generated within the Chinese mainland for domain.example.com, where the final security handling method is interception or challenge. The fields included are RequestID, ClientIP, and RequestTime. Log sampling is disabled, log delivery compression is enabled, and a custom request header Vendor is carried during log delivery with a constant value of EdgeOne. The bucket selected is Tencent Cloud's COS.
Input Example
POST / HTTP/1.1
Host: teo.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateRealtimeLogDeliveryTask
<Common request parameters>
{
"ZoneId": "zone-2z55fgysdtmc",
"TaskName": "test_log_task",
"TaskType": "s3",
"EntityList": [
"domain.example.com"
],
"LogType": "l7-access-logs",
"Area": "mainland",
"Fields": [
"RequestID",
"ClientIP",
"RequestTime"
],
"CustomFields": [
{
"Name": "ReqHeader",
"Value": "Accept-Language",
"Enabled": true
}
],
"Sample": 605,
"S3": {
"Endpoint": "https://example.cos.ap-guangzhou.myqcloud.com",
"Region": "ap-guangzhou",
"Bucket": "example-bucket-4-1310765013/example-4-1310765013/logs/EdgeOne/test",
"CompressType": "",
"AccessId": "Your bucket access key ID",
"AccessKey": "Your bucket access key KEY"
}
}Output Example
{
"Response": {
"TaskId": "26580056-1187-43ed-b2c7-ecdb5bae0b46",
"RequestId": "5e0a2b4e-df6d-4d2a-ac39-1706cbf8a703"
}
}Example4 Create a log delivery task with the destination set to Tencent Cloud CLS
Create a log delivery task with the destination set to Tencent Cloud CLS. The data scope includes Layer 7 Access Logs generated by domain.example.com within the Chinese mainland. The fields included are RequestID, ClientIP, RequestTime, the field value extracted from the Accept-Language request header, and the field named content_type using a custom expression. Set the sampling ratio to 60.5%.
Input Example
POST / HTTP/1.1
Host: teo.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateRealtimeLogDeliveryTask
<Common request parameters>
{
"ZoneId": "zone-2z55fgysdtmc",
"TaskName": "test_log_task",
"TaskType": "cls",
"EntityList": [
"domain.example.com"
],
"LogType": "l7-access-logs",
"Area": "mainland",
"Fields": [
"RequestID",
"ClientIP",
"RequestTime"
],
"CustomFields": [
{
"Name": "ReqHeader",
"Value": "Accept-Language",
"Enabled": true
}
],
"CustomExpressionFields": [
{
"Name": "content_type",
"Expression": "${http.request.headers[\"Content-Type\"]}"
}
],
"Sample": 605,
"CLS": {
"LogSetId": "1a6efff1-0e40-4d37-a4ed-02c92513406b",
"TopicId": "0b3a07c0-5cf6-4017-8a75-cd4459aea588",
"LogSetRegion": "ap-guangzhou"
}
}Output Example
{
"Response": {
"TaskId": "26580056-1187-43ed-b2c7-ecdb5bae0b46",
"RequestId": "5e0a2b4e-df6d-4d2a-ac39-1706cbf8a703"
}
}Example5 Creating a Log Delivery Task with the Destination Set to a Custom HTTP Service
This example shows you how to create a log delivery task with the destination set to a custom HTTP service. The delivery data range covers Layer 7 Access Logs generated for domain.example.com within the Chinese mainland, where the final security handling method is interception or challenge. The fields included are RequestID, ClientIP, and RequestTime. Log sampling is disabled, log delivery compression is enabled, and a custom request header Vendor is carried during log delivery, with a constant value of EdgeOne.
Input Example
POST / HTTP/1.1
Host: teo.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateRealtimeLogDeliveryTask
<Common request parameters>
{
"ZoneId": "zone-2z55fgysdtmc",
"TaskName": "test_log_task",
"TaskType": "custom_endpoint",
"EntityList": [
"domain.example.com"
],
"LogType": "l7-access-logs",
"Area": "mainland",
"Fields": [
"RequestID",
"ClientIP",
"RequestTime"
],
"Sample": 1000,
"DeliveryConditions": [
{
"Conditions": [
{
"Key": "SecurityAction",
"Operator": "equal",
"Value": [
"Deny",
"JSChallenge",
"ManagedChallenge"
]
}
]
}
],
"CustomEndpoint": {
"Url": "http://custom_endpoint/access_log/post",
"CompressType": "gzip",
"Headers": [
{
"Name": "Vendor",
"Value": "EdgeOne"
}
]
}
}Output Example
{
"Response": {
"TaskId": "26580056-1187-43ed-b2c7-ecdb5bae0b46",
"RequestId": "5e0a2b4e-df6d-4d2a-ac39-1706cbf8a703"
}
}5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.
- Tencent Cloud SDK 3.0 for Python
- Tencent Cloud SDK 3.0 for Java
- Tencent Cloud SDK 3.0 for PHP
- Tencent Cloud SDK 3.0 for Go
- Tencent Cloud SDK 3.0 for Node.js
- Tencent Cloud SDK 3.0 for .NET
- Tencent Cloud SDK 3.0 for C++
Command Line Interface
6. Error Code
The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.
| Error Code | Description |
|---|---|
| FailedOperation | Operation failed. |
| FailedOperation.CreateClsLogSetFailed | Failed to create the log set. Check if the log set name already exists. |
| FailedOperation.CreateClsLogTopicTaskFailed | Failed to create the log topic task. Check whether the log topic name or task name already exists. |
| FailedOperation.CreateLogTopicTaskAuthFailure | Authentication failed while creating a custom push task. Check whether the push address is correct. |
| FailedOperation.RealtimeLogAuthFailure | Real-time log authentication fail |
| FailedOperation.RealtimeLogNotFound | The real-time log push task does not exist. |
| InvalidParameter | Parameter error. |
| InvalidParameter.InvalidLogFormatFieldDelimiter | The field separator in the log output format is incorrect. |
| InvalidParameter.InvalidLogFormatFormatType | The log output format type is incorrect. |
| InvalidParameter.InvalidLogFormatRecordDelimiter | The log record separator in the log output format is incorrect. |
| InvalidParameter.RealtimeLogEntityAlreadyCreated | Instance push has been created. |
| InvalidParameter.RealtimeLogInvalidDeliveryArea | Log push region is invalid |
| InvalidParameter.RealtimeLogInvalidLogType | Invalid log push type |
| InvalidParameter.RealtimeLogInvalidTaskType | Real-time log delivery type is invalid |
| InvalidParameter.RealtimeLogNumsExceedLimit | Real-time log push task data exceeds the limit. |
| InvalidParameterValue | Parameter value error. |
| LimitExceeded | The quota limit is exceeded. |
| LimitExceeded.CustomLogFieldRegexLimitExceeded | The number of regular expression type fields in real-time log custom fields exceeds the limit. |
| OperationDenied | Operation denied. |
| ResourceNotFound | The resource does not exist. |
| ResourceUnavailable | Resources are unavailable. |
| UnauthorizedOperation.NoPermission | The subaccount has insufficient permissions. Grant the required permissions and proceed with the operation. |
- 1. API Description
- 2. Input Parameters
- 3. Output Parameters
- 4. Example
- Example1 Create a log delivery task with the push destination as EdgeOne log analytics
- Example2 Creating a Log Delivery Task with AWS S3 as the Destination Using IAM Role-based Authorization Configuration
- Example3 Create a log delivery task with the destination set to S3-compatible object storage (compatible with SigV4 authentication algorithm), delivering Layer 7 Access Logs generated by domain.example.com within the Chinese mainland.
- Example4 Create a log delivery task with the destination set to Tencent Cloud CLS
- Example5 Creating a Log Delivery Task with the Destination Set to a Custom HTTP Service
- 5. Developer Resources
- 6. Error Code