目录

创建元服务链接

功能介绍

元服务链接是专为开发者设计的密文URL服务,它可以被用户点击并直达拉起元服务任意页面,实现元服务的点击触达,即点即用。

作为服务商,您可以为商家的元服务生成并配置专属的元服务链接,同时集成App Linking的融合码特性,实现扫描普通链接二维码跳转元服务的任意指定页面,提升用户体验。

接口原型

承载协议

HTTPS POST

接口方向

服务商服务器 -> 华为服务器

接口URL

https://connect-api.cloud.huawei.com/api/applinking/v1/harmonyos/shortLink

数据格式

响应消息:Content-Type: application/json

请求参数

[h2]Header

参数名称

必选(M)/可选(O)

类型

参数说明

client_id

M

String

API客户端ID。

创建第三方平台成功后系统自动分配的客户端ID,可在第三方管理平台“开发管理资料 > 开发配置”页面中获取,详情请参见获取平台访问凭据。

Authorization

M

String

认证信息,格式为“Authorization: Bearer ${access_token}”。access_token为获取平台级Token中获取的access_token。

appId

M

Integer(64)

应用ID。

请填写元服务的应用ID。

[h2]Body

参数名称

必选(M)/可选(O)

类型

参数说明

name

M

String(255)

元服务链接的名称。

isQRCodeLinked

M

Boolean

是否将元服务与普通链接二维码进行关联。

  • 如果希望用户扫描普通链接二维码后跳转到元服务,请选择“true”。
  • 如果没有普通链接二维码,可以选择“false”。

qrCodeRule

O

String(256)

二维码链接的匹配规则。

链接匹配规则组成部分:
  1. (必选)协议:仅支持http或https,精确匹配。
  2. (必选)域名:精确匹配。
  3. (可选)子路径:
    1. 如果链接匹配规则以/结尾,则匹配任意以该规则为前缀的子路径。
    2. 如果链接匹配规则不以/结尾,则不支持子路径匹配:
      1. {协议+域名+子路径}与链接匹配规则一致,匹配成功。
      2. {协议+域名+子路径}与链接匹配规则不一致时,匹配失败。
  4. (可选)动态参数:在URL中的?后,采用前缀匹配(即必须以链接匹配规则中配置的动态参数开始)。

链接匹配规则示例:

  • 示例1:https://www.example.com/a

    二维码链接可以是https://www.example.com/a、https://www.example.com/a?t=2等结构,不能是https://www.example.com/a/b的结构。

  • 示例2:https://www.example.com/a/

    二维码链接可以是https://www.example.com/a/b、https://www.example.com/a/b?t=1、https://www.example.com/a/b?t=1&f=2等结构。

  • 示例3:https://www.example.com/a?t=1

    二维码链接必须以https://www.example.com/a?t=1开头,可以是https://www.example.com/a?t=1、https://www.example.com/a?t=1&f=2等结构,不能是https://www.example.com/a?t=12的结构。

链接匹配规则限制:

  1. 链接匹配规则具有全局唯一性,不能配置完全相同的链接匹配规则。
  2. 每个元服务最多关联100个链接匹配规则。
说明:

isQRCodeLinked参数为true(关联)时,此参数必填。

testQrCodeUrl

O

String(1024)

填写普通链接二维码对应的链接。如果测试链接和链接匹配规则不符合,接口会返回204866445错误码。

此步骤用于提前验证配置的链接匹配规则,确保配置的二维码链接能准确跳转到元服务。

多个测试链接使用英文分号分隔,例如:https://www.example.com/a/b;https://www.example.com/a/b?t=1

isPrefixOccupied

O

Boolean

是否占用符合二维码匹配规则的所有子规则。

取值范围:

  • true:占用,表示其他元服务不可配置该元服务设置的前缀匹配规则的子规则。
  • false:不占用。
说明:

isQRCodeLinked参数为true(关联)时,此参数必填。

isReleased

M

Boolean

是否直接发布元服务链接。

取值范围:

  • true:直接发布。
  • false:保存为草稿。
说明:

当isReleased为false(保存为草稿)时,仅testQrCodeUrl生成的二维码在系统扫码后支持拉起元服务,适用于元服务上架前的调测。调测完成后,可调用修改元服务链接接口,将isReleased设置为true进行发布。发布后,所有符合qrCodeRule的二维码均支持扫描跳转元服务。

customParams

O

String(1024)

元服务链接的自定义参数。

用于精确定位到元服务指定页面。需要按key=value的键值对形式输入,多个键值对之间以“&”分隔。例如:key1=value1&key2=value2&key3=value3...

startTime

O

Integer(64)

元服务链接生效开始时间。

此时间是与1970年1月1日午夜之间的差值。

单位:毫秒

示例:1704211200000

说明:

isQRCodeLinked参数为false(不关联)时,此参数必填。

endTime

O

Integer(64)

元服务链接生效结束时间。

此时间是与1970年1月1日午夜之间的差值。

单位:毫秒

示例:1704211200000

说明:

isQRCodeLinked参数为false(不关联)时,此参数必填。

请求示例

POST /api/applinking/v1/harmonyos/shortLink HTTP/1.1
Host: connect-api.cloud.huawei.com
client_id: 41******68
Content-Type: application/json
Authorization: Bearer ******
appId: 1******57
{
  "name": "test***001",
  "isQRCodeLinked": true,
  "qrCodeRule": "https://linking.***.cn/test***001",
  "testQrCodeUrl": "https://linking.***.cn/test***001",
  "isPrefixOccupied": true,
  "isReleased": true,
  "customParams": "key1=a",
  "startTime": 1761555566000,
  "endTime": 4102243200000
}

响应参数

参数

必选(M)/可选(O)

参数类型

描述

ret

M

ConnectRet

包含返回码及描述信息的结果。

linkInfos

O

HmLinkDetailByServerInfo

元服务链接详细信息。

响应示例

{
  "ret": {
    "code": 0,
    "msg": "success"
  },
  "linkInfos": {
    "name": "test***001",
    "shortUrl": "https://******.cn/*****",
    "startTime": 1761555566000,
    "endTime": 4102243200000,
    "atomicService": {
      "packageName": "com.******.******",
      "customParams": "key1=a",
      "appId": 1******57
    }
  }
}