Capability Overview
This skill covers both Domain Information Service (Domain) and Cloud DNS (Alidns) two types of APIs; the SDKs and endpoints are different, so do not mix them up.
Directory Structure
aliyun-domain-skills/
├── SKILL.md
├── reference/ # API 定义(YML),含入参与返回值
│ ├── check_domain.yml
│ ├── query_domainlist.yml
│ ├── describe_domain_records.yml
│ ├── add_domain_record.yml
│ └── update_domain_record.yml
└── scripts/ # 可执行脚本与依赖清单
├── check_domain.py
├── query_domainlist.py
├── describe_domain_records.py
├── add_domain_record.py
├── update_domain_record.py
└── requirements.txt
- reference/: Stores API-related information, including input parameters, return values, etc. (YML), for consulting contracts and field meanings.
- scripts/: Directly runnable Python scripts (for example,
python scripts/query_domainlist.py); you can also read their implementation and write or rewrite new code based on them. - Dependencies:
requirements.txtis located in thescripts/directory; for first-time use, please first runpip install -r aliyun-domain-skills/scripts/requirements.txtto install dependencies.
This skill provides the followingindependent capabilities, which can be called individually or used in combination according to actual needs:
| Capability | API | Product/SDK | Purpose | Use Case |
|---|---|---|---|---|
| Query domain list | QueryDomainList | Domain / domain20180129 | Query the domain list under the account | List account domains, check domain assets, filter domains about to expire |
| Check domain registrability | CheckDomain | Domain / domain20180129 | Check whether a domain can be registered and its price | Pre-registration domain check, batch domain availability assessment |
| List DNS records | DescribeDomainRecords | Alidns / alidns20150109 | Query DNS records by primary domain with pagination | Troubleshoot DNS resolution, obtain RecordId |
| Add DNS record | AddDomainRecord | Alidns / alidns20150109 | Add a DNS record under the primary domain | Newly launched subdomain, add A/CNAME, etc. |
| Modify DNS record | UpdateDomainRecord | Alidns / alidns20150109 | Update RR, type, record value, etc. by RecordId | Switch traffic, change IP, adjust TTL/line |
Important Notes:
- Domain and Alidns are different products and SDKs; there is no mandatory call order between QueryDomainList / CheckDomain and DescribeDomainRecords / AddDomainRecord / UpdateDomainRecord, and they can be combined according to business needs.
- QueryDomainList and CheckDomain are independent of each other; if you need to "first list domains then check prices", you can combine them yourself (for example, first QueryDomainList, then CheckDomain,
fee_command=renew)。 - AddDomainRecord and UpdateDomainRecord are write operations: before adding, it is recommended to use DescribeDomainRecords to confirm whether the same RR+Type+line already exists, to avoid duplication; before updating, you usually need to first obtain the target record's RecordId; before execution, please confirm the scope of impact.
Query Domain List (QueryDomainList)
Call Alibaba Cloud Domain OpenAPI via Python SDK alibabacloud_domain20180129 to query the domain list under the current account.
Prerequisite Check (Must Be Performed First)
Before executing any query, you must first confirm that AK/SK has been configured.
Check Order
1. First check environment variables
echo "AK_ID: ${ALIBABA_CLOUD_ACCESS_KEY_ID:+已设置}"
echo "AK_SECRET: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET:+已设置}"
2. If not set, check the current working directory's .env file
find . -maxdepth 1 -name ".env" -exec cat {} \;
.env file format:
ALIBABA_CLOUD_ACCESS_KEY_ID=your-access-key-id
ALIBABA_CLOUD_ACCESS_KEY_SECRET=your-access-key-secret
3. Load credentials in Python code
from dotenv import load_dotenv
import os
# 先尝试从环境变量读取
access_key_id = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID", "").strip()
access_key_secret = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET", "").strip()
# 如果未设置,尝试从 .env 文件加载
if not access_key_id or not access_key_secret:
load_dotenv() # 从当前工作目录的 .env 文件加载
access_key_id = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID", "").strip()
access_key_secret = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET", "").strip()
if not access_key_id or not access_key_secret:
raise RuntimeError("缺少阿里云凭证。请先设置 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET")
If the credential check is not passed, the query steps should not continue.
Install Dependencies
pip install -r aliyun-domain-skills/scripts/requirements.txt
Or install manually:
pip install alibabacloud_domain20180129 alibabacloud_alidns20150109 alibabacloud_credentials alibabacloud_tea_openapi alibabacloud_tea_util python-dotenv
QueryDomainList Usage
Request Parameters
Required parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| PageNum | integer | Page number | 1 |
| PageSize | integer | Page size | 10 |
Optional parameters (filter conditions)
| Parameter | Type | Description | Example |
|---|---|---|---|
| DomainName | string | Domain name, searchable in the domain list | test.com |
| StartExpirationDate | integer (int64) | Start time of the domain expiration date (milliseconds from 00:00 on January 1, 1970 UTC to the query time) | 1522080000000 |
| EndExpirationDate | integer (int64) | End time of the domain expiration date (millisecond timestamp) | 1522080000000 |
| StartRegistrationDate | integer (int64) | Start time of the domain registration date (millisecond timestamp) | 1522080000000 |
| EndRegistrationDate | integer (int64) | End time of the domain registration date (millisecond timestamp) | 1522080000000 |
| QueryType | string | List query type: 1-Urgent renewal, 2-Urgent redemption | 1 |
| OrderKeyType | string | Sort field: RegistrationDate (registration time) / ExpirationDate (expiration time) | RegistrationDate |
| OrderByType | string | Sort order: ASC (ascending) / DESC (descending), default DESC | ASC |
| ProductDomainType | string | Domain type: New gTLD (new generic top-level domain) / gTLD (generic top-level domain) / ccTLD (country code top-level domain) | New gTLD |
| DomainGroupId | string | Domain group number | 123456 |
| ResourceGroupId | string | Resource group ID | rg-aek2indvyxgpfti |
| Tag | array | Tag list (up to 21) | [{Key: "Remark", Value: "Tag1"}] |
| Ccompany | string | Domain owner name | Guangzhou Jinye Renewable Resources Recycling Co., Ltd. |
| Registrar | string | Registrar | - |
| Dns | string | DNS | - |
| UserClientIp | string | User IP, can be set to 127.0.0.1 | 127.0.0.1 |
| Lang | string | Language of the API error message: zh (Chinese) / en (English), default en | en |
Response structure
{
"PrePage": false, # 是否有上一页
"CurrentPageNum": 0, # 当前页码
"RequestId": "B7AB5469-5E38-4AA9-A920-C65B7A9C8E6E", # 请求 ID
"PageSize": 5, # 每页大小
"TotalPageNum": 1, # 总页数
"Data": {
"Domain": [ # 域名列表
{
"DomainAuditStatus": "FAILED", # 实名认证状态:FAILED/SUCCEED/NONAUDIT/AUDITING
"DomainGroupId": "123456", # 域名分组编号
"Remark": "测试备注", # 域名备注
"DomainGroupName": "测试分组", # 域名分组名称
"RegistrationDate": "2017-11-02 04:00:45", # 注册时间
"InstanceId": "ST20151102120031118", # 实例编号
"DomainName": "test.com", # 域名
"ExpirationDateStatus": "1", # 过期状态:1-未过期, 2-已过期
"ExpirationDate": "2017-11-02 04:00:45", # 到期日期
"RegistrantType": "1", # 注册类型:1-个人, 2-企业
"ExpirationDateLong": 1522080000000, # 到期时长(毫秒时间戳)
"ExpirationCurrDateDiff": -30, # 到期日与当前时间的天数差
"Premium": true, # 是否溢价域名
"RegistrationDateLong": 1522080000000, # 注册时长(毫秒时间戳)
"ProductId": "2a", # 产品 ID
"DomainStatus": "3", # 域名状态:1-急需续费, 2-急需赎回, 3-正常
"DomainType": "gTLD", # 域名类型
"ResourceGroupId": "rg-aek2yyciz557g3q", # 资源组 ID
"Tag": {
"Tag": [
{"Key": "费用", "Value": "标签1"}
]
},
"Ccompany": "广州森林广告装饰有限公司", # 域名所有者名称
"ChgholderStatus": "0", # 域名过户状态:0-正常, 1-过户中, 2-过户失败
"Registrar": "...", # 注册商
"DnsList": {
"DnsList": ["ns1.example.com", "ns2.example.com"] # DNS 列表
}
}
]
},
"TotalItemNum": 1, # 域名总数
"NextPage": false # 是否有下一页
}
Core process
- From environment variables or
.envfile readALIBABA_CLOUD_ACCESS_KEY_ID/ALIBABA_CLOUD_ACCESS_KEY_SECRET - Create
Domain20180129Client - Build
QueryDomainListRequest, set required parameters and optional filter conditions - Call
query_domain_list_with_options - Parse the returned domain list JSON
Example code reference:scripts/query_domainlist.py
Complete API parameter and response structure documentation:reference/query_domainlist.yml
Common query scenarios
Scenario 1: Query all domains (basic query)
request = domain_20180129_models.QueryDomainListRequest(
page_num=1,
page_size=20
)
Scenario 2: Search by domain name
request = domain_20180129_models.QueryDomainListRequest(
page_num=1,
page_size=20,
domain_name="test.com"
)
Scenario 3: Query domains that are about to expire
import time
# 计算今天到未来30天的毫秒时间戳
today = int(time.time() * 1000)
thirty_days_later = today + 30 * 24 * 60 * 60 * 1000
request = domain_20180129_models.QueryDomainListRequest(
page_num=1,
page_size=20,
start_expiration_date=today,
end_expiration_date=thirty_days_later,
order_key_type="ExpirationDate",
order_by_type="ASC"
)
Scenario 4: Query domains that urgently need renewal
request = domain_20180129_models.QueryDomainListRequest(
page_num=1,
page_size=20,
query_type="1" # 1-急需续费
)
Scenario 5: Filter by resource group
request = domain_20180129_models.QueryDomainListRequest(
page_num=1,
page_size=20,
resource_group_id="rg-aek2indvyxgpfti"
)
Scenario 6: Filter by tag
request = domain_20180129_models.QueryDomainListRequest(
page_num=1,
page_size=20,
tag=[
{"Key": "环境", "Value": "生产"}
]
)
Error handling suggestions
401/403: AK/SK is invalid, not configured, or RAM permissions are insufficientInvalidAccessKeyId: AccessKeyId is incorrectSignatureDoesNotMatch: AccessKeySecret is incorrect or the signature does not match- If the exception contains the
Recommendfield, troubleshoot first according to the diagnostic link
Usage process
- Check the environment variables or
.envfile to confirm that AK/SK is configured - Install dependencies
- Build request parameters according to the query requirements (required parameters + optional filter conditions)
- Call
query_domain_list_with_options - Retrieve and parse the returned domain list JSON
Notes
- reference/ The YML in is used to check API input parameters and return values;scripts/ The scripts in can be run directly, making it easy to verify the environment and SDK calls.
- If the business scenario differs from the example, you can rewrite or create new code after reading the YML and the script implementation.
- Timestamp parameters (such as
StartExpirationDate) require millisecond-level timestamps - When paginating queries, adjust as needed
PageNumandPageSize
Check Domain Registrability (CheckDomain)
Via the Python SDK alibabacloud_domain20180129 call the Alibaba Cloud Domain OpenAPI to check whether a specified domain is registrable and obtain price information.
Prerequisite Check (Must Be Performed First)
Before executing any query, you must first confirm that AK/SK has been configured.
Check Order
- Check environment variables first
echo "AK_ID: ${ALIBABA_CLOUD_ACCESS_KEY_ID:+已设置}"
echo "AK_SECRET: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET:+已设置}"
- If not set, check the current working directory's
.envfile
find . -maxdepth 1 -name ".env" -exec cat {} \;
.env File format:
ALIBABA_CLOUD_ACCESS_KEY_ID=your-access-key-id
ALIBABA_CLOUD_ACCESS_KEY_SECRET=your-access-key-secret
- Load credentials in Python code
from dotenv import load_dotenv
import os
# 先尝试从环境变量读取
access_key_id = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID", "").strip()
access_key_secret = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET", "").strip()
# 如果未设置,尝试从 .env 文件加载
if not access_key_id or not access_key_secret:
load_dotenv() # 从当前工作目录的 .env 文件加载
access_key_id = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID", "").strip()
access_key_secret = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET", "").strip()
if not access_key_id or not access_key_secret:
raise RuntimeError("缺少阿里云凭证。请先设置 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET")
If the credential check is not passed, the query steps should not continue.
Install dependencies
pip install -r aliyun-domain-skills/scripts/requirements.txt
Or install manually:
pip install alibabacloud_domain20180129 alibabacloud_alidns20150109 alibabacloud_credentials alibabacloud_tea_openapi alibabacloud_tea_util python-dotenv
CheckDomain Usage
Request Parameters
Required Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| DomainName | string | Domain name | test**.xin |
Optional Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| FeeCommand | string | Operation command: create (new purchase) / renew (renewal) / transfer (transfer in) / restore (redemption) | create |
| FeeCurrency | string | Currency type: USD (US dollar) | USD |
| FeePeriod | integer | Purchase period in years (1-10 years) | 1 |
| Lang | string | Language of error messages returned by the API: zh (Chinese) / en (English), default en | en |
Response Structure
{
"RequestId": "BA7A4FD4-EB9A-4A20-BB0C-9AEB15634DC1", # 唯一请求识别码
"Avail": "1", # 域名是否可以注册:1-可注册, 3-预登记, 4-可删除预订, 0-不可注册, -1-异常, -2-暂停注册, -3-黑名单
"Price": 1286, # 溢价词注册价格
"DomainName": "test**.xin", # 查询的域名名称
"Premium": "true", # 是否是溢价词:true/false
"DynamicCheck": true, # 是否动态询价
"Reason": "In use", # 由注册局返回的不可注册原因
"StaticPriceInfo": { # 静态价格信息
"PriceInfo": [
{
"action": "activate", # 操作类型(activate:新购)
"money": 78.0, # 金额,单位元
"period": 12 # 周期,单位月
}
]
}
}
Core Process
- Read
.envfileALIBABA_CLOUD_ACCESS_KEY_ID/ALIBABA_CLOUD_ACCESS_KEY_SECRET - Create
Domain20180129Client - Build
CheckDomainRequest, setting the domain name (required) and optional parameters - Call
check_domain_with_options - Parse the returned domain check result JSON
Example code reference:scripts/check_domain.py
Complete API parameter and response structure documentation:reference/check_domain.yml
Common Use Cases
Scenario 1: Check whether a domain is registrable (basic query)
request = domain_20180129_models.CheckDomainRequest(
domain_name="example.com"
)
Scenario 2: Check domain new purchase price
request = domain_20180129_models.CheckDomainRequest(
domain_name="example.com",
fee_command="create",
fee_currency="USD",
fee_period=1
)
Scenario 3: Check domain renewal price
request = domain_20180129_models.CheckDomainRequest(
domain_name="example.com",
fee_command="renew",
fee_currency="USD",
fee_period=1
)
Scenario 4: Check domain transfer price
request = domain_20180129_models.CheckDomainRequest(
domain_name="example.com",
fee_command="transfer"
)
Scenario 5: Batch check multiple domains
domains_to_check = ["example1.com", "example2.com", "example3.com"]
for domain in domains_to_check:
request = domain_20180129_models.CheckDomainRequest(
domain_name=domain
)
resp = client.check_domain_with_options(request, runtime)
# 处理结果
Error Handling Suggestions
401/403: AK/SK is invalid, not configured, or RAM permissions are insufficientInvalidAccessKeyId: AccessKeyId is incorrectSignatureDoesNotMatch: AccessKeySecret is incorrect or the signature does not match- If the exception contains the
Recommendfield, prioritize troubleshooting according to the diagnostic link
Usage Process
- Check environment variables or the
.envfile to confirm that AK/SK has been configured - Install dependencies
- Build request parameters as needed (required parameters + optional parameters)
- Call
check_domain_with_options - Obtain and parse the returned domain check result JSON
Notes
- There is a rate limit when calling the CheckDomain API. For the same Alibaba Cloud account and its RAM users, the limit for calling this API is 10QPS, and the total API limit is 100QPS
- For domain validity requirements, please refer toDomain Validity
- reference/ The YML in is used to consult API input parameters and return values;scripts/ The script in can be run directly, making it convenient to verify the environment and SDK calls.
- If the business scenario differs from the example, you can rewrite or create new code yourself after reading the YML and script implementation.
List resolution records (DescribeDomainRecords)
Call the alibabacloud_alidns20150109 via the Python SDKAlibaba Cloud DNS OpenAPI to paginate and query the list of resolution records under the specifiedprimary domain(including RecordId, for use in subsequent record modifications).
Product and client
- SDK package:
alibabacloud_alidns20150109 - Client:
Alidns20150109Client - Endpoint:
alidns.aliyuncs.com(different from Domain'sdomain20180129)
Prerequisite checks and dependencies
The AK/SK check order is the same as the "Prerequisite checks" in the "Query domain list (QueryDomainList)" section above.
Install dependencies (requirements.txt already includes both the Domain and Alidns SDKs):
pip install -r aliyun-domain-skills/scripts/requirements.txt
Or when installing manually, include at least:alibabacloud_alidns20150109 and credential- and Tea-related packages (consistent with requirements.txt in the repository).
DescribeDomainRecords usage
Request parameters (summary)
Required
| Parameter | Type | Description |
|---|---|---|
| DomainName | string | Primary domain, e.g. example.com |
Common optional
| Parameter | Type | Description |
|---|---|---|
| PageNumber | integer | Page number, starting from 1, default 1 |
| PageSize | integer | Number of rows per page, maximum 500, default 20 |
| Lang | string | Request/response language,zh / en , etc. |
| KeyWord | string | General keyword |
| RRKeyWord | string | Host record keyword (fuzzy, according to SearchMode) |
| TypeKeyWord | string | Resolution type keyword (exact match) |
| ValueKeyWord | string | Record value keyword (fuzzy, according to SearchMode) |
| SearchMode | string | LIKE / EXACT / ADVANCED / COMBINATION , etc.; for how they work with the above keyword fields, see the official documentation |
| GroupId | integer | Domain group ID;0/-1/-2 etc. have special meanings, see the YML |
| Type / Line / Status | string | Filter by record type, line, status (Enable/Disable) |
For complete parameters and response fields, see reference/describe_domain_records.yml。
Response highlights
- The resolution record list in the response body includes each record's RecordId、RR、Type、Value、TTL and other fields;RecordId is a required parameter for calling
UpdateDomainRecord.
Core process
- Configure AK/SK (environment variables or
.env) - Create
Alidns20150109Client,config.endpoint = 'alidns.aliyuncs.com' - Build
DescribeDomainRecordsRequest, at least setdomain_name - Call
describe_domain_records_with_options - Parse the paginated results, and iterate through
PageNumberas needed until all records are retrieved
Sample code reference:scripts/describe_domain_records.py
Error handling suggestions
401/403: Invalid credentials or the RAM user lacks DNS-related permissionsInvalidAccessKeyId/SignatureDoesNotMatch: Same as above- If the exception contains
Recommend, troubleshoot according to the diagnostic information
Add resolution record (AddDomainRecord)
Call alibabacloud_alidns20150109 through the same SDK AddDomainRecordto addprimary domainunder the specifiedadda resolution record (different from UpdateDomainRecord: no existing RecordId is required, and the API returns a new RecordId).
Prerequisite checks and dependencies
Same as the "List resolution records (DescribeDomainRecords)" section above. Before write operations, please confirm DomainName、RR、Type、Value correct, avoiding conflicts with existing records or mistakenly pointing to production traffic.
AddDomainRecord usage
Request parameters (summary)
Required
| Parameter | Type | Description |
|---|---|---|
| DomainName | string | Primary domain, such as example.com(can be obtained via DescribeDomains, etc.) |
| RR | string | Host record; for resolving the primary domain itself, enter @, do not leave it blank |
| Type | string | Record type, such as A、CNAME、MX , etc. |
| Value | string | Record value |
Common optional
| Parameter | Type | Description |
|---|---|---|
| TTL | integer | Effective time (seconds), default 600, range 1–86400 |
| Priority | integer | MX priority (often required for MX records), see YML for the range |
| Line | string | Resolution line, default default |
| Lang / UserClientIp | string | Language, client IP |
For complete parameters and responses, see reference/add_domain_record.yml。
Response key points
- On success, returns RequestId and the newly created record's RecordId(subsequently can use UpdateDomainRecord to modify by that ID).
Coordination with DescribeDomainRecords
- Optional: call DescribeDomainRecordsfor the primary domain to confirm that no conflicting RR + Type + line combination exists.
- Build AddDomainRecordRequest, set DomainName, RR, Type, Value, and optional TTL/Line, etc.
- Call add_domain_record_with_options, save the returned RecordId for subsequent operations and maintenance or updates.
Core workflow
- Configure AK/SK
- Create
Alidns20150109Client(endpoint:alidns.aliyuncs.com) - Build
AddDomainRecordRequest, set required and optional parameters - Call
add_domain_record_with_options
Example code reference:scripts/add_domain_record.py
Error handling suggestions
- Same as DescribeDomainRecords; when a write operation fails, note whether it is because the record already exists, the domain is not in resolution, permissions are insufficient, or the parameters are invalid.
Modify resolution record (UpdateDomainRecord)
Through the same SDK alibabacloud_alidns20150109 call UpdateDomainRecord, according to RecordId to modify an existing resolution record (host record, type, record value, TTL, line, etc.).
Prerequisite checks and dependencies
Same as the above section "List resolution records (DescribeDomainRecords)"; before write operations, please confirm again the target RecordId and Value, to avoid mistakenly modifying production resolution.
UpdateDomainRecord usage
Request parameters (summary)
Required
| Parameter | Type | Description |
|---|---|---|
| RecordId | string | Resolution record ID, usually returned by DescribeDomainRecords |
| RR | string | Host record; for primary domain resolution, enter @ |
| Type | string | Record type, such as A、CNAME、MX , etc. |
| Value | string | Record value |
Common optional
| Parameter | Type | Description |
|---|---|---|
| TTL | integer | Effective time (seconds), default 600, range 1–86400 |
| Priority | integer | MX priority (often required for MX records), see YML for the range |
| Line | string | Resolution line, default default |
| Lang / UserClientIp | string | Language, client IP |
For complete parameters and responses, see reference/update_domain_record.yml。
Response key points
- On success, returns RequestId and RecordId(consistent with the record requested for modification).
Coordination with DescribeDomainRecords
- Call DescribeDomainRecordson the primary domain, locate in the results the RR + Type(and line) corresponding record, and read RecordId。
- Use the same RecordId call UpdateDomainRecordupdate Value / TTL / Line , etc.
Core Process
- Configure AK/SK
- Create
Alidns20150109Client(endpoint same as above) - Build
UpdateDomainRecordRequest, set RecordId, RR, Type, Value, and optional parameters - Call
update_domain_record_with_options
Example code reference:scripts/update_domain_record.py
Error Handling Suggestions
- Same as DescribeDomainRecords; when a write operation fails, check whether it is because the record does not exist, permissions are insufficient, or it conflicts with the current resolution state.
Capability Extension
This skill already includes Domain(QueryDomainList, CheckDomain) and Alidns(DescribeDomainRecords, AddDomainRecord, UpdateDomainRecord) contracts and example scripts. Other independent APIs (e.g., domain details, registration tasks, more DNS operations, etc.) can still be added subsequently, and it is recommended to continue extending in the format of "reference YML + scripts example + one row in the capability table."
All capabilities follow the principle of "independent invocation, on-demand combination."