Know Your Wisdom

如何接入API？

2025-11-04

鉴权

字段描述
USER_TOKEN用户登录后台会自动生成该 Token，注销登录后失效
  1. 使用 Token 鉴权
Authorization: Token {{USER_TOKEN}}

用户登录后台会自动生成 Token，注销登录后失效。

你可以 F12 打开浏览器开发者工具，刷新页面后，在 网络 一栏里任选 API 访问获得 Token。

  1. 使用 Basic Auth 鉴权

第一步： 进入后台、账户、个人信息页面，设置密码。

比如你的用户名是 demo，密码是 123456。

第二步：运行该命令，生成 Base64 编码的凭据字符串

echo -n "demo:123456" | base64

输出： ZGVtbzoxMjM0NTYK

第三步： 在 API 请求头中使用该字符串

Authorization: Basic ZGVtbzoxMjM0NTYK

Swagger 文档

点击访问

API 列表

创建模版落地页

  • Reuqest
POST https://rpc.knowuv.com/shortlink.ShortLinkService/CreateLandingPageShortLink
Authorization: Token {{USER_TOKEN}}
Content-Type: application/json

{
  "templateName": "wxmp_gift",
  "urlQuery": {
    "appid": "wx15f182efdb0ba66c",
    "path": "/pages/index/index",
    "title": "泡泡🫧马特测试 PopMart",
    "description": "这是一大串描述信息，用于测试生成落地页短链接的功能是否正常工作。",
    "btn_text":    "去抽盒子🎉",
    "image": "https://nouv.oss-cn-shanghai.aliyuncs.com/_nuxt/imgs/img.png"
  }
}
  • Response
{
  "msg": "Landing Page short link created successfully",
  "shortlink": "https://wx.knowuv.com/yaARm"
}

创建微信小程序短链接

POST https://rpc.knowuv.com/shortlink.ShortLinkService/CreateWxMpShortLink
Authorization: Token {{USER_TOKEN}}
Content-Type: application/json

{
  "appid": "wx15f182efdb0ba66c",
  "path": "/pages/index/index",
  "title": "泡泡🫧马特测试 PopMart"
}
  • Response
{
  "msg": "WxMp short link created successfully",
  "shortlink": "https://h5.knowuv.com/2w3Fu"
}

proto 定义：

message CreateWxMpShortLinkRequest {
  string appid = 1;
  string path = 2;
  string title = 3;
  int64 etime = 4;
}

message CreateWxMpShortLinkResponse {
  int32 code = 1;
  string msg = 2;
  string shortlink = 3;
}

创建 MDC 短链接

MDC 是 Nuxt 基于 Markdown 拓展的语法，可以允许自定义页面。

优点是非常灵活，示例页面：https://h5.knowuv.com/N3R6y

用法：

  1. 进入 MDC 编辑器，编辑自己想要的页面
  2. 把内容全选，传进 API 即可

路径： /shortlink.ShortLinkService/CreateMdcShortLink

请求格式：

message CreateMdcShortLinkRequest {
  string mdcContent = 1;
  map<string, string> urlQuery = 2;
  int64 etime = 3;
}

message CreateMdcShortLinkResponse {
  int32 code = 1;
  string msg = 2;
  string shortlink = 3;
}

完整的 proto 定义

enum ShortLinkType {
  INVALID = 0[(mandarin) = "无效"];
  INTERNAL = 1[(mandarin) = "内部"];
  JOB = 2[(mandarin) = "任务"];
  DEPARTMENT = 3[(mandarin) = "部门"];
  EXTERNAL = 4[(mandarin) = "外部"];
}

enum ShortLinkStatus {
  Normal = 0[(mandarin) = "正常"];
  Deleted = 1[(mandarin) = "删除"];
  Invalid = 2[(mandarin) = "无效"];
  Expired = 3[(mandarin) = "过期"];
  Restricted = 4[(mandarin) = "封禁"];
  Auditing = 5[(mandarin) = "审核中"];
}

enum ShortLinkChartType {
  Last24HoursPv = 0[(mandarin) = "过去24小时访问趋势"];
  Last3DaysPv = 1[(mandarin) = "过去3天访问趋势"];
  Last7DaysPv = 2[(mandarin) = "过去7天访问趋势"];
  Last30DaysPv = 3[(mandarin) = "过去30天访问趋势"];
  Last90DaysPv = 4[(mandarin) = "过去90天访问趋势"];
  Last180DaysPv = 5[(mandarin) = "过去180天访问趋势"];
  Last365DaysPv = 6[(mandarin) = "过去365天访问趋势"];
  TimeDistribution = 7[(mandarin) = "时间分布"];
  CityDistribution = 8[(mandarin) = "城市分布"];
  TrafficSource = 9[(mandarin) = "流量来源"];
}

message ShortLink {
  string short_link_code = 1; // 短链码
  string origin_url = 2; // 源链
  string origin_url_md5 = 3; // 源链MD5
  uint32 pv = 4; // 访问次数
  uint32 type = 5; // 短链类型
  string remark = 6; // 短链标记
  uint32 status = 7; // 短链状态
}

message CreateShortLinkRequest {
  string origin_url = 1; // 源链
  string remark = 2; // 短链标记
  uint32 type = 3; // 短链类型
}

message CreateShortLinkResponse {
  int32 code = 1;
  string msg = 2;
  ShortLink data = 3;
}

message GetShortLinkRequest {
  string short_link_code = 1; // 短链码
}

message GetShortLinkResponse {
  int32 code = 1;
  string msg = 2;
  ShortLink data = 3;
}

message VisitShortLinkRequest {
  string short_link_code = 1; // 短链码
}

message VisitShortLinkResponse {
  int32 code = 1;
  string msg = 2;
  string data = 3;
}

message OriginLinkItem {
  string url = 1;
  int32 weight = 2;
  string title = 3;
  string _id = 4;
  string hash = 5;
}

message ShortLinkPluginOptions {
  string name = 1;
  map<string, string> data = 2;
}

message CreateShortLinkRequestV2 {
  repeated OriginLinkItem originLinkList = 1;
  string domain = 2;
  repeated string tags = 3;
  repeated ShortLinkPluginOptions pluginOptions = 4;
  string fallbackPage = 5;
  int64 etime = 6;
  string template_name = 7;
  map<string, string> templateParameters = 8;
  int32 status = 9;
}

message CreateShortLinkResponseV2Data {
  int64 pk = 1;
  repeated OriginLinkItem originLinkList = 2;
  repeated string tags = 3;
  int32 status = 4;
  int64 etime = 5;
  int32 pv = 6;
  string domain = 7;
  string fallbackPage = 8;
  string _id = 9;
  int64 ctime = 10;
  int64 mtime = 11;
  string code = 12;
  int32 __v = 13;
  int64 user_id = 14;
  string templateName = 15;
  map<string, string> templateParameters = 16;
  int32 todayPv = 17; // 今日访问量
  repeated ShortLinkPluginOptions pluginOptions = 18;
}

message CreateShortLinkResponseV2 {
  int32 code = 1;
  string msg = 2;
  CreateShortLinkResponseV2Data data = 3;
}

message ListShortLinkRequestV2 {
  string short_link_code = 1; // 短链码
  int32 page = 2;
  int32 page_size = 3;
  repeated string contain_origin_url = 4;
  repeated string contain_tag = 5;
  optional string template_name = 6;
  optional int32 status = 7;
}

message ListShortLinkResponseV2 {
  int32 code = 1;
  string msg = 2;
  repeated CreateShortLinkResponseV2Data data = 3;
  int32 total = 4;
}

message ShortLinkPv {
  string _id = 1;
  int64 pk = 2;
  string user_agent = 3;
  string referrer = 4;
  int64 ctime = 5;
  string ip = 6;
  string os = 7;
  string device = 8;
  string city = 9;
  string region = 10;
  string country = 11;
  string url = 12;
}

message ListShortLinkPvDetailRequest {
  string short_link_code = 1; // 短链码
  int32 page = 2;
  int32 page_size = 3;
}

message ListShortLinkPvDetailResponse {
  int32 code = 1;
  string msg = 2;
  repeated ShortLinkPv data = 3;
  int32 total = 4;
}

message GetShortLinkChartRequest {
  string short_link_code = 1;
  ShortLinkChartType chart_type = 2;
  string pk = 3;
}

// Chart.js dataset structure
message ChartJsDataset {
  string label = 1;
  repeated int32 data = 2;
  bool includeToday = 3;  //  get today data from redis
  // Optionally add more Chart.js dataset fields if needed, e.g. backgroundColor, borderColor, etc.
  // repeated string backgroundColor = 3;
  // repeated string borderColor = 4;
}

// Chart.js compatible response
message GetShortLinkChartResponse {
  int32 code = 1;
  string msg = 2;
  repeated string labels = 3; // x-axis labels
  repeated ChartJsDataset datasets = 4; // y-axis datasets
}

message UpdateShortLinkRequestV2 {
  string short_link_code = 1;
  repeated OriginLinkItem originLinkList = 2;
  optional string domain = 3;
  repeated string tags = 4;
  repeated ShortLinkPluginOptions pluginOptions = 5;
  optional string fallbackPage = 7;
  optional int64 etime = 8;
  int64 pk = 9;
  optional int32 status = 10;
  optional string templateName = 11;
  map<string, string> templateParameters = 12;
  repeated string cleanList = 13; // 需要清除的字段列表
}

message UpdateShortLinkResponseV2 {
  int32 code = 1;
  string msg = 2;
  CreateShortLinkResponseV2Data data = 3;
}

message UpdateShortLinkResponse {
  int32 code = 1;
  string msg = 2;
  CreateShortLinkResponseV2Data data = 3;
}

message DeleteShortLinkRequestV2 {
  repeated int64 pk_list = 1;
  repeated string code_list = 2;
}

message DeleteShortLinkResponseV2 {
  int32 code = 1;
  string msg = 2;
  int32 affected = 3;
}

message ListAvailableDomainsRequest {
}

message DomainItem {
  string name = 1;  //  frontend display name
  string value = 2; //  frontend value
}

message ListAvailableDomainsResponse {
  int32 code = 1;
  string msg = 2;
  repeated DomainItem data = 3;
}

message CreateWxMpShortLinkRequest {
  string appid = 1;
  string path = 2;
  string title = 3;
  int64 etime = 4;    //  毫秒级的时间戳，过期时间
}

message CreateWxMpShortLinkResponse {
  int32 code = 1;
  string msg = 2;
  string shortlink = 3;
}

message CreateMdcShortLinkRequest {
  string mdcContent = 1;
  map<string, string> urlQuery = 2;
  int64 etime = 3;    //  毫秒级的时间戳，过期时间
}

message CreateMdcShortLinkResponse {
  int32 code = 1;
  string msg = 2;
  string shortlink = 3;
}

service ShortLinkService {
  rpc CreateShortLink(CreateShortLinkRequest) returns (CreateShortLinkResponse) {
    option (google.api.http) = {
      post: "/grpc-gateway/v1/shortlink/create"
      body: "*"
    };
  }

  rpc GetShortLink(GetShortLinkRequest) returns (GetShortLinkResponse) {
    option (google.api.http) = {
      post: "/grpc-gateway/v1/shortlink/get"
      body: "*"
    };
  }

  rpc VisitShortLink(VisitShortLinkRequest) returns (VisitShortLinkResponse) {
    option (google.api.http) = {
      post: "/grpc-gateway/v1/shortlink/visit"
      body: "*"
    };
  }

  rpc CreateShortLinkV2(CreateShortLinkRequestV2) returns (CreateShortLinkResponseV2) {
    option (google.api.http) = {
      post: "/grpc-gateway/v1/shortlink/create_v2"
      body: "*"
    };
  }

  rpc ListShortLinkV2(ListShortLinkRequestV2) returns (ListShortLinkResponseV2) {
    option (google.api.http) = {
      post: "/grpc-gateway/v1/shortlink/list_v2"
      body: "*"
    };
  }

  rpc UpdateShortLinkV2(UpdateShortLinkRequestV2) returns (UpdateShortLinkResponseV2) {
    option (google.api.http) = {
      post: "/grpc-gateway/v1/shortlink/update_v2"
      body: "*"
    };
  }

  rpc DeleteShortLinkV2(DeleteShortLinkRequestV2) returns (DeleteShortLinkResponseV2) {
    option (google.api.http) = {
      post: "/grpc-gateway/v1/shortlink/delete_v2"
      body: "*"
    };
  }

  rpc ListShortLinkPvDetail(ListShortLinkPvDetailRequest) returns (ListShortLinkPvDetailResponse) {
    option (google.api.http) = {
      post: "/grpc-gateway/v1/shortlink/list_pv_detail"
      body: "*"
    };
  }

  rpc GetShortLinkChart(GetShortLinkChartRequest) returns (GetShortLinkChartResponse) {
    option (google.api.http) = {
      post: "/grpc-gateway/v1/shortlink/get_chart"
      body: "*"
    };
  }

  rpc ListAvailableDomains(ListAvailableDomainsRequest) returns (ListAvailableDomainsResponse) {
    option (google.api.http) = {
      post: "/grpc-gateway/v1/shortlink/list_available_domains"
      body: "*"
    };
  }

  rpc CreateWxMpShortLink(CreateWxMpShortLinkRequest) returns (CreateWxMpShortLinkResponse) {
    option (google.api.http) = {
      post: "/grpc-gateway/v1/shortlink/create_wxmp_shortlink"
      body: "*"
    };
  }

  rpc CreateMdcShortLink(CreateMdcShortLinkRequest) returns (CreateMdcShortLinkResponse) {
    option (google.api.http) = {
      post: "/grpc-gateway/v1/shortlink/create_mdc_shortlink"
      body: "*"
    };
  }
}

如果你还有任何操作疑问，欢迎随时联系我们
🤝 KnowUV —— 稳稳连接客户！🚀

如有其他问题，请邮件联系： dusty-cjh@qq.com

Catalogue