Retrieve & Filter DNS Records via ListRecords API - Edge Security Acceleration - Alibaba Cloud - Edge Security Acceleration

Queries the list of DNS records under a site, including record values, priorities, authentication configurations, etc. Supports filtering by conditions such as record name and record type.

Operation description

DNS records corresponding to edge containers, edge functions, and Layer 4 acceleration will not be returned by this API.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

esa:ListRecords

get

*Site

acs:esa:{#regionId}:{#accountId}:site/{#SiteId}

None

Request parameters

Parameter	Type	Required	Description	Example
SiteId	integer	Yes	Site ID, which can be obtained by calling the ListSites API.	1234567890123
RecordName	string	No	Record name. Used as a filter condition for queries.	www.example.com
RecordMatchType	string	No	The search matching mode for record names. Defaults to exact match. Valid values: prefix: Prefix match. suffix: Suffix match. exact: Exact match. fuzzy: Fuzzy match.	fuzzy
PageNumber	integer	No	The page number for paginated queries. The value must be greater than or equal to 1. Default value: 1.	1
PageSize	integer	No	The number of entries per page for paginated queries. Valid values: 1 to 500. Default value: 500.	10
SourceType	string	No	The origin type of the record. Used as a filter condition for queries (only CNAME records can be filtered by this field). Valid values: OSS: OSS origin. S3: S3 origin. LB: Load balancer origin. OP: Origin pool. Domain: Standard domain origin.	OSS
BizName	string	No	The business scenario for record acceleration. Used as a filter condition for queries. Valid values: image_video: Image and video. api: API. web: Web page.	web
Proxied	boolean	No	Specifies whether proxy acceleration is enabled for the record. Used as a filter condition for queries. Valid values: true: Proxy enabled. false: Proxy acceleration disabled.	true
Type	string	No	The DNS record type of the record. Used as a filter condition for queries.	CNAME

Response elements

Element	Type	Description	Example
	object
RequestId	string	The request ID.	15C66C7B-671A-4297-9187-2C4477247A74
PageNumber	integer	The current page number, same as the PageNumber request parameter.	1
PageSize	integer	The number of records displayed per page.	10
TotalCount	integer	The total number of records.	20
Records	array<object>	DNS information of the records. For details, refer to Documentation.
	array<object>	Information about a single record.
BizName	string	The business scenario for record acceleration. Valid values: image_video: Image and video. api: API. web: Web page.	web
Data	object	The specific DNS information of the record. Different record types contain different information.	{"value":"1.1.1.1"}
Value	string	The value of the record. This parameter applies to A/AAAA, CNAME, NS, MX, TXT, CAA, SRV, and URI records. The meaning of this parameter varies based on the record type: A/AAAA: The target IP address. Use an IPv4 address for an A record and an IPv6 address for an AAAA record. CNAME: The target domain name. NS: The name server for the specified domain. MX: The domain name of the target mail server. TXT: A text string. CAA: The domain name of the certificate authority. SRV: The domain name of the target host. URI: A URI string.	CNAME
Priority	integer	The priority of the record, which must be an integer from 0 to 65535. A lower value indicates a higher priority. This parameter applies only to MX, SRV, and URI records.	0
Flag	integer	The record's flag. For a CAA record, the flag determines how a certificate authority (CA) processes the record. The value ranges from 0 to 255. This parameter applies only to CAA records.	128
Tags	object		{\"Name\":\"PARAMETER\"}
Weight	integer	The weight of the record, which must be an integer from 0 to 65535. This parameter applies only to SRV and URI records.	0
Port	integer	The port number, which must be an integer from 0 to 65535. This parameter applies only to SRV records.	80
Type	integer	The certificate type for a CERT record, or the public key type for an SSHFP record.	0
KeyTag	integer	The public key identifier. The value ranges from 0 to 65535. This parameter is valid only for CERT records.	0
Algorithm	integer	The encryption algorithm for the record. The value ranges from 0 to 255. This parameter is valid only for CERT and SSHFP records.	0
Certificate	string	The public key certificate. This parameter is valid only for CERT, SMIMEA, and TLSA records.	dGVzdGFkYWxrcw==
Usage	integer	The usage identifier. The value ranges from 0 to 255. This parameter is valid only for SMIMEA and TLSA records.	0
Selector	integer	The type of certificate or public key for the record. The value ranges from 0 to 255. This parameter is valid only for SMIMEA and TLSA records.	0
MatchingType	integer	The algorithm policy for matching or validating certificates. The value ranges from 0 to 255. This parameter is valid only for SMIMEA and TLSA records.	0
Fingerprint	string	The public key fingerprint. This parameter is valid only for SSHFP records.	abcdef1234567890
Tag	string	The record's tag. For a CAA record, the tag indicates its specific type and purpose. This parameter is valid only for CAA records.	issue
CreateTime	string	The creation time of the record. The date format follows the ISO 8601 standard and uses UTC time in the format of yyyy-MM-ddTHH:mm:ssZ.	2023-12-24T02:01:11Z
UpdateTime	string	The update time of the record. The date format follows the ISO 8601 standard and uses UTC time in the format of yyyy-MM-ddTHH:mm:ssZ.	2023-06-07T10:02:59Z
Proxied	boolean	Indicates whether proxy acceleration is enabled for the record. Valid values: true: Proxy enabled. false: Proxy acceleration disabled.	true
RecordId	integer	The record ID.	1234567890123
RecordSourceType	string	The origin type of the CNAME record. This parameter is required when adding a CNAME record. Valid values: OSS: OSS origin. S3: S3 origin. LB: Load balancer origin. OP: Origin pool. Domain: Standard domain origin. If this parameter is not specified or left empty, the default value is Domain, which indicates a standard domain origin type.	OSS
RecordName	string	The record name.	a.example.com
RecordType	string	The DNS type of the record, such as A/AAAA, CNAME, TXT, etc.	A/AAAA
SiteId	integer	The ID of the site to which the record belongs.	1234567890123
SiteName	string	The name of the site to which the record belongs.	example.com
Ttl	integer	The TTL (Time to Live) of the record, in seconds. When the value is 1, it indicates that the TTL is set to automatic.	30
RecordCname	string	The CNAME of the record. This is the CNAME value that needs to be configured for the record when the site access method is CNAME access.	a.example.com.cnamezone.com
Comment	string	The comment of the record.	this is a remark.
AuthConf	object	The origin authentication information of the CNAME record.
AuthType	string	The origin authentication type. The available authentication types depend on the origin type, which is specified by the `RecordSourceType` parameter. This parameter is required if the origin type is OSS or S3. Valid values: public: Public read. Use this value if the origin type is OSS or S3 and the origin server allows public read access. private: Private read. Use this value if the origin type is S3 and the origin server requires private read access. private_same_account: Private read within the same account. Use this value if the origin type is OSS, the origin server is in the same Alibaba Cloud account, and requires private read access. private_cross_account: Private read across different accounts. Use this value if the origin type is OSS, the origin server is in a different Alibaba Cloud account, and requires private read access.	private
AccessKey	string	The AccessKey for the account that owns the origin server. This parameter is required if the origin type is OSS and the authentication type is `private_cross_account`, or if the origin type is S3 and the authentication type is `private`.	u0Nkg5gBK***QF5wvKMM504JUHt
SecretKey	string	The SecretKey for the account that owns the origin server. This parameter is required if the origin type is OSS and the authentication type is `private_cross_account`, or if the origin type is S3 and the authentication type is `private`.	VIxuvJSA2S03f***kp208dy5w7
Version	string	The signature algorithm version. This parameter is required if the origin type is S3 and the authentication type is `private`. Valid values: v2 v4 The default is `v4`.	v4
Region	string	The region where the origin server is located. This parameter is required if the origin type is S3. For valid region names, refer to the official S3 documentation.	us-east-1
HostPolicy	string	The origin host policy. This takes effect when the record type is CNAME. It sets the policy for the host header used during origin requests. Two modes are available: follow_hostname: Follow the request host. follow_origin_domain: Follow the origin domain.	follow_origin_domain

Examples

Success response

JSON format

{
  "RequestId": "15C66C7B-671A-4297-9187-2C4477247A74",
  "PageNumber": 1,
  "PageSize": 10,
  "TotalCount": 20,
  "Records": [
    {
      "BizName": "web",
      "Data": {
        "Value": "CNAME",
        "Priority": 0,
        "Flag": 128,
        "Tags": {
          "test": "test",
          "test2": 1
        },
        "Weight": 0,
        "Port": 80,
        "Type": 0,
        "KeyTag": 0,
        "Algorithm": 0,
        "Certificate": "dGVzdGFkYWxrcw==",
        "Usage": 0,
        "Selector": 0,
        "MatchingType": 0,
        "Fingerprint": "abcdef1234567890",
        "Tag": "issue"
      },
      "CreateTime": "2023-12-24T02:01:11Z",
      "UpdateTime": "2023-06-07T10:02:59Z",
      "Proxied": true,
      "RecordId": 1234567890123,
      "RecordSourceType": "OSS",
      "RecordName": "a.example.com",
      "RecordType": "A/AAAA",
      "SiteId": 1234567890123,
      "SiteName": "example.com",
      "Ttl": 30,
      "RecordCname": "a.example.com.cnamezone.com",
      "Comment": "this is a remark.",
      "AuthConf": {
        "AuthType": "private",
        "AccessKey": "u0Nkg5gBK***QF5wvKMM504JUHt",
        "SecretKey": "VIxuvJSA2S03f***kp208dy5w7",
        "Version": "v4",
        "Region": "us-east-1"
      },
      "HostPolicy": "follow_origin_domain"
    }
  ]
}

Error codes

HTTP status code	Error code	Error message	Description
400	InternalException	Failed to call the service. Try again later or contact technical support.	Failed to call the service. Try again later or contact technical support.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.