Polr项目API开发指南：从认证到数据分析全解析

Polr项目API开发指南：从认证到数据分析全解析

polr :aerial_tramway: A modern, powerful, and robust URL shortener 项目地址: https://gitcode.com/gh_mirrors/po/polr

前言

Polr作为一个开源的URL缩短服务，提供了完善的API接口供开发者集成使用。本文将全面解析Polr API的使用方法，帮助开发者快速掌握API调用技巧。

API认证机制

API密钥获取与配置

Polr采用API密钥进行身份验证，每个请求都必须携带有效的API密钥。管理员可通过以下方式管理API密钥：

1. 管理面板操作

   • 登录管理员账户
   • 进入"Admin"选项卡
   • 找到目标用户，通过API按钮下拉菜单进行密钥管理
   • 可设置请求配额（每分钟请求数），负值表示无限制

2. 数据库直接操作

   • 修改users表中的api_key字段
   • 设置api_active为1(激活)或0(禁用)
   • 配置api_quota配额值

API核心功能详解

Polr API目前提供两大类操作：URL缩短和URL查询。

1. URL缩短功能

单URL缩短接口

• 端点：/api/v2/action/shorten
• 参数：
  • url：必填，待缩短的原始URL
  • is_secret：可选，是否创建私密链接，默认为false
  • custom_ending：可选，自定义短链后缀

示例请求：

GET /api/v2/action/shorten?key=API_KEY&url=https://example.com&custom_ending=myLink

响应示例(JSON)：

{
    "action": "shorten",
    "result": "https://yourdomain.com/myLink"
}

批量URL缩短接口

• 端点：/api/v2/action/shorten_bulk (仅支持POST)
• 参数：
  • data：包含URL数组的JSON字符串

请求体示例：

{
  "links": [
      {"url": "https://site1.com"},
      {"url": "https://site2.com", "is_secret": true},
      {"url": "https://site3.com", "custom_ending": "mysite"}
  ]
}

响应示例：

{
    "action": "shorten_bulk",
    "result": {
        "shortened_links": [
            {"long_url": "https://site1.com", "short_url": "http://yourdomain.com/ab1"},
            {"long_url": "https://site2.com", "short_url": "http://yourdomain.com/cd2/ef34"},
            {"long_url": "https://site3.com", "short_url": "http://yourdomain.com/mysite"}
        ]
    }
}

2. URL查询功能

• 端点：/api/v2/action/lookup
• 参数：
  • url_ending：必填，短链后缀
  • url_key：可选，查询私密链接时需要

响应示例：

{
    "action": "lookup",
    "result": "https://original-long-url.com"
}

数据分析接口

Polr提供了强大的数据分析能力，可获取短链的各种统计信息。

• 端点：/api/v2/data/link
• 参数：
  • url_ending：短链后缀
  • left_bound/right_bound：时间范围
  • stats_type：统计类型(day/country/referer)

统计类型详解

1. 按天统计：

   • 返回指定时间范围内每天的点击量
   • 数据格式：{"x":"日期","y":点击量}

2. 按国家统计：

   • 返回各国家的点击量
   • 数据格式：{"label":"国家代码","clicks":点击量}

3. 按来源统计：

   • 返回各来源网站的点击量
   • 数据格式：{"label":"来源网站","clicks":点击量}

权限说明：

• 普通用户只能查询自己的链接数据
• 管理员可查询所有链接数据
• 默认最多查询365天数据，可在配置中修改

错误处理机制

Polr API使用标准HTTP状态码表示请求状态，常见错误包括：

1. 400 Bad Request

   • 请求格式错误
   • 自定义后缀已被占用

2. 401 Unauthorized

   • API密钥无效或未激活
   • 查询私密链接时密钥错误

3. 403 Forbidden

   • 超过API调用配额

4. 404 Not Found

   • 查询的短链不存在

5. 500 Internal Server Error

   • 服务器内部错误

错误响应示例：

{
    "status_code": 429,
    "error_code": "QUOTA_EXCEEDED",
    "error": "Quota exceeded."
}

最佳实践建议

1. URL编码：所有URL参数必须进行URL编码
2. 响应类型：明确指定response_type参数(json/plain_text)
3. 错误处理：实现完善的错误处理逻辑
4. 配额管理：监控API使用情况，避免超过配额
5. 批量操作：大量URL处理时使用批量接口提高效率

结语

通过本文的详细解析，开发者应该已经掌握了Polr API的核心功能和使用方法。无论是简单的URL缩短，还是复杂的数据分析，Polr API都能提供稳定可靠的服务。建议在实际开发中参考本文的示例代码和最佳实践，以确保API集成的稳定性和效率。

polr :aerial_tramway: A modern, powerful, and robust URL shortener 项目地址: https://gitcode.com/gh_mirrors/po/polr