本章我们讨论本专题需要的 Cloudflare API。我们的数据其实会保存在 PostgreSQL 数据库中，这样可以有效的管理，以及避免频繁的调用 CF IP——毕竟，调用远程API是一件费时的工作。基于此，我们只需要了解以下API。 ## Cloudflare API 鉴权开始之前，我们需要了解以下 CF API 的鉴权，所有 API 都需要进行鉴权。CF API 有多种鉴权方式，对于本文来说，我们使用 `Authorization: Bearer ` 的方式。其中 `` 就是上一章创建的 Token。 ## API 返回值 CF API 可以通过 HTTP 状态码和返回的数据进行判断，是否调用成功。我们来看返回的结果： - `errors: [ { code: int, message: string } ]`：错误信息。如果调用成功，该字段为空数组。 - `messages: [ { code: int, message: string } ]`：错误信息。如果调用成功，该字段为空数组。和 `errors` 区别在哪？有待确认。 - `success: bool `：是否成功 - `result: Option`：不同API返回的值不一样。在调用成功后，返回详细的结果。成功的示例： ```json { "errors": [], "messages": [], "success": true, "result": { "comment": "Domain verification record", "name": "example.com", "proxied": true, "settings": {}, "tags": [], "ttl": 3600, "content": "198.51.100.4", "type": "A", "comment_modified_on": "2024-01-01T05:20:00.12345Z", "created_on": "2014-01-01T05:20:00.12345Z", "id": "023e105f4ecef8ad9ca31a8372d0c353", "meta": {}, "modified_on": "2014-01-01T05:20:00.12345Z", "proxiable": true, "tags_modified_on": "2025-01-01T05:20:00.12345Z" } } ``` 发生错误时的示例： ```json { "errors": [ { "code": 7003, "message": "No route for the URI" } ], "messages": [], "success": false, "result": null } ``` ## 创建 DNS 记录 [创建 DNS 记录 API](https://developers.cloudflare.com/api/operations/dns-records-for-a-zone-create-dns-record)，允许我们以编程的方式来添加 DNS 记录，对应到我们的项目就是注册新域名。 ### 记录类型 CF 支持非常多类型的记录，我们常用的有：`A`、`AAAA`、`CNAME` 、`TXT` 和 `NS` 等。 ### CDN 支持某些类型 DNS 记录是支持 CF 的 CDN 的，比如：`A`、`AAAA`、`CNAME` 等。 ### 请求方式和地址 - 请求方式：`POST` - 请求地址：`https://api.cloudflare.com/client/v4 /zones/{zone_id}/dns_records`，其中，`{zone_id}` 是前一章获取到的 Zone ID ### 请求参数 | 参数 | 数据类型 | 是否必填 | 说明 | | --------- | ----------------------------------------------------------- | -------- | --------------------------------------------------------- | | `name` | `string` (1-255（含）字符) | 是 | 记录的名称 | | `content` | `string` | 是 | 记录值 | | `type` | `string` （ `A 、 AAAA 、 CNAME 、 TXT 、 NS ...`值中的其一） | 是 | 记录类型 | | `proxied` | `bool` | 否 | 是否开启 CDN 支持 | | `comment` | `string` | 否 | 注释 | | `ttl` | `int`（`1 或 60-86400`） | 否 | 记录的生存时间(Time To Live)。如果传值是`1`，表示`自动`。 | ### 返回结果以下是结果示例： ```json { "errors": [], "messages": [], "success": true, "result": { "comment": "Domain verification record", "name": "example.com", "proxied": true, "settings": {}, "tags": [], "ttl": 3600, "content": "198.51.100.4", "type": "A", "comment_modified_on": "2024-01-01T05:20:00.12345Z", "created_on": "2014-01-01T05:20:00.12345Z", "id": "023e105f4ecef8ad9ca31a8372d0c353", "meta": {}, "modified_on": "2014-01-01T05:20:00.12345Z", "proxiable": true, "tags_modified_on": "2025-01-01T05:20:00.12345Z" } } ``` 其中很多字段都请求参数相同。这里来看以下字段： - `id`：记录的ID - `created_on`：记录创建时间 - `modified_on`：记录修改时间 ## 删除 DNS 记录 [删除 DNS 记录 API](https://developers.cloudflare.com/api/operations/dns-records-for-a-zone-delete-dns-record)，允许我们以编程的方式删除 DNS 记录。对应项目里的删除域名。 ### 请求方式和地址 - 请求方式：`DELETE` - 请求地址：`https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records/{dns_record_id}` - `{zone_id}`：上一章获取到的 Zone ID - `{dns_record_id}`：DNS 记录的ID。比如，我们在【创建 DNS 记录】时，返回结果里面的 `id` 字段 ### 返回结果 ```json { "result": { "id": "023e105f4ecef8ad9ca31a8372d0c353" } } ``` - `id`：被删除的 DNS 记录的ID。 ## 修改 DNS 记录 [修改 DNS 记录 API](https://developers.cloudflare.com/api/operations/dns-records-for-a-zone-patch-dns-record)，允许我们以编程方式修改 DNS 记录。对应项目里的修改域名。 ### 请求方式和地址 - 请求方式：`PATCH` - 请求地址：`https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records/{dns_record_id}` - `{zone_id}`：上一章获取到的 Zone ID - `{dns_record_id}`：DNS 记录的ID。比如，我们在【创建 DNS 记录】时，返回结果里面 ### 请求参数和【创建 DNS 记录】API 所需的参数一样。 ### 返回结果 ```json { "errors": [], "messages": [], "success": true, "result": { "comment": "Domain verification record", "name": "example.com", "proxied": true, "settings": {}, "tags": [], "ttl": 3600, "content": "198.51.100.4", "type": "A", "comment_modified_on": "2024-01-01T05:20:00.12345Z", "created_on": "2014-01-01T05:20:00.12345Z", "id": "023e105f4ecef8ad9ca31a8372d0c353", "meta": {}, "modified_on": "2014-01-01T05:20:00.12345Z", "proxiable": true, "tags_modified_on": "2025-01-01T05:20:00.12345Z" } } ``` 和【创建 DNS 记录】API 返回结果一样。 ## 列表与详情由于我们会将数据保存在数据库中，所以为了减少 API 请求，我们不使用 CF 的列表和详情 API。你可以自行阅读他们的文档进行了解。 ## 试一试现在，我们来试一试这些 API 的使用。一来是为了实战API调用，二来是为来验证我们获取到的 Token 和 Zone ID 是否正确。你可以使用 Postman 等 GUI 工具，也可以使用 cURL 等终端工具，本文使用 cURL。 ### 添加一条 A 记录 ```bash TOKEN=<你的TOKEN> ZONE_ID=<你的Zone ID> curl -X POST -d '{"name":"axum","content":"85.194.246.69","comment":"AXUM中文网","proxied":true,"type":"A"}' \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer ${TOKEN}" \ "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/dns_records" ``` > 示例中的IP是 Serv00 某区域的IP 结果： ```json {"result":{"id":"fae3*****14e","zone_id":"*****","zone_name":"zliu.tech","name":"axum.zliu.tech","type":"A","content":"85.194.246.69","proxiable":true,"proxied":true,"ttl":1,"settings":{},"meta":{"auto_added":false,"managed_by_apps":false,"managed_by_argo_tunnel":false},"comment":"AXUM中文网","tags":[],"created_on":"2024-11-25T06:07:07.584536Z","modified_on":"2024-11-25T06:07:07.584536Z","comment_modified_on":"2024-11-25T06:07:07.584536Z"},"success":true,"errors":[],"messages":[]} ``` 面板截图： ![添加DNS](https://file.axum.eu.org/subjects/domain-distribution/dns-add.png) ### 修改为 AAAA 记录 ```bash TOKEN=<你的TOKEN> ZONE_ID=<你的Zone ID> DNS_ID=<上一步返回的ID> curl -X PATCH -d '{"name":"axum","content":"2001:4860:4860::8888","comment":"AXUM中文网","proxied":true,"type":"AAAA"}' \ --header 'Content-Type: application/json;charset=utf-8' \ --header "Authorization: Bearer ${TOKEN}" \ "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/dns_records/${DNS_ID}" ``` > 示例中的IP是 Google 的公共 DNS 地址结果： ```json {"result":{"id":"fae3*****14e","zone_id":"*****","zone_name":"zliu.tech","name":"axum.zliu.tech","type":"AAAA","content":"2001:4860:4860::8888","proxiable":true,"proxied":true,"ttl":1,"settings":{},"meta":{"auto_added":false,"managed_by_apps":false,"managed_by_argo_tunnel":false},"comment":"AXUM中文网","tags":[],"created_on":"2024-11-25T06:07:07.584536Z","modified_on":"2024-11-25T06:18:08.500462Z","comment_modified_on":"2024-11-25T06:07:07.584536Z"},"success":true,"errors":[],"messages":[]} ``` 面板截图： ![修改DNS](https://file.axum.eu.org/subjects/domain-distribution/dns-update.png) ### 删除 DNS 记录 ```bash TOKEN=<你的TOKEN> ZONE_ID=<你的Zone ID> DNS_ID=<上一步返回的ID> curl -X DELETE \ --header 'Content-Type: application/json;charset=utf-8' \ --header "Authorization: Bearer ${TOKEN}" \ "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/dns_records/${DNS_ID}" ``` 结果： ```json {"result":{"id":"fae3****14e"},"success":true,"errors":[],"messages":[]} ```

域名分发

准备工作

Cloudflare 常用 API