介绍
# WordPress.com
通过托管的 OAuth 身份验证访问 WordPress.com REST API。在 WordPress.com 托管的网站上创建和管理文章、页面及网站内容。
## 快速开始
```bash # List posts from a site python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/wordpress/rest/v1.1/sites/{site_id}/posts?number=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 基础 URL
``` https://gateway.maton.ai/wordpress/rest/v1.1/{endpoint} ```
网关将请求代理到 `public-api.wordpress.com` 并自动注入您的 OAuth 令牌。
**注意：** WordPress.com 使用 REST v1.1 API。特定站点的端点使用 `/sites/{site_id_or_domain}/{resource}` 模式。
## 身份验证
所有请求都需要在 Authorization 标头中提供 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取 API 密钥
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 WordPress.com OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=wordpress&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'wordpress'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 获取连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "connection": { "connection_id": "fb327990-1a43-4325-9c15-bad771b6a288", "status": "ACTIVE", "creation_time": "2026-02-10T07:46:26.908898Z", "last_updated_time": "2026-02-10T07:49:33.440422Z", "url": "https://connect.maton.ai/?session_token=...", "app": "wordpress", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 指定连接
如果您有多个 WordPress.com 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/wordpress/rest/v1.1/sites/{site_id}/posts') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', 'fb327990-1a43-4325-9c15-bad771b6a288') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最早）的活动连接。
## API 参考
### 站点
#### 获取站点信息
```bash GET /wordpress/rest/v1.1/sites/{site_id_or_domain} ```
**响应：** ```json { "ID": 252505333, "name": "My Blog", "description": "Just another WordPress.com site", "URL": "https://myblog.wordpress.com", "capabilities": { "edit_pages": true, "edit_posts": true, "edit_others_posts": true, "delete_posts": true } } ```
站点标识符可以是： - 数字站点 ID（例如 `252505333`） - 域名（例如 `myblog.wordpress.com` 或 `en.blog.wordpress.com`）
### 文章
#### 列出文章
```bash GET /wordpress/rest/v1.1/sites/{site}/posts ```
**查询参数：** - `number` - 要返回的文章数量（默认：20，最大：100） - `offset` - 分页偏移量 - `page` - 页码 - `page_handle` - 分页游标（来自响应 `meta.next_page`） - `order` - 排序顺序：`DESC` 或 `ASC` - `order_by` - 排序字段：`date`、`modified`、`title`、`comment_count`、`ID` - `status` - 文章状态：`publish`、`draft`、`pending`、`private`、`future`、`trash`、`any` - `type` - 文章类型：`post`、`page`、`any` - `search` - 搜索词 - `category` - 分类别名 - `tag` - 标签别名 - `author` - 作者 ID - `fields` - 要返回的字段逗号分隔列表
**响应：** ```json { "found": 150, "posts": [ { "ID": 83587, "site_ID": 3584907, "author": { "ID": 257479511, "login": "username", "name": "John Doe" }, "date": "2026-02-09T15:00:00+00:00", "modified": "2026-02-09T16:30:00+00:00", "title": "My Post Title", "excerpt": "<p>Post excerpt...</p>", "content": "<p>Full post content...</p>", "slug": "my-post-title", "status": "publish", "type": "post", "categories": {...}, "tags": {...} } ], "meta": { "next_page": "value=2026-02-09T15%3A00%3A00%2B00%3A00&id=83587" } } ```
#### 获取文章
```bash GET /wordpress/rest/v1.1/sites/{site}/posts/{post_id} ```
**响应：** ```json { "ID": 83587, "site_ID": 3584907, "author": {...}, "date": "2026-02-09T15:00:00+00:00", "title": "My Post Title", "content": "<p>Full post content...</p>", "slug": "my-post-title", "status": "publish", "type": "post", "categories": { "news": { "ID": 123, "name": "News", "slug": "news" } }, "tags": { "featured": { "ID": 456, "name": "Featured", "slug": "featured" } } } ```
#### 创建文章
```bash POST /wordpress/rest/v1.1/sites/{site}/posts/new Content-Type: application/json
{ "title": "New Post Title", "content": "<p>Post content here...</p>", "status": "draft", "categories": "news, updates", "tags": "featured, important" } ```
**参数：** - `title` - 文章标题（必需） - `content` - 文章内容（HTML） - `excerpt` - 文章摘要 - `status` - `publish`、`draft`、`pending`、`private`、`future` - `date` - 文章日期（ISO 8601） - `categories` - 逗号分隔的分类名称或别名 - `tags` - 逗号分隔的标签名称或别名 - `format` - 文章格式：`standard`、`aside`、`chat`、`gallery`、`link`、`image`、`quote`、`status`、`video`、`audio` - `slug` - URL 别名 - `featured_image` - 特色图片附件 ID - `sticky` - 文章是否置顶（布尔值） - `password` - 文章保护密码
**响应：** ```json { "ID": 123, "site_ID": 252505333, "title": "New Post Title", "status": "draft", "date": "2026-02-10T09:50:35+00:00" } ```
#### 更新文章
```bash POST /wordpress/rest/v1.1/sites/{site}/posts/{post_id} Content-Type: application/json
{ "title": "Updated Title", "content": "<p>Updated content...</p>" } ```
使用与创建文章相同的参数。
#### 删除文章
```bash POST /wordpress/rest/v1.1/sites/{site}/posts/{post_id}/delete ```
将文章移至回收站。返回状态为 `status: "trash"` 的已删除文章。
### 页面
页面使用与文章相同的端点，但需指定 `type=page`：
#### 列出页面
```bash GET /wordpress/rest/v1.1/sites/{site}/posts?type=page ```
#### 创建页面
```bash POST /wordpress/rest/v1.1/sites/{site}/posts/new?type=page Content-Type: application/json
{ "title": "About Us", "content": "<p>About page content...</p>", "status": "publish" } ```
#### 获取页面下拉列表
```bash GET /wordpress/rest/v1.1/sites/{site}/dropdown-pages/ ```
返回用于下拉菜单/菜单的简化页面列表。
#### 获取页面模板
```bash GET /wordpress/rest/v1.1/sites/{site}/page-templates ```
返回网站主题的可用页面模板。
### 文章点赞
#### 获取文章点赞
```bash GET /wordpress/rest/v1.1/sites/{site}/posts/{post_id}/likes ```
**响应：** ```json { "found": 99, "i_like": false, "can_like": true, "site_ID": 3584907, "post_ID": 83587, "likes": [...] } ```
#### 点赞文章
```bash POST /wordpress/rest/v1.1/sites/{site}/posts/{post_id}/likes/new ```
#### 取消点赞文章
```bash POST /wordpress/rest/v1.1/sites/{site}/posts/{post_id}/likes/mine/delete ```
### 文章转发
#### 检查转发状态
```bash GET /wordpress/rest/v1.1/sites/{site}/posts/{post_id}/reblogs/mine ```
**响应：** ```json { "can_reblog": true, "can_user_reblog": true, "is_reblogged": false } ```
### 文章类型
#### 列出文章类型
```bash GET /wordpress/rest/v1.1/sites/{site}/post-types ```
**响应：** ```json { "found": 3, "post_types": { "post": { "name": "post", "label": "Posts", "labels": {...} }, "page": { "name": "page", "label": "Pages", "labels": {...} } } } ```
### 文章统计
#### 获取文章统计
```bash GET /wordpress/rest/v1.1/sites/{site}/post-counts/{post_type} ```
**示例：** `/sites/{site}/post-counts/post` 或 `/sites/{site}/post-counts/page`
**响应：** ```json { "counts": { "all": {"count": 150}, "publish": {"count": 120}, "draft": {"count": 25}, "trash": {"count": 5} } } ```
### 用户
#### 列出站点用户
```bash GET /wordpress/rest/v1.1/sites/{site}/users ```
**响应：** ```json { "found": 3, "users": [ { "ID": 277004271, "login": "username", "name": "John Doe", "email": "[email protected]", "roles": ["administrator"] } ] } ```
### 用户设置
#### 获取用户设置
```bash GET /wordpress/rest/v1.1/me/settings ```
**响应：** ```json { "enable_translator": true, "surprise_me": false, "holidaysnow": false, "user_login": "username" } ```
#### 更新用户设置
```bash POST /wordpress/rest/v1.1/me/settings/ Content-Type: application/json
{ "enable_translator": false } ```
### 用户点赞
#### 获取用户点赞的文章
```bash GET /wordpress/rest/v1.1/me/likes ```
**响应：** ```json { "found": 10, "likes": [ { "ID": 83587, "site_ID": 3584907, "title": "Liked Post Title" } ] } ```
### 嵌入
#### 获取站点嵌入
```bash GET /wordpress/rest/v1.1/sites/{site}/embeds ```
返回站点的可用嵌入处理器。
### 短代码
#### 获取可用短代码
```bash GET /wordpress/rest/v1.1/sites/{site}/shortcodes ```
返回站点上可用的短代码。
## 分页
WordPress.com 使用基于游标的分页，通过 `page_handle`：
```python import os import requests
headers = { 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}' }
# Initial request response = requests.get( 'https://gateway.maton.ai/wordpress/rest/v1.1/sites/{site}/posts', headers=headers, params={'number': 20} ) result = response.json() all_posts = result['posts']
# Continue with page_handle while result.get('meta', {}).get('next_page'): response = requests.get( 'https://gateway.maton.ai/wordpress/rest/v1.1/sites/{site}/posts', headers=headers, params={'number': 20, 'page_handle': result['meta']['next_page']} ) result = response.json() all_posts.extend(result['posts'])
print(f"Total posts: {len(all_posts)}") ```
或者，使用 `offset` 进行简单分页：
```bash GET /wordpress/rest/v1.1/sites/{site}/posts?number=20&offset=20 ```
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/wordpress/rest/v1.1/sites/{site}/posts?number=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); console.log(`Found ${data.found} posts`); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/wordpress/rest/v1.1/sites/{site}/posts', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'number': 10, 'status': 'publish'} ) data = response.json() print(f"Found {data['found']} posts") ```
### Python (创建文章)
```python import os import requests
response = requests.post( 'https://gateway.maton.ai/wordpress/rest/v1.1/sites/{site}/posts/new', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'application/json' }, json={ 'title': 'My New Post', 'content': '<p>Hello World!</p>', 'status': 'draft', 'categories': 'news', 'tags': 'hello, first-post' } ) post = response.json() print(f"Created post ID: {post['ID']}") ```
## 注意事项
- WordPress.com API 使用 REST v1.1（非 v2） - 站点标识符可以是数字 ID 或域名 - 对 `/posts/{id}` 的 POST 请求会更新文章（而非 PUT/PATCH） - DELETE 使用 POST 请求到 `/posts/{id}/delete`（而非 HTTP DELETE） - 在文章中引用时，分类和标签会自动创建 - 日期/时间值为 ISO 8601 格式 - 所有内容均为 HTML 格式 - 重要：在将 curl 输出通过管道传递给 `jq` 或其他命令时，某些 Shell 环境中可能无法正确展开 `$MATON_API_KEY` 等环境变量
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 WordPress 连接或错误请求 | | 401 | Maton API 密钥无效或缺失 | | 403 | 权限不足或 OAuth 范围不符 | | 404 | 站点或资源未找到 | | 429 | 速率受限 | | 4xx/5xx | 来自 WordPress.com API 的透传错误 |
错误响应包含详细信息： ```json { "error": "unauthorized", "message": "User cannot view users for specified site" } ```
### 故障排除：API 密钥问题
1. 检查 `MATON_API_KEY` 环境变量是否已设置：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 故障排除：应用名称无效
1. 确保您的 URL 路径以 `wordpress` 开头。例如：
- 正确：`https://gateway.maton.ai/wordpress/rest/v1.1/sites/{site_id}/posts` - 错误：`https://gateway.maton.ai/rest/v1.1/sites/{site_id}/posts`
## 资源
- [WordPress.com REST API 概述](https://developer.wordpress.com/docs/api/) - [入门指南](https://developer.wordpress.com/docs/api/getting-started/) - [API 参考](https://developer.wordpress.com/docs/api/rest-api-reference/) - [OAuth 身份验证](https://developer.wordpress.com/docs/oauth2/) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])