WordPress API 与 Gutenberg

概述

本技能提供全面指导，帮助您通过 WordPress REST API 创建和管理采用 Gutenberg 区块编辑器格式的文章。内容涵盖身份验证、区块序列化、媒体上传及发布工作流。

快速开始

使用 API 前，请确保已具备以下条件：

1. WordPress 站点：已启用 REST API（默认启用）

2. 身份验证凭据：

   • 应用密码（Application Password，适用于 WordPress 5.6+）：在 /wp-admin/admin.php?page=application-passwords 页面生成
   • 已安装 JWT Authentication 插件（替代方案）
   • 用户名/密码用于 Basic Auth（不建议在生产环境中使用）

3. 基础 URL：https://your-site.com/wp-json/wp/v2

身份验证

应用密码（推荐）

# 设置环境变量
export WP_URL="https://your-site.com"
export WP_USERNAME="admin"
export WP_APPLICATION_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx"

import requests
import os

wp_url = os.environ.get('WP_URL')
username = os.environ.get('WP_USERNAME')
password = os.environ.get('WP_APPLICATION_PASSWORD')

auth = (username, password)

JWT 身份验证

若使用 JWT 插件，请先获取令牌：

import requests

wp_url = "https://your-site.com"
username = "admin"
password = "password"

# 获取令牌
resp = requests.post(f"{wp_url}/wp-json/jwt-auth/v1/token", 
                     json={"username": username, "password": password})
token = resp.json()['token']

headers = {"Authorization": f"Bearer {token}"}

使用 Gutenberg 区块创建文章

WordPress REST API 要求文章以 Gutenberg 序列化区块格式提交。content 字段应包含区块注释及 HTML 内容。

基础区块结构

def create_gutenberg_post(title, content_blocks):
    """
    使用 Gutenberg 区块创建文章。
    
    参数:
        title: 文章标题
        content_blocks: 区块字典列表，每个字典包含 'blockName' 和 'attrs'
    
    返回:
        用于 POST 请求的 JSON 数据
    """
    # 将区块序列化为 Gutenberg 格式
    block_html = []
    for block in content_blocks:
        block_name = block.get('blockName', 'core/paragraph')
        attrs = block.get('attrs', {})
        inner_html = block.get('innerHTML', '')
        
        # 创建区块注释
        attrs_json = json.dumps(attrs) if attrs else ''
        block_comment = f''
        block_html.append(f'{block_comment}{inner_html}')
    
    content = '\n\n'.join(block_html)
    
    return {
        "title": title,
        "content": content,
        "status": "draft",  # 或 "publish"
        "format": "standard"
    }

常用区块示例

详见 references/common_blocks.md 中的详细示例，包括：

• 带格式化的段落区块
• 标题区块（h2–h4）
• 带图注与对齐方式的图像区块
• 列表区块（有序/无序）
• 引用区块
• 代码区块
• 自定义 HTML 区块
• 列布局与布局区块

完整工作流

步骤 1：准备身份验证

将凭据设置为环境变量或配置文件中。

步骤 2：构建文章数据

定义标题、内容区块、分类、标签及特色图像。

步骤 3：上传媒体（如需）

def upload_image(image_path, post_id=None):
    """将图像上传至 WordPress 媒体库。"""
    with open(image_path, 'rb') as f:
        files = {'file': f}
        data = {}
        if post_id:
            data['post'] = post_id
        
        response = requests.post(f"{wp_url}/wp-json/wp/v2/media",
                                 files=files, data=data, auth=auth)
        return response.json()

步骤 4：创建文章

def create_post(post_data):
    """创建新的 WordPress 文章。"""
    response = requests.post(f"{wp_url}/wp-json/wp/v2/posts",
                             json=post_data, auth=auth)
    return response.json()

步骤 5：更新状态

将草稿状态更改为已发布：

def publish_post(post_id):
    """发布一篇草稿文章。"""
    response = requests.post(f"{wp_url}/wp-json/wp/v2/posts/{post_id}",
                             json={"status": "publish"}, auth=auth)
    return response.json()

高级功能

分类与标签

# 获取或创建分类
def ensure_category(name, slug=None):
    categories = requests.get(f"{wp_url}/wp-json/wp/v2/categories",
                             params={"search": name}, auth=auth).json()
    if categories:
        return categories[0]['id']
    else:
        new_cat = requests.post(f"{wp_url}/wp-json/wp/v2/categories",
                               json={"name": name, "slug": slug or name.lower()},
                               auth=auth).json()
        return new_cat['id']

特色图像

# 先上传图像，再设为特色图像
image_data = upload_image("path/to/image.jpg")
post_data["featured_media"] = image_data['id']

自定义字段（ACF）

若使用 Advanced Custom Fields 插件：

post_data["meta"] = {
    "your_field_name": "field_value"
}

错误处理

请始终检查响应结果：

response = requests.post(...)
if response.status_code in [200, 201]:
    print("成功！")
else:
    print(f"错误 {response.status_code}: {response.text}")

常见问题：

• 401：身份验证失败
• 403：用户权限不足
• 404：端点未找到（请核对 WordPress 版本）
• 500：服务器错误（请检查 PHP 错误日志）

脚本

scripts/ 目录包含以下辅助工具：

• wp_publish.py：完整的发布流程脚本
• block_generator.py：从 Markdown 生成 Gutenberg 区块 HTML
• media_uploader.py：批量上传图像

参考资料

• common_blocks.md：详细的区块示例
• api_reference.md：完整的 WordPress REST API 参考文档
• troubleshooting.md：常见问题与解决方案

资源文件

• templates/article_template.json：典型文章结构的 JSON 模板
• block_samples/：各类内容类型的示例区块 HTML

请求示例

# 使用 curl 配合 Application Password 发送请求
curl -X POST https://your-site.com/wp-json/wp/v2/posts 
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" 
  -H "Content-Type: application/json" 
  -d '{
    "title": "我的新文章",
    "content": "
Hello World!
",
    "status": "draft"
  }'