服务开发

更新时间：2026-08-24

本文为您介绍如何创建、开发、测试和发布数据服务 API。

前提条件

BLB

开通BLB

数据服务使用需开通负载均衡 BLB 服务。点击去开通。

创建实例

在负载均衡 BLB 中创建应用型实例，需通过接口创建（BLB 控制台不支持开启 underlayVip，只能调用 BCE OpenAPI）。数据服务要求关联的 BLB 实例必须开启 underlayVip，否则会导致调用请求失败。

平台在下方提供 create-blb-py2.sh 脚本，封装了"创建 + 轮询校验"的完整流程，执行后自动创建 BLB 并确认 underlayVip 生效，无需手动调用接口。

前置条件

本机已安装 bash、curl、openssl、python2.7（脚本会依次尝试 python2.7 / python2 / python，只要是 2.x 版本即可）
已获取有效的百度云 AK/SK，且该账号在目标地域有 BLB 创建权限
目标 VPC、子网已存在，且与要创建 BLB 的地域一致

操作步骤

给脚本添加可执行权限：

Bash

1chmod +x create-blb-py2.sh

执行创建命令，填入 BLB 名称、VPC ID、子网 ID、地域、AK、SK：

                Bash
                
            

                ./create-blb-py2.sh \
  --name       MyBLB \
  --vpc-id     vpc-xxxxxxx \
  --subnet-id  sbn-xxxxxxx \
  --region     bd \
  --ak         ALTAK******** \
  --sk         ******************************
            

--region 可选 bj（北京）/ gz（广州）/ su（苏州）/ bd（保定）/ cd（成都），须与 VPC、子网所在地域一致，否则会报 NoSuchVpc / NoSuchSubnet。

推荐用环境变量传密钥，避免明文出现在命令行历史中。

                Bash
                
                export BCE_AK=ALTAK********
export BCE_SK=******************************
./create-blb-py2.sh --name MyBLB --vpc-id vpc-xxxxxxx --subnet-id sbn-xxxxxxx --region bd

脚本会自动创建 BLB 并轮询查询状态，直到 status 变为 available 且 underlayVip 不为空，成功后输出：

Plain Text

1✅ BLB 创建并校验通过
2  blbId       : lb-45tiisqp
3  address     : 192.168.0.10   (overlay VIP)
4  underlayVip : 100.66.144.2
5  region      : bd

记下返回的 blbId，创建数据服务 API 时需要在"应用型 BLB 实例"配置项中选择该实例。

常见问题

现象	可能原因	处理方式
报错 `SignatureDoesNotMatch`	本机时间与标准时间偏差过大，或 AK/SK 填写有误（含多余空格/换行）	执行 `date -u` 核对时间；确认 AK/SK 是否正确
`underlayVip` 一直为空，最终轮询超时（默认 120 秒，可用 `--poll-timeout` 调整）	目标地域账号配额已用尽	联系云平台，凭响应中的 `X-Bce-Request-Id` 排查
创建失败，提示 `NoSuchVpc` / `NoSuchSubnet`	VPC/子网与 `--region` 不在同一地域	核对三者地域是否一致

如需在不实际创建的情况下校验参数和签名是否正确，可加 --dry-run 参数，脚本只会打印请求内容而不发送请求。

脚本内容（create-blb-py2.sh）

将下列内容保存为本地文件 create-blb-py2.sh 后按上述步骤执行即可。

                Bash
                
            

                #!/usr/bin/env bash
# =============================================================================
# create-blb-py2.sh
#
# 一键创建带 underlayVip 的百度云 BLB 并校验。python2.7 兼容版。
# 内置 BCE V1 签名算法，无外部签名工具。
#
# 依赖: bash 4+, curl, openssl, python2.7
# =============================================================================
set -euo pipefail

# ---------------- 使用说明 ----------------
usage() {
  cat <<'EOF'
用法:
  create-blb-py2.sh --name NAME --vpc-id VPC_ID --subnet-id SUBNET_ID \
                    --region REGION --ak AK --sk SK [选项]

必填参数:
  --name NAME           BLB 名称
  --vpc-id VPC_ID       目标 VPC ID (需与 region 匹配)
  --subnet-id SUBNET_ID 目标子网 ID (需与 region 匹配)
  --region REGION       地域代码, 可选: bj|gz|su|bd|cd
  --ak AK               Access Key   (或用环境变量 BCE_AK)
  --sk SK               Secret Key   (或用环境变量 BCE_SK)

可选参数:
  --protocol http|https 请求协议, 默认 http
  --expires SECONDS     签名有效期(秒), 默认 1800
  --poll-interval S     BLB 状态轮询间隔(秒), 默认 3
  --poll-timeout S      轮询总超时(秒), 默认 120
  --dry-run             只打印将要发送的请求与签名, 不实际请求
  -h, --help            显示帮助

地域 endpoint 对照:
  bj -> blb.bj.baidubce.com   (北京)
  gz -> blb.gz.baidubce.com   (广州)
  su -> blb.su.baidubce.com   (苏州)
  bd -> blb.bd.baidubce.com   (保定)
  cd -> blb.cd.baidubce.com   (成都)

示例:
  ./create-blb-py2.sh \
    --name  MyBlb \
    --vpc-id    vpc-xxxxxxx \
    --subnet-id sbn-xxxxxxx \
    --region bd \
    --ak    ALTAK******** \
    --sk    ******************************
EOF
}

# ---------------- 参数解析 ----------------
NAME="" ; VPC_ID="" ; SUBNET_ID="" ; REGION=""
AK="${BCE_AK:-}" ; SK="${BCE_SK:-}"
PROTOCOL="http"
EXPIRES=1800
POLL_INTERVAL=3
POLL_TIMEOUT=120
DRY_RUN=0

while [[ $# -gt 0 ]]; do
  case "$1" in
    --name)          NAME="$2";          shift 2;;
    --vpc-id)        VPC_ID="$2";        shift 2;;
    --subnet-id)     SUBNET_ID="$2";     shift 2;;
    --region)        REGION="$2";        shift 2;;
    --ak)            AK="$2";            shift 2;;
    --sk)            SK="$2";            shift 2;;
    --protocol)      PROTOCOL="$2";      shift 2;;
    --expires)       EXPIRES="$2";       shift 2;;
    --poll-interval) POLL_INTERVAL="$2"; shift 2;;
    --poll-timeout)  POLL_TIMEOUT="$2";  shift 2;;
    --dry-run)       DRY_RUN=1;          shift 1;;
    -h|--help)       usage; exit 0;;
    *) echo "未知参数: $1" >&2; usage; exit 2;;
  esac
done

# ---------------- 参数校验 ----------------
missing=()
for v in NAME VPC_ID SUBNET_ID REGION AK SK; do
  [[ -z "${!v}" ]] && missing+=("$v")
done
if (( ${#missing[@]} > 0 )); then
  echo "缺少必填参数: ${missing[*]}" >&2
  usage; exit 2
fi

case "$REGION" in
  bj|gz|su|bd|cd) ;;
  *) echo "--region 必须是 bj|gz|su|bd|cd 之一, 实际: $REGION" >&2; exit 2;;
esac

case "$PROTOCOL" in
  http|https) ;;
  *) echo "--protocol 必须是 http|https, 实际: $PROTOCOL" >&2; exit 2;;
esac

HOST="blb.${REGION}.baidubce.com"
BASE_URL="${PROTOCOL}://${HOST}"

# ---------------- 依赖检查 ----------------
# python2.7 通用别名兜底：优先 python2.7，其次 python2，再退到 python（需自身是 2.x）
PY_BIN=""
for candidate in python2.7 python2 python; do
  if command -v "$candidate" >/dev/null 2>&1; then
    # 确认是 2.x（避免 `python` 指向 3.x）
    ver="$("$candidate" -c 'import sys;print(sys.version_info[0])' 2>/dev/null || echo 0)"
    if [[ "$ver" == "2" ]]; then
      PY_BIN="$candidate"
      break
    fi
  fi
done
if [[ -z "$PY_BIN" ]]; then
  echo "缺少依赖: python2.7 (未找到 2.x 版本的 python 解释器)" >&2
  exit 3
fi

for cmd in curl openssl; do
  command -v "$cmd" >/dev/null || { echo "缺少依赖: $cmd" >&2; exit 3; }
done

# ---------------- 工具函数 ----------------
# HMAC-SHA256 十六进制输出
# 用法: hmac_sha256_hex <key> <data>
hmac_sha256_hex() {
  printf '%s' "$2" | openssl dgst -sha256 -hmac "$1" | awk '{print $NF}'
}

# BCE 规范化 URL 编码
# 用法: url_encode <string> [encode_slash: true|false]
url_encode() {
  "$PY_BIN" - "$1" "${2:-true}" <<'PY'
# -*- coding: utf-8 -*-
from __future__ import print_function
import sys, urllib
s = sys.argv[1]
encode_slash = sys.argv[2].lower() == 'true'
# BCE unreserved chars: A-Z a-z 0-9 - _ . ~
# urllib.quote default safe='/', we explicitly pass safe set
safe = '' if encode_slash else '/'
# py2: passing unicode to urllib.quote raises UnicodeEncodeError, force utf-8 first
if isinstance(s, unicode):
    s = s.encode('utf-8')
sys.stdout.write(urllib.quote(s, safe=safe))
PY
}

# 生成 BCE V1 签名 Authorization
# 用法: bce_sign <method> <uri_path> <host>
# 输出: Authorization 头值
bce_sign() {
  local method="$1"
  local uri_path="$2"
  local host_value="$3"

  local timestamp
  timestamp="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

  # 1) signingKeyStr
  local signing_key_str="bce-auth-v1/${AK}/${timestamp}/${EXPIRES}"

  # 2) signingKey = HmacSHA256(SK, signingKeyStr)  → hex 字符串
  local signing_key_hex
  signing_key_hex="$(hmac_sha256_hex "$SK" "$signing_key_str")"

  # 3) 规范化 URI (保留斜杠)
  local canonical_uri
  canonical_uri="$(url_encode "$uri_path" false)"

  # 4) 规范化 QueryString (本脚本不使用 query 参数)
  local canonical_query=""

  # 5) 规范化 Headers (最简: 只签 host)
  local canonical_headers
  canonical_headers="$(url_encode "host" true):$(url_encode "$host_value" true)"
  local signed_headers="host"

  # 6) 拼接 canonical request 并做第二次 HMAC
  local canonical_request
  canonical_request="${method}
${canonical_uri}
${canonical_query}
${canonical_headers}"

  local signature
  signature="$(hmac_sha256_hex "$signing_key_hex" "$canonical_request")"

  echo "${signing_key_str}/${signed_headers}/${signature}"
}

# 解析 JSON 字段
# 用法: json_get <json> <key>
json_get() {
  "$PY_BIN" -c '# -*- coding: utf-8 -*-
from __future__ import print_function
import sys, json
try:
    obj = json.loads(sys.argv[1])
except Exception:
    sys.exit(0)
v = obj.get(sys.argv[2], "")
if v is None:
    v = ""
# py2: v may be unicode/str/number/bool, normalize to string output
if isinstance(v, bool):
    v = "true" if v else "false"
print(v)
' "$1" "$2"
}

# ---------------- 组装创建请求体 ----------------
BODY="$("$PY_BIN" -c '# -*- coding: utf-8 -*-
from __future__ import print_function
import json, sys
print(json.dumps({
  "name":        sys.argv[1],
  "subnetId":    sys.argv[2],
  "vpcId":       sys.argv[3],
  "allocateVip": True,
}, separators=(",", ":")))
' "$NAME" "$SUBNET_ID" "$VPC_ID")"

# ---------------- Step 1: 创建 BLB ----------------
echo "==> [1/2] 创建 BLB  region=${REGION}  host=${HOST}"
AUTH_CREATE="$(bce_sign POST "/v1/appblb" "$HOST")"

if (( DRY_RUN == 1 )); then
  echo "---- DRY RUN 打印请求 ----"
  echo "POST ${BASE_URL}/v1/appblb"
  echo "Host: ${HOST}"
  echo "Content-Type: application/json"
  echo "Authorization: ${AUTH_CREATE}"
  echo "Body: ${BODY}"
  echo "-------------------------"
  exit 0
fi

CREATE_RESP="$(curl -sS -w $'\n%{http_code}' -X POST "${BASE_URL}/v1/appblb" \
  -H "Host: ${HOST}" \
  -H "Content-Type: application/json" \
  -H "Authorization: ${AUTH_CREATE}" \
  --data "${BODY}")"
CREATE_STATUS="$(printf '%s' "$CREATE_RESP" | tail -n1)"
CREATE_BODY="$(printf '%s' "$CREATE_RESP" | sed '$d')"

if [[ "$CREATE_STATUS" != "200" ]]; then
  echo "❌ 创建 BLB 失败, HTTP ${CREATE_STATUS}"
  echo "响应体: $CREATE_BODY"
  exit 4
fi

echo "创建响应: $CREATE_BODY"

BLB_ID="$(json_get "$CREATE_BODY" "blbId")"
if [[ -z "$BLB_ID" ]]; then
  echo "❌ 未从创建响应中解析出 blbId" >&2
  exit 4
fi
echo "blbId = ${BLB_ID}"

# ---------------- Step 2: 轮询详情校验 underlayVip ----------------
echo "==> [2/2] 轮询查询 BLB 详情, 期望 status=available 且 underlayVip 非空"
DEADLINE=$(( $(date +%s) + POLL_TIMEOUT ))
attempt=0
while true; do
  attempt=$((attempt+1))
  AUTH_GET="$(bce_sign GET "/v1/appblb/${BLB_ID}" "$HOST")"

  DETAIL_RESP="$(curl -sS -w $'\n%{http_code}' -X GET "${BASE_URL}/v1/appblb/${BLB_ID}" \
    -H "Host: ${HOST}" \
    -H "Authorization: ${AUTH_GET}")"
  DETAIL_STATUS="$(printf '%s' "$DETAIL_RESP" | tail -n1)"
  DETAIL_BODY="$(printf '%s' "$DETAIL_RESP" | sed '$d')"

  # 创建后短时间内 GET 可能返回 404 ResourceNotExist, 属于最终一致性窗口, 继续等待
  if [[ "$DETAIL_STATUS" == "404" ]]; then
    echo "  [第 ${attempt} 次] 资源尚未可见 (HTTP 404 ResourceNotExist), 继续等待"
    if (( $(date +%s) >= DEADLINE )); then
      echo "❌ 轮询 ${POLL_TIMEOUT}s 超时, BLB 一直不可见" >&2
      echo "最后一次响应: $DETAIL_BODY" >&2
      exit 6
    fi
    sleep "$POLL_INTERVAL"
    continue
  fi

  if [[ "$DETAIL_STATUS" != "200" ]]; then
    echo "❌ 查询详情失败, HTTP ${DETAIL_STATUS}: $DETAIL_BODY" >&2
    exit 5
  fi

  STATUS="$(json_get "$DETAIL_BODY" "status")"
  UNDERLAY_VIP="$(json_get "$DETAIL_BODY" "underlayVip")"
  ADDRESS="$(json_get "$DETAIL_BODY" "address")"

  echo "  [第 ${attempt} 次] status=${STATUS:-<empty>}  underlayVip=${UNDERLAY_VIP:-<empty>}"

  if [[ "$STATUS" == "available" && -n "$UNDERLAY_VIP" ]]; then
    echo
    echo "✅ BLB 创建并校验通过"
    echo "  blbId       : $BLB_ID"
    echo "  address     : $ADDRESS   (overlay VIP)"
    echo "  underlayVip : $UNDERLAY_VIP"
    echo "  region      : $REGION"
    echo "详情: $DETAIL_BODY"
    exit 0
  fi

  if (( $(date +%s) >= DEADLINE )); then
    echo "❌ 轮询 ${POLL_TIMEOUT}s 超时" >&2
    echo "最后一次响应: $DETAIL_BODY" >&2
    exit 6
  fi
  sleep "$POLL_INTERVAL"
done
            

API网关

开通API网关

数据服务需通过API网关转发到胜算平台的后端服务，因此需要确保当前用户或子用户已经开通了API网关服务的权限。目前在完成实名认证后即可开通，开通 API网关。

创建API网关分组

API 网关的分组管理功能可以高效地、便捷地管理一组具有关联的 API。

操作步骤：

登录并进入 API 网关 API GW。
在左侧导航栏，单击API网关-分组管理，分组管理文档。
单击新建分组。
填写分组名称和分组描述信息，单击确认，即可完成分组创建。
在创建完API网关分组后，会默认为每个网关分组提供一个内网域名。如需使用自定义域名，可点击下方绑定域名按钮，具体操作流程见绑定自定义域名流程。

胜算平台

具备数据服务模块权限及创建权限
计算资源：数据服务测试与实际调用需使用资源数据处理实例-数据服务类型

创建数据服务

数据服务支持通过向导模式、脚本模式和注册 API三种方式创建 API。三种模式的基础配置流程一致，但数据来源和查询逻辑配置方式不同：

向导模式：通过可视化表单自动生成查询语句，适用于单表简单查询场景。
脚本模式：由用户编写 SQL 实现查询逻辑，适用于同一数据源内的多表关联、子查询和聚合统计等复杂查询场景。
注册 API：将已有的外部 API 接入数据服务统一管理。

API 基础配置流程如下：

登录百度胜算控制台，在选中的工作空间操作列单击打开按钮，进入空间内。
侧边导航依次单击数据服务>服务管理，进入数据服务页面。
单击创建按钮，在创建API对话框配置以下参数：

配置项名称	说明
API 名称	必填，长度为 1～256 个字符，不能包含 `/`、`\`、空格或冒号（`:`），不能仅输入 `.`；同一项目文件夹路径下的 API 名称不能重复。
所属位置	必填，单击浏览按钮，选择 API 所属的项目文件夹路径。从工作台创建 API 时，系统默认填充对应的项目文件夹路径。
API 分组	必填，下拉选择API网关中已存在的分组。
应用型 BLB 实例	必填，下拉选择应用型BLB实例，请选择上方通过接口创建的开通UnderlayIP的BLB实例，否则会导致调用请求失败。
API 模式	必填，支持选择向导模式、脚本模式或注册 API，默认为向导模式。API 模式创建后不可变更。向导模式：适用于单表简单查询场景，无需手写 SQL，通过可视化配置自动生成查询语句。脚本模式：适用于复杂查询场景，支持自定义编写 SQL，可实现多表关联、子查询、函数运算、聚合统计和动态条件等查询逻辑。注册 API：适用于已有外部 API 的接入和统一管理。
SQL 模式	仅脚本模式显示，支持选择基础 SQL 或高级 SQL，默认为基础 SQL。基础SQL：基础SQL指通过基础SQL语法来编写查询逻辑。暂不支持ElasticSearch数据源。高级SQL：高级SQL指通过支持Mybatis标签的SQL语法来编写查询逻辑，实现动态SQL。目前支持的标签类型包括：if，choose，when，otherwise，trim，foreach，where。暂不支持ElasticSearch数据源。
API Path	必填，用于定义 API 的访问路径，必须以 `/` 开头，例如 `/api/v1/users`。
协议	必填，支持 HTTP 和 HTTPS，默认全选。
请求方式	必填，支持 GET 和 POST，默认选择 GET。
返回类型	必填，目前仅支持 JSON。
描述	非必填，用于填写 API 的功能或用途，最多支持 500 个字符。

配置完成后，单击确认，进入对应模式的 API 开发页面。

开发服务

向导模式

选择向导模式后，开发页面包含选择表、选择参数、排序字段和返回示例定义区域。具体操作步骤如下：

在选择表区域，依次选择数据源类型、数据源、数据库和数据表。

配置项名称	说明
数据源类型	支持选择 MySQL、Oracle、SQL Server、PostgreSQL或Doris。
数据源名称	选择对应类型的数据源。
数据库名称	选择所选数据源下的数据库。
数据表名称	选择所选数据库中的数据表。

在选择参数区域，展示所选数据表的所有字段信息，勾选需要设为请求参数、返回参数以及添加到排序字段的表字段；如需分页返回，可勾选返回结果分页，默认关闭；支持通过字段名快速定位字段。

开启返回结果分页后，系统将自动添加请求参数 pageSize、pageNum 和返回参数 pageSize、pageNum、totalNum，并按页返回数据；关闭后将一次性返回全部数据，最多返回 1000 条。建议在数据量较大时开启分页，并配置排序规则以保证结果顺序稳定。

在排序字段区域，展示在选择参数区域添加的排序字段。可为排序字段设置升序或降序排序方式，并支持删除已添加的排序字段；同时支持拖拽排序，长按字段左侧的拖拽按钮可调整排序字段的先后顺序。
在右侧请求参数区域，展示在选择参数区域设为请求参数的字段，具体配置参数如下：

配置项名称	说明
参数名称	默认为绑定字段名称，可编辑。
绑定字段	绑定的数据表字段名称，仅支持查看。
参数类型	参数数据类型，可选范围：STRING、INT、LONG、FLOAT、DOUBLE、DECIMAL、BOOLEAN，默认为左侧参数选择中对应的映射而来的字段类型。
参数位置	支持选择QUERY、BODY，默认为QUERY。
操作符	查询操作符，可选范围：默认为=。 =：请求参数等于实际赋值。 LIKE：为请求参数搜索某种指定模式。 IN：为请求参数规定赋值集合。 NOT IN：请求参数不在赋值集合中。 NOT LIKE：请求参数不在该指定模式中。 !=：请求参数不等于实际赋值。＞：请求参数大于实际赋值。＜：请求参数小于实际赋值。＞=：请求参数大于或等于实际赋值。＜=：请求参数小于或等于实际赋值。
必填	是否必填，默认勾选支持取消，即设定为必传参数。
示例值	参数示例值，请输入符合参数类型的值。
默认值	参数默认值，请输入符合参数类型的值。
描述	默认为所选字段的字段描述，支持修改参数描述。

在右侧返回参数区域，展示在选择参数区域设为返回参数的字段，具体配置参数如下：

配置项名称	说明
参数名称	默认为绑定字段名称，可编辑。
绑定字段	绑定的数据表字段名称，仅支持查看。
参数类型	参数数据类型，可选范围：STRING、INT、LONG、FLOAT、DOUBLE、DECIMAL、BOOLEAN，默认为左侧参数选择中对应的映射而来的字段类型。
示例值	参数示例值，请输入符合参数类型的值。
描述	默认为所选字段的字段描述，支持修改参数描述。

在返回示例定义区域，填写接口响应数据样例，支持单击从测试结果粘贴并简化快捷导入内容，可手动编辑JSON示例，展示接口调用成功后的数据结构、字段格式，作为接口调用参考依据。

脚本模式

选择脚本模式后，开发页面包含选择表、编写查询 SQL、请求参数、返回参数和返回示例定义区域。脚本模式支持基础 SQL和高级 SQL两种 SQL 模式：

基础 SQL：标准原生 SQL 语法，适用于固定查询场景。
高级 SQL：支持 MyBatis3 动态标签，适用于多条件、动态表、动态字段等可变查询场景。

在选择表区域依次选择数据源类型和数据源名称。

配置项名称	说明
数据源类型	支持选择 MySQL、Oracle、SQL Server、PostgreSQL或Doris。
数据源名称	选择对应类型的数据源。

在编写查询 SQL区域选择 SQL 模式并输入查询 SQL。如需分页返回，可勾选返回结果分页，默认开启；单击格式化按钮，对SQL进行美化。以下是SQL示例：

基础SQL
1. 使用标准 SQL 语法，支持 ${参数名}、#{参数名} 动态传参。字段别名自动映射为返回参数名称。示例如下：
SQL
```
1SELECT name, addr AS address, SUM(num) AS total_num
2FROM database1.table1
3WHERE user_id = ${uid}
4GROUP BY name, addr
```
1. 编写 SQL 时请注意：
  - SELECT 字段将解析为返回参数，字段别名将作为返回参数名称；
  - 在 WHERE 条件中使用 ${参数名} 或 #{参数名} 定义请求参数，例如 ${uid} 或 #{uid}；
  - 仅支持单条 SELECT 语句，不支持 SELECT * 和写操作；
  - 支持单表查询、多表关联、嵌套查询和跨库查询；跨库查询时需携带数据库名称；
  - SQL 编写完成后，请配置请求参数和返回参数，以便 API 调用者正确传参与解析结果。
高级SQL
1. 使用支持MyBatis 3标签的SQL语法，支持以下标签：if、choose、when、otherwise、where、trim、foreach。以下示例通过条件控制查询不同的数据表，var为请求参数，col01为返回参数。
SQL
```
1select col01
2from
3<choose>
4    <when test='var == 1'>
5        table_name01
6    </when>
7    <when test='var == 2'>
8        table_name02
9    </when>
10</choose>;
```
1. 编写 SQL 时请注意：
  - 仅支持单条SELECT语句，不支持SELECT*及写操作；
  - 支持单表/多表/嵌套及跨库查询（需带库名）；
  - 编写好SQL之后，请对参数信息进行设置，以方便API调用者；
  - 支持使用 ${参数名} 或#{参数名} 定义请求参数（如 ${uid}、#{uid}），MyBatis标签中的特殊字符需进行转义。

开启返回结果分页后，系统将自动添加请求参数 pageSize、pageNum 和返回参数 pageSize、pageNum、totalNum，并按页返回数据；关闭后将一次性返回全部数据，最多返回 1000 条。建议在数据量较大时开启分页，并配置排序规则以保证结果顺序稳定。

在右侧请求参数区域，可通过单击自动解析按钮来自动解析相关参数，也支持手动添加和校正参数，具体配置参数如下：

配置项名称	说明
参数名称	默认为解析出来的字段名称，可编辑。
参数类型	参数数据类型，可选范围：STRING、INT、LONG、FLOAT、DOUBLE、DECIMAL、BOOLEAN，自动解析出来的字段默认为STRING类型。高级SQL模式下额外支持类型如下：ARRAY_STRING、ARRAY_INT、ARRAY_LONG、ARRAY_FLOAT、ARRAY_DOUBLE、ARRAY_DECIMAL、ARRAY_BOOLEAN。
参数位置	支持选择QUERY、BODY，默认为QUERY。
必填	是否必填。
示例值	参数示例值，请输入符合参数类型的值。
默认值	参数默认值，请输入符合参数类型的值。
描述	参数描述，支持文本输入任意内容。
操作	删除：单击删除该行参数。

返回参数

在右侧返回参数区域，可通过单击自动解析按钮来自动解析相关参数，也支持手动添加和校正参数，具体配置参数如下：

配置项名称	说明
参数名称	默认为解析出来的字段名称，可编辑。
参数类型	参数数据类型，可选范围：STRING、INT、LONG、FLOAT、DOUBLE、DECIMAL、BOOLEAN，自动解析出来的字段默认为STRING类型，你可调整参数类型，但若返回参数类型与实际数据类型不匹配时，可能导致精度丢失或转换失败，建议调整为STRING类型。
示例值	参数示例值，请输入符合参数类型的值。
描述	参数描述，支持文本输入任意内容。
操作	删除：单击删除该行参数。

在返回示例定义区域，填写接口响应数据样例。支持单击从测试结果粘贴并简化按钮快捷导入内容，也可手动编辑 JSON 示例，用于展示接口调用成功后的数据结构和字段格式。

注册 API

选择注册 API后，数据服务不直接生成查询 SQL，而是将已有外部 API 接入平台统一管理。开发页面包含后端服务定义、用户请求参数定义、后端请求参数定义、后端常量参数、返回参数定义、返回示例定义和错误码定义区域。具体操作步骤如下：

在后端服务定义区域，依次选择后台服务Host、后端服务Path、请求方式和后端超时。

配置项	说明
后端服务 Host	必填。输入后端服务域名或 IP，必须以 `http://` 或 `https://` 开头，且不能包含 Path。
后端服务 Path	必填。以 `/` 开头。支持使用方括号定义路径参数，例如 `/getTaskInfo/[taskId]`。
请求方式	必填。支持 GET 和 POST。
超时时间	必填，单位为 ms，默认 30000，取值范围为 10～360000。

注意：如果后端 Path 中定义了路径参数，必须在后端请求参数区域定义对应参数。例如 Path 为 /task_[taskId] 时，需要定义 taskId 参数。

在用户请求参数区域单击添加参数，定义对外暴露给 API 调用方的参数。

配置项	说明
参数名称	API 请求参数的字段名称，名称不可重复。
参数类型	选择参数数据类型，例如字符串、数字、布尔、数组、对象等。
参数位置	指定参数传递位置：请求头（Header）、查询参数（Query）、请求体（Body）。
必填	标识该参数是否为必传参数，可选：是 / 否。
示例值	参数填写参考样例，用于帮助用户快速理解格式要求。
默认值	调用接口未传入该参数时使用的默认取值，无默认值可留空。
描述	参数含义、业务作用、填写约束、特殊规则说明。
操作	支持对参数条目执行删除操作。

在后端请求参数区域单击添加参数，定义实际传递给后端 API 的参数，并将其绑定到用户请求参数。

配置项	说明
后端参数名称	后端接口接收的参数字段名。
后端参数位置	指定后端参数接收位置，可选：请求头（Header）、路径（Path）、查询参数（Query）、请求体（Body）。
对应用户请求参数名称	绑定前端用户传入的请求参数名称，实现参数映射。
描述	当前参数的业务作用、约束说明。
操作	支持对参数条目执行删除操作。

如果后端 API 需要接收调用方不可见的固定值，在后端常量参数区域单击添加参数，填写参数名称、参数值、参数位置和参数类型。

参数配置项	可选范围或规则
参数名称	支持英文、数字、下划线和中划线，必须以字母开头，长度为 1～128 个字符，名称不能重复。
参数类型	STRING、INT、LONG、FLOAT、DOUBLE、BOOLEAN。
参数值	参数的默认值。
参数位置	指定后端参数接收位置，可选：QUERY、HEAD，默认为 QUERY。
描述	当前参数的业务作用。
操作	支持对参数条目执行删除操作。

后端请求参数名称与后端常量参数名称整体不能重复；后端 Path 中的路径参数必须与后端请求参数定义对应。

在返回参数定义区域单击添加参数，定义返回数据的参数名称、类型、示例值和描述。

配置项	说明
参数名称	支持英文、数字、下划线和中划线，必须以字母开头，长度为 1～128 个字符，名称不能重复。
参数类型	STRING、INT、LONG、FLOAT、DOUBLE、BOOLEAN。
示例值	参数示例值。
描述	当前参数的业务作用。
操作	支持对参数条目执行删除操作。

在返回示例定义区域填写接口响应数据样例，支持单击从测试结果粘贴并简化快捷导入内容，可手动编辑JSON示例，展示接口调用成功后的数据结构、字段格式，作为接口调用参考依据。
在错误码定义区域单击添加，填写后端错误码、错误信息和说明。

配置项	说明
错误码	错误标识编码，列表内不可重复。
错误信息	返回给调用方的简短错误提示文本。
说明	描述错误触发场景、业务含义及相关注意事项。
操作	支持对参数条目执行删除操作。

说明：

注册 API 的返回参数配置用于说明返回数据结构，实际返回内容仍由后端 API 返回。

注册 API 发布后，平台会将其纳入数据服务统一管理，并通过平台 API 地址对外提供调用入口。外部调用方不应直接绕过平台调用后端地址。

保存API

完成服务开发和调用设置后，单击右上角的保存。API 保存成功后方可进行在线测试。

测试API

API 开发完成后，可通过在线测试验证查询逻辑和返回结果是否符合预期：

单击右侧的测试，进入测试界面。
根据已配置的请求参数填写参数值。
单击运行，查看返回结果和执行日志。
测试通过后，可在返回示例定义区域单击从测试结果粘贴并简化，将简化后的测试结果填充为返回示例。

发布API

API 测试无误后，可将其发布至线上环境供外部调用。单击右上角的发布，在发布 API 对话框中修改版本号或填写版本描述，然后单击确认发布。

发布后可在API网关页面查看到对应的API。

基本配置

打开 API 配置页面，单击右侧导航栏中的属性，可查看或修改 API 的基本信息：

配置项	说明
API 名称	展示当前 API 名称，支持修改。
所属位置	展示当前 API 所属的工作台项目位置。
API 分组	展示当前API的分组。
应用型 BLB 实例	展示当前API的BLB实例，您可对其进行相应的修改。
API 模式	展示当前 API 模式。
SQL 模式	脚本模式下展示当前 API 的 SQL 模式。
API Path	展示 API 访问路径，支持修改。
协议	展示 API 请求协议，支持修改。
请求方式	展示 API 请求方式，支持修改。
返回类型	展示 API 返回类型，支持修改。
描述	展示 API 描述，支持修改。
API ID	展示 API 的唯一 ID。
创建人	展示 API 创建人。
创建时间	展示 API 创建时间。
修改人	展示 API 最近一次修改人。
修改时间	展示 API 最近一次修改时间。

历史版本

在右侧历史版本区域查看按月份分组的已发布版本。
单击目标版本后的查看，进入版本详情页面。
如需恢复历史版本，单击恢复到此版本，然后在确认对话框中单击确认恢复。系统将使用该版本内容覆盖当前草稿。

评价此篇文章

有帮助没帮助

概览

服务运维

百度胜算