tencent cloud

APIs

DocumentaçãoAPIsTencent Cloud EdgeOneLog Service APIsCreateRealtimeLogDeliveryTask

CreateRealtimeLogDeliveryTask

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-10-23 15:17:13

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-logs or web-attack is supported.
  • Under the same combination of ZoneId and Area, only one task can be created for each LogType.

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.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

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:

  • mainland: Chinese mainland;
  • overseas: Global (excluding the Chinese mainland).
LogType Yes String

Data delivery type. Valid values:

  • l7-access-logs: Layer 7 access logs;
  • application: Layer 4 proxy logs;
  • function: Edge Function execution logs;
  • web-attack: managed rule logs.

The following log types have been merged into l7-access-logs, and no new tasks can be added for them:

  • domain: site acceleration logs;
  • web-rateLiming: rate limiting and CC attack defense logs;
  • web-rule: custom rule logs;
  • web-bot: Bot management logs.
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:

  • cls: deliver to Tencent Cloud CLS;
  • custom_endpoint: deliver to a custom HTTP(S) endpoint;
  • s3: deliver to an S3-compatible (SigV4 authentication algorithm compatible) object storage endpoint. This task type is not supported when LogType = web-attack;
  • aws_s3: deliver to an AWS S3 bucket. It uses IAM role authorization, requires no long-term key, and applies only to AWS native S3;
  • log_analysis: deliver to EdgeOne Log Analysis. This is supported only when LogType = l7-access-logs or web-attack.
EntityList.N Yes Array of String

List of entities that the real-time log delivery task applies to. Examples:

  • Layer 7 domain name: domain.example.com
  • Layer 4 proxy instance: sid-2s69eb5wcms7
  • Edge Function instance: test-zone-2mxigizoh9l9-1257626257
For valid values, see DescribeL4Proxy.
Fields.N Yes Array of String

List of preset fields to deliver. For valid values, see:

For valid values, see also DescribeLogFields.
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 (LogType = l7-access-logs or domain).

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 (LogType = l7-access-logs or domain).

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 CustomExpressionFields has the same name as a field in Fields or CustomFields, the value in CustomExpressionFields takes precedence.
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:

  • When TaskType is custom_endpoint, the default format is an array of JSON objects, each JSON object represents a log entry;
  • When TaskType is s3 or aws_s3, the default format is JSON Lines;

Particularly, when TaskType is cls or log_analysis, the only allowed value for LogFormat.FormatType is json, and other parameters in LogFormat will be ignored. It is recommended not to transfer LogFormat.
CLS No CLSTopic

CLS configuration. This parameter is required when TaskType is cls.
CustomEndpoint No CustomEndpoint

Configuration of the custom HTTP service. This parameter is required when TaskType is custom_endpoint.
S3 No S3

Configuration of the S3-compatible (SigV4 authentication algorithm compatible) object storage. This parameter is required when TaskType is s3.
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 TaskType is aws_s3.

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.

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.
Anterior: DescribeRealtimeLogDeliveryTasksPróximo: ModifyRealtimeLogDeliveryTask

Ajuda e Suporte

Esta página foi útil?

comentários

Search
    Enter keywords to search documentation