Revive Adserver Restapi Plugin

恢复Adserver REST API插件

Revive Adserver的全面REST API插件，为管理活动、横幅、区域、目标和统计数据提供RESTful端点。具有一个完整的API令牌管理系统，带有管理面板界面，用于安全身份验证和细粒度权限。完全兼容 恢复广告服务器mcp 服务器。

特性

核心API功能

• ✅ 活动管理 -完成广告活动的CRUD操作
• ✅ 横幅管理 -上传、管理和配置横幅广告
• ✅ 区域配置 -配置和管理广告区和广告位
• ✅ 高级目标定位 -使用规则集进行地理、基于时间的设备和URL定位
• ✅ 统计与分析 -全面的绩效报告和指标
• ✅ 文件上传系统 -带验证的安全横幅文件上传

安全和身份验证

• ✅ API代币管理 -完整的基于令牌的身份验证系统
• ✅ 管理面板 -基于Web的令牌和设置管理界面
• ✅ 权限系统 -精细权限（16个不同的访问级别）
• ✅ 会话身份验证 -与现有的Revive管理会话集成
• ✅ 速率限制 -可配置每个IP请求限制和安全控制
• ✅ 使用情况分析 -完整的审计跟踪和令牌使用监控

集成与兼容性

• ✅ MCP兼容 -与完全集成 恢复广告服务器mcp
• ✅ CORS支持 -web应用程序的跨源请求处理
• ✅ REST标准 -RESTful API设计，具有一致的JSON响应
• ✅ 恢复整合 -与Revive Adserver 5.x的原生集成

需求

• 恢复Adserver 5.0+
• PHP 7.4+
• MySQL 5.7+或MariaDB 10.3+

安装

推荐：插件安装程序（简易）

安装此插件的最简单方法是使用Revive Adserver内置插件安装程序：

1. 下载插件包

- 转到 发布页面 - 下载最新 reviveRestApi-X.X.X.zip 文件

1. 访问插件安装程序

- 登录您的Revive Adserver管理面板 - 引导到 插件 → 插件管理

1. 安装插件

- 点击 “安装插件” 按钮 - 选择 “上传插件” - 选择已下载的 reviveRestApi-X.X.X.zip 文件 - 点击 “上传” 安装

1. 激活插件

- 上传后，在插件列表中找到“Revive REST API（MCP Compatible）” - 点击 “安装” 激活插件 - 插件状态应更改为“已启用”

1. 配置设置

- 点击 “设置” 插件旁边 - 配置 API基本路径 （默认值： /api/v1) - 保存您的设置

1. 验证安装

- 测试API运行状况终结点： http://yoursite.com/api/v1/health - 您应该收到一个JSON响应，确认API正在工作

1. 访问令牌管理

- 导航到： http://yoursite.com/plugins/reviveRestApi/www/admin/ - 通过web界面创建和管理API令牌 - 配置API设置和安全控制

替代方案：手动安装

如果您更喜欢手动安装：

1. 下载插件文件

- 下载最新版本的ZIP文件 - 提取内容

1. 上载到服务器

- 上传 reviveRestApi 文件夹到： /path/to/revive/plugins/ - 确保适当的文件权限（可由web服务器读取）

1. 通过管理面板安装

- 访问您的Revive管理面板 - 引导到 插件 → 插件管理 - 找到“恢复REST API（MCP兼容）”，然后单击 安装 - 根据需要配置插件设置

Docker安装

如果使用此存储库中的Docker设置：

# Plugin is already included in the container
docker-compose up -d

安装故障排除

插件未显示：

• 验证ZIP文件是否正确上传
• 检查插件目录上的文件权限
• 确保Revive Adserver版本兼容性（5.0+）

上传失败：

• 检查PHP上传限制(upload_max_filesize, post_max_size)
• 验证服务器上的磁盘空间
• 确保web服务器具有对插件目录的写入权限

安装后API不工作：

• 清除所有缓存（浏览器、CDN、服务器端）
• 检查是否启用了web服务器URL重写
• 验证没有冲突的插件或.htaccess规则

管理面板

访问管理界面

导航到： http://yoursite.com/plugins/reviveRestApi/www/admin/

需求：必须先登录Revive Adserver管理面板

令牌管理功能

• 创建API令牌：生成具有自定义权限的安全令牌
• 代币概述：查看所有令牌的使用统计数据和状态
• 权限控制：分配精细权限（活动、横幅、区域等）
• 使用情况分析：监视令牌使用模式和API活动
• 代币生命周期：根据需要激活、停用和删除令牌

API设置配置

• 启用/禁用API：全球API开/关控制
• 身份验证要求：强制对所有端点进行身份验证
• 速率限制：配置每分钟请求数（默认值：100）
• 令牌到期：设置默认令牌到期日（默认值：90天）
• 用户令牌限制：每个用户的最大令牌数（默认值：5）

安全控制

• 令牌监控：实时使用情况跟踪和警报
• IP限制：通过IP地址监视和控制访问
• 审计跟踪：所有API代币活动的完整日志
• 权限管理：细粒度访问控制系统

配置

插件设置可以通过以下方式配置：

1. 管理面板界面 （推荐）：

- 引导到 /plugins/reviveRestApi/www/admin/ - 使用“设置”选项卡进行配置

1. 恢复插件设置:

- 插件 → 插件管理 → 设置 - 配置 API基本路径 （默认值： /api/v1)

API文档

基本URL

/api/v1

可用端点

健康检查

GET /api/v1/health

活动

GET    /api/v1/campaigns           # List campaigns
POST   /api/v1/campaigns           # Create campaign
GET    /api/v1/campaigns/{id}      # Get campaign details
PUT    /api/v1/campaigns/{id}      # Update campaign
DELETE /api/v1/campaigns/{id}      # Delete campaign

横幅

GET    /api/v1/banners             # List banners
POST   /api/v1/banners             # Create banner
GET    /api/v1/banners/{id}        # Get banner details
PUT    /api/v1/banners/{id}        # Update banner
DELETE /api/v1/banners/{id}        # Delete banner
POST   /api/v1/banners/{id}/upload # Upload banner file

区域

GET    /api/v1/zones               # List zones
POST   /api/v1/zones               # Create zone
GET    /api/v1/zones/{id}          # Get zone details
PUT    /api/v1/zones/{id}          # Update zone
DELETE /api/v1/zones/{id}          # Delete zone

定向

GET /api/v1/campaigns/{id}/targeting   # Get campaign targeting
PUT /api/v1/campaigns/{id}/targeting   # Update campaign targeting
GET /api/v1/banners/{id}/targeting     # Get banner targeting
PUT /api/v1/banners/{id}/targeting     # Update banner targeting

统计

GET /api/v1/stats/campaigns            # Campaign statistics
GET /api/v1/stats/campaigns/{id}       # Specific campaign stats
GET /api/v1/stats/banners              # Banner statistics  
GET /api/v1/stats/banners/{id}         # Specific banner stats
GET /api/v1/stats/zones                # Zone statistics
GET /api/v1/stats/zones/{id}           # Specific zone stats

认证

API通过完整的令牌管理系统支持两种身份验证方法：

基于会话的身份验证

对于登录到Revive管理界面的用户，API请求将自动使用现有会话。

基于令牌的身份验证

该插件包括一个完整的API令牌管理系统与管理面板集成。

创建API令牌

1. 登录您的Revive Adserver管理面板
2. 导航到： /plugins/reviveRestApi/www/admin/
3. 点击“创建新令牌”
4. 输入令牌名称并选择权限
5. 安全地保存生成的令牌（仅显示一次）

使用API令牌

通过以下方式之一包含您的API令牌：

授权标头（推荐）：

Authorization: Bearer rapi_YourTokenHere

自定义标题：

X-API-Token: rapi_YourTokenHere

查询参数：

/api/v1/campaigns?api_token=rapi_YourTokenHere

令牌管理功能

• 安全生成：使用SHA-256哈希的加密安全令牌
• 权限系统：精细权限（campaigns.read、banners.write等）
• 过期控制：可配置的令牌过期时间（默认值：90天）
• 使用情况分析：使用详细的日志记录跟踪令牌使用情况
• 管理面板：用于令牌管理的基于Web的界面
• 速率限制：可配置每个IP请求限制

API令牌端点

# List your tokens
GET /api/v1/tokens

# Create new token
POST /api/v1/tokens
{
  "name": "My API Token",
  "permissions": ["campaigns.read", "stats.read"]
}

# Delete token
DELETE /api/v1/tokens/{id}

可用权限

• campaigns.read/write/delete -活动管理
• banners.read/write/delete/upload -横幅管理
• zones.read/write/delete -区域管理
• targeting.read/write -目标规则
• rulesets.read/write/delete/apply -规则集管理
• stats.read -统计访问
• all -API完全访问

有关完整的令牌管理文档，请参阅 代币管理.md.

使用示例

创建活动

curl -X POST http://yoursite.com/api/v1/campaigns \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rapi_YourTokenHere" \
  -d '{
    "campaignname": "Summer Sale 2024",
    "clientid": 1,
    "views": 100000,
    "clicks": 5000,
    "revenue": 2500.00,
    "status": 0
  }'

上传横幅

curl -X POST http://yoursite.com/api/v1/banners/1/upload \
  -H "Authorization: Bearer rapi_YourTokenHere" \
  -F "file=@banner-300x250.jpg"

设置地理定位

curl -X PUT http://yoursite.com/api/v1/campaigns/1/targeting \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rapi_YourTokenHere" \
  -d '{
    "geo": {
      "countries": ["US", "CA", "UK"],
      "regions": ["California", "New York", "London"]
    },
    "time": {
      "hour_from": 9,
      "hour_to": 17,
      "days": [1, 2, 3, 4, 5]
    }
  }'

创建API令牌

curl -X POST http://yoursite.com/api/v1/tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rapi_AdminTokenHere" \
  -d '{
    "name": "Campaign Manager",
    "permissions": ["campaigns.read", "campaigns.write", "stats.read"]
  }'

管理API令牌

# List all tokens
curl -X GET http://yoursite.com/api/v1/tokens \
  -H "Authorization: Bearer rapi_YourTokenHere"

# Get token details with usage stats
curl -X GET http://yoursite.com/api/v1/tokens/1 \
  -H "Authorization: Bearer rapi_YourTokenHere"

# Delete a token
curl -X DELETE http://yoursite.com/api/v1/tokens/1 \
  -H "Authorization: Bearer rapi_YourTokenHere"

响应格式

成功响应

{
  "success": true,
  "data": { ... },
  "meta": {
    "total": 100,
    "limit": 20,
    "offset": 0,
    "page": 1,
    "pages": 5
  }
}

错误响应

{
  "error": "Error message",
  "code": 400,
  "timestamp": "2024-08-20T14:30:00+00:00"
}

MCP服务器兼容性

此插件旨在与 恢复广告服务器mcp 模型上下文协议服务器，通过Claude Code实现与广告服务器的自然语言交互。

安全功能

身份验证和授权

• 双重身份验证：基于会话和基于令牌的身份验证方法
• API代币系统：使用SHA-256哈希的加密安全令牌
• 权限系统：16个细粒度权限（campaigns.read、banners.write等）
• 代币生命周期：安全生成、验证、过期和撤销
• 管理面板访问：使用基于会话的身份验证的安全web界面

安全控制

• 速率限制：可配置每个IP请求限制（默认值：100/分钟）
• 令牌到期：自动令牌过期（可配置，默认值：90天）
• 使用情况监控：完成所有API令牌使用情况的审核跟踪
• 输入验证：跨所有端点的XSS和SQL注入保护
• 安全存储：令牌存储为SHA-256哈希值，从不以纯文本形式存储

高级安全性

• CORS 管理：可配置的跨源资源共享
• IP跟踪：按IP地址监视和记录所有API请求
• 用户代理日志记录：跟踪访问API的客户端应用程序
• 安全事件日志记录：全面的安全事件监控
• 身份验证跟踪失败：监控身份验证失败并发出警报

故障排除

API常见问题

401未经授权的错误

症状：API返回401状态代码 原因和解决方案:

• 身份验证已禁用：检查是否 require_authentication 设置为 0 在API设置中
• 令牌格式无效：确保令牌以开头 rapi_ 并且格式正确
• 过期令牌：在管理面板中检查令牌到期日期
• 非活动令牌：验证令牌是否处于活动状态(is_active = 1)在管理面板中

403禁止错误

症状：API返回403状态代码 原因和解决方案:

• 权限不足：检查令牌权限是否与所需的端点访问相匹配
• 缺少权限：添加所需的权限（例如。， campaigns.read)到令牌
• 代币所有权：确保用户有权查看/修改请求的令牌

令牌不工作

症状：API拒绝的有效令牌 诊断步骤:

1. 验证令牌格式：应以开头 rapi_ 前缀
2. 检查过期时间：在管理面板中查看令牌详细信息
3. 确认权限：确保令牌具有端点所需的权限
4. 使用管理员会话进行测试：登录管理面板时尝试相同的端点
5. 检查API设置：验证是否已启用API并正确配置了身份验证

管理面板访问问题

症状：无法访问 /plugins/reviveRestApi/www/admin/ 解决方案:

• 需要登录：必须先登录到Revive管理面板
• 文件权限：检查管理目录上的web服务器读取权限
• URL路径：根据您的安装验证正确的插件路径
• 数据库表：确保在安装过程中创建了令牌管理表

调试步骤

1. 测试API健康状况: GET /api/v1/health 应返回JSON状态
2. 检查数据库：验证 api_tokens, api_token_usage，以及 api_settings 表存在
3. 审核日志：检查web服务器错误日志中的PHP错误
4. 令牌验证：使用管理面板查看令牌状态和使用情况
5. 权限测试：尝试使用会话身份验证的端点（登录到管理员）

获取帮助

关于代币相关问题：

1. 在管理面板中检查令牌状态(/plugins/reviveRestApi/www/admin/)
2. 审查 代币管理.md 获取详细文档
3. 使用不同的权限组合进行测试
4. 监控身份验证模式的使用日志

支持

对于问题、疑问或贡献：

1. 检查文档
2. 审查现有问题
3. 创建包含详细信息的新问题

许可证

此插件根据GPL-2.0+许可证发布，与Revive Adserver的许可证兼容。

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

更新日志

看 更改日志.md 查看版本历史和更改。