English · 简体中文 · 繁體中文 · 日本語 · Русский · Bahasa Indonesia · Deutsch · Français · 한국어 · العربية
[返回專案介紹](../README_ZH_TW.md) 透過 API 註冊網域、管理 DNS、更新動態 IP，並自動化帳號操作。示例統一使用 DNSHE API 地址和佔位憑據；請將示例網域、ID 和金鑰替換為你自己的資源。 ## 目錄 - [快速開始](#快速開始) - [認證與請求約定](#認證與請求約定) - [網域管理](#網域管理) - [DNS 記錄管理](#dns-記錄管理) - [動態 DNS（DDNS）](#動態-dnsddns) - [API 金鑰管理](#api-金鑰管理) - [網域轉贈](#網域轉贈) - [配額查詢](#配額查詢) - [WHOIS 查詢](#whois-查詢) - [錯誤處理與速率限制](#錯誤處理與速率限制) - [用戶端示例](#用戶端示例) - [安全建議與常見問題](#安全建議與常見問題) - [技術支援](#技術支援) ## 快速開始 ```text https://api005.dnshe.com/index.php?m=domain_hub ``` 基礎地址已包含 `m=domain_hub`，追加路由引數時使用 `&`。除 GET 查詢引數外，請求與響應使用 JSON。普通鑑權請求預設每分鐘 60 次，運營方可調整；功能可用性取決於帳號和部署配置。命令示例使用 Bash/sh，請先配置下列環境變數。 ```bash export DNSHE_API_KEY='replace-with-your-api-key' export DNSHE_API_SECRET='replace-with-your-api-secret' export DNSHE_DDNS_TOKEN='replace-with-your-ddns-token' ``` ## 認證與請求約定 首次金鑰請在客戶中心 → [管理網域](https://my.dnshe.com/index.php?m=domain_hub) → API 管理中建立。鑑權請求必須攜帶 `X-API-Key` 和 `X-API-Secret` 請求頭，URL 或請求體傳遞憑據的方式已禁用。GET 引數放在查詢字串中，寫操作使用 JSON 並設定 `Content-Type: application/json`。`endpoint` 選擇資源，`action` 選擇操作；`quota` 和 `whois` 無需 `action`。DDNS 使用單獨的 Token。 ## 網域管理 ### 1.1 列出網域 `GET` · `endpoint=subdomains` · `action=list` #### 引數 - `page` — `integer`; 可選; 預設值 / 範圍: `1`. - `cursor_id` — `integer`; 可選. - `per_page` — `integer`; 可選; 預設值 / 範圍: `200; 1–500`. - `include_total` — `boolean`; 可選; 預設值 / 範圍: `false`. - `search` — `string`; 可選. - `rootdomain` — `string`; 可選. - `status` — `string`; 可選; 預設值 / 範圍: `active | suspended | expired`. - `created_from / created_to` — `string`; 可選; 預設值 / 範圍: `YYYY-MM-DD`. - `sort_by` — `string`; 可選; 預設值 / 範圍: `id`. - `sort_dir` — `string`; 可選; 預設值 / 範圍: `desc; asc | desc`. - `fields` — `string`; 可選; 預設值 / 範圍: `all`. `page` 是從 1 開始的相容頁碼。大資料量推薦首次傳 `cursor_id=0`；當 `pagination.has_more=true` 時，將 `pagination.next_cursor_id` 用作下次遊標，變為 false 時停止。遊標模式固定按 ID 排序，不使用 OFFSET。`per_page` 預設 200、最大 500，建議先用 50–100。`include_total=1` 會額外統計總數，大資料量時可能較慢。`search` 匹配字首或根網域；`rootdomain`、`status`、`created_from`、`created_to` 用於過濾，日期格式為 YYYY-MM-DD。`sort_by` 支援 `id`、`created_at`、`updated_at`、`expires_at`、`subdomain`；`sort_dir` 為 `asc` 或 `desc`。 `fields` 為逗號分隔的欄位列表或 `all`，支援 `id`、`subdomain`、`rootdomain`、`full_domain`、`status`、`created_at`、`updated_at`、`expires_at`、`never_expires`、`cloudflare_zone_id`、`provider_account_id`。自定義選擇仍會補充 `id`。`count` 表示本次返回集合的數量，不應當作所有匹配網域的總數。 #### 請求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=list" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" ``` ```bash curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=list&cursor_id=0&per_page=100&fields=id,subdomain,rootdomain,status" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" ``` ```bash curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=list&search=test&rootdomain=de5.net&status=active&sort_by=expires_at&sort_dir=asc&per_page=50" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" ``` #### 響應示例 ```json { "success": true, "count": 2, "subdomains": [ { "id": 1, "subdomain": "test", "rootdomain": "de5.net", "full_domain": "test.de5.net", "status": "active", "created_at": "2025-10-19 10:00:00", "updated_at": "2025-10-19 10:00:00" }, { "id": 2, "subdomain": "api", "rootdomain": "de5.net", "full_domain": "api.de5.net", "status": "active", "created_at": "2025-10-19 11:00:00", "updated_at": "2025-10-19 11:00:00" } ] } ``` ```json { "success": true, "count": 1, "subdomains": [ { "id": 901, "subdomain": "test", "rootdomain": "de5.net", "full_domain": "test.de5.net", "status": "active" } ], "pagination": { "mode": "cursor", "page": 1, "per_page": 100, "has_more": true, "cursor_id": 0, "next_cursor_id": 901 } } ``` ### 1.2 註冊網域 `POST` · `endpoint=subdomains` · `action=create` #### 引數 - `subdomain` — `string`; 必填. - `domain` — `string`; 必填. `subdomain` 是網域字首，例如 `myapp`；`domain` 是可用根網域，例如 `de5.net`。註冊使用 `action=create` 和請求欄位 `domain`；響應中的 `rootdomain` 及同名列表過濾引數不是註冊欄位。仍需符合可用性和帳號配額要求。 #### 請求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=create" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "subdomain": "myapp", "domain": "de5.net" }' ``` #### 響應示例 ```json { "success": true, "message": "Subdomain registered successfully", "subdomain_id": 3, "full_domain": "myapp.de5.net" } ``` ### 1.3 獲取網域詳情 `GET` · `endpoint=subdomains` · `action=get` #### 引數 - `subdomain_id` — `integer`; 必填. 使用當前鑑權帳號擁有的網域 ID，響應包含網域物件、`dns_records` 與 `dns_count`。 #### 請求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=get&subdomain_id=1" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" ``` #### 響應示例 ```json { "success": true, "subdomain": { "id": 1, "subdomain": "test", "rootdomain": "de5.net", "full_domain": "test.de5.net", "status": "active", "created_at": "2025-10-19 10:00:00", "updated_at": "2025-10-19 10:00:00" }, "dns_records": [ { "id": 1, "name": "test.de5.net", "type": "A", "content": "203.0.113.10", "ttl": 600, "priority": null, "status": "active", "created_at": "2025-10-19 10:05:00" } ], "dns_count": 1 } ``` ### 1.4 刪除網域 `POST / DELETE` · `endpoint=subdomains` · `action=delete` #### 引數 - `subdomain_id` — `integer`; 必填. 刪除帳號名下的目標網域及關聯 DNS 記錄，響應透過 `dns_records_deleted` 報告刪除數量。提交前請確認目標 ID。 #### 請求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=delete" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "subdomain_id": 1 }' ``` #### 響應示例 ```json { "success": true, "message": "Subdomain deleted successfully", "subdomain_id": 1, "full_domain": "test.de5.net", "dns_records_deleted": 4 } ``` ### 1.5 續期網域 `POST / PUT` · `endpoint=subdomains` · `action=renew` #### 引數 - `subdomain_id` — `integer`; 必填. DNSHE 正常免費續期仍然免費，示例為 `charged_amount=0`。通用外掛可配置收費贖回；涉及贖回時，請先確認網域狀態和控制檯規則。根據響應的 `previous_expires_at`、`new_expires_at`、`never_expires`、`remaining_days`、`charged_amount` 判斷實際結果。 續期失敗包括：HTTP 403 `renewal disabled`、`redemption period requires administrator`、`renewal window expired`；HTTP 422 且 `error_code=renewal_not_yet_available`；HTTP 402 `insufficient balance for redemption renewal`；HTTP 404 表示網域不存在或不屬於當前帳號。請檢查續期視窗或聯絡支援，不要無間隔重試。 #### 請求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=renew" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "subdomain_id": 3 }' ``` #### 響應示例 ```json { "success": true, "message": "Subdomain renewed successfully", "subdomain_id": 3, "subdomain": "myapp", "previous_expires_at": "2027-05-01 00:00:00", "new_expires_at": "2028-05-01 00:00:00", "renewed_at": "2027-04-30 00:00:00", "never_expires": 0, "status": "active", "remaining_days": 367, "charged_amount": 0 } ``` ## DNS 記錄管理 ### 2.1 列出 DNS 記錄 `GET` · `endpoint=dns_records` · `action=list` #### 引數 - `subdomain_id` — `integer`; 必填. 優先使用列表或建立介面返回的模組 `id`，新公開記錄使用 15 位外顯 ID。`record_id` 是 DNS 供應商的記錄標識。修改/刪除至少提供其中一個，同時提供時必須指向同一記錄，否則返回 `dns_record_identifier_mismatch`。舊內部 ID 繼續相容。參考文件說明純數字 `record_id` 至少相容至 2027-06-12，新呼叫請將模組 ID 放入 `id`。 #### 請求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=list&subdomain_id=1" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" ``` #### 響應示例 ```json { "success": true, "count": 2, "records": [ { "id": 1, "record_id": "5a0ce6c4d1d4c71bc5e60a2a2a0e4997", "name": "test.de5.net", "type": "A", "content": "203.0.113.10", "ttl": 600, "priority": null, "line": null, "proxied": false, "status": "active", "created_at": "2025-10-19 10:05:00", "updated_at": "2025-10-19 10:05:00" }, { "id": 2, "name": "www.test.de5.net", "type": "CNAME", "content": "test.de5.net", "ttl": 600, "priority": null, "proxied": false, "status": "active", "created_at": "2025-10-19 10:10:00" } ] } ``` ### 2.2 建立 DNS 記錄 `POST` · `endpoint=dns_records` · `action=create` #### 引數 - `subdomain_id` — `integer`; 必填. - `type` — `string`; 必填. - `name` — `string`; 可選; 預設值 / 範圍: `@`. - `content` — `string`; 可選. - `ttl` — `integer`; 可選; 預設值 / 範圍: `600`. - `priority` — `integer`; 可選; 預設值 / 範圍: `MX: 10; SRV: 0`. - `line` — `string`; 可選. - `record_weight / weight` — `integer`; 可選. - `record_port / port` — `integer`; 可選; 預設值 / 範圍: `1–65535`. - `record_target / target` — `string`; 可選. - `caa_flag` — `integer`; 可選; 預設值 / 範圍: `0; 0–255`. - `caa_tag` — `string`; 可選; 預設值 / 範圍: `issue; 1–15 [A-Za-z0-9]`. - `caa_value` — `string`; 可選. `type` 支援 A、AAAA、CNAME、MX、TXT、NS、SRV、CAA。`name` 是相對於已註冊網域的名稱，省略、空值或 `@` 表示網域本身，不接受完整網域；萬用字元 `*` 只能位於最左側標籤。`content` 必填，除非由 SRV/CAA 結構化引數組裝。`ttl` 預設 600 秒；`priority` 在 MX 中預設 10，在 SRV 中預設 0。 SRV 的 `record_weight`/`weight`、`record_port`/`port`、`record_target`/`target` 分別表示權重、埠（1–65535）和目標主機，目標 `.` 表示服務不可用。CAA 使用 `caa_flag`（0–255，預設 0）、`caa_tag`（1–15 位字母數字，預設 `issue`）和 `caa_value`。`line` 僅適用於 AliDNS，其他供應商拒絕非空值。 後臺可透過 `disable_ns_management` 禁用 NS 寫入。網域委派到外部 DNS 後，建立或修改非 NS 記錄會返回 `external_dns_delegated`；刪除舊記錄、校準和過期清理不受此限制。 #### 請求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=create" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "subdomain_id": 1, "type": "A", "content": "203.0.113.10", "ttl": 600 }' ``` #### 響應示例 ```json { "success": true, "message": "DNS record created successfully", "id": 738492016583241, "record_id": "5a0ce6c4d1d4c71bc5e60a2a2a0e4997" } ``` ### 2.3 修改 DNS 記錄 `POST / PUT / PATCH` · `endpoint=dns_records` · `action=modify` #### 引數 - `id` — `integer`; 可選. - `record_id` — `string`; 可選. - `type / name / content` — `string`; 可選. - `ttl / priority` — `integer`; 可選. - `line` — `string`; 可選. - `record_weight / weight` — `integer`; 可選. - `record_port / port` — `integer`; 可選. - `record_target / target` — `string`; 可選. - `caa_flag` — `integer`; 可選. - `caa_tag / caa_value` — `string`; 可選. 提供 `id` 或 `record_id`，以及需要修改的欄位。名稱規則及 SRV/CAA 選項與建立相同。兩個標識同時提供時必須指向同一記錄，響應返回模組 ID 和供應商記錄 ID。 優先使用列表或建立介面返回的模組 `id`，新公開記錄使用 15 位外顯 ID。`record_id` 是 DNS 供應商的記錄標識。修改/刪除至少提供其中一個，同時提供時必須指向同一記錄，否則返回 `dns_record_identifier_mismatch`。舊內部 ID 繼續相容。參考文件說明純數字 `record_id` 至少相容至 2027-06-12，新呼叫請將模組 ID 放入 `id`。 後臺可透過 `disable_ns_management` 禁用 NS 寫入。網域委派到外部 DNS 後，建立或修改非 NS 記錄會返回 `external_dns_delegated`；刪除舊記錄、校準和過期清理不受此限制。 #### 請求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=modify" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "id": 738492016583241, "type": "A", "content": "203.0.113.20", "ttl": 600 }' ``` #### 響應示例 ```json { "success": true, "message": "DNS record updated successfully", "id": 738492016583241, "record_id": "5a0ce6c4d1d4c71bc5e60a2a2a0e4997" } ``` ### 2.4 刪除 DNS 記錄 `POST / DELETE` · `endpoint=dns_records` · `action=delete` #### 引數 - `id` — `integer`; 可選. - `record_id` — `string`; 可選. 優先使用列表或建立介面返回的模組 `id`，新公開記錄使用 15 位外顯 ID。`record_id` 是 DNS 供應商的記錄標識。修改/刪除至少提供其中一個，同時提供時必須指向同一記錄，否則返回 `dns_record_identifier_mismatch`。舊內部 ID 繼續相容。參考文件說明純數字 `record_id` 至少相容至 2027-06-12，新呼叫請將模組 ID 放入 `id`。 #### 請求示例 ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=delete" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "id": 1 }' ``` ```bash curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=delete" \ -H "X-API-Key: ${DNSHE_API_KEY}" \ -H "X-API-Secret: ${DNSHE_API_SECRET}" \ -H "Content-Type: application/json" \ -d '{ "record_id": "5a0ce6c4d1d4c71bc5e60a2a2a0e4997" }' ``` #### 響應示例 ```json { "success": true, "message": "DNS record deleted successfully" } ``` ## 動態 DNS（DDNS） `GET / POST / PUT` · `endpoint=ddns` · `action=update` 在網域管理 → DDNS 中，為指定 A/AAAA 記錄建立專用 Token。透過 `Authorization: Bearer