OmniHSS API 参考

API 概述

基本 URL

https://[hostname]:8443/api

请求格式

Content-Type: application/json
协议: 仅支持 HTTPS
端口: 8443（可配置）

重要: 所有 API 端点期望接收没有包装对象的“扁平” JSON 有效负载。

正确格式:

{
  "name": "value",
  "field": "value"
}

错误格式（请勿使用）:

{
  "subscriber": {
    "name": "value",
    "field": "value"
  }
}

示例:

# ✓ 正确
curl -X POST https://hss.example.com:8443/api/ims/profile \
  -H "Content-Type: application/json" \
  -d '{"name": "default", "ifc_template": "..."}'

# ✗ 错误
curl -X POST https://hss.example.com:8443/api/ims/profile \
  -H "Content-Type: application/json" \
  -d '{"ims_profile": {"name": "default", "ifc_template": "..."}}'

响应格式

所有响应都是 JSON，具有以下结构：

成功响应:

{
  "status": "success",
  "response": { ... }
}

错误响应:

{
  "status": "error",
  "response": {
    "invalid_fields": {
      "field_name": "error message"
    }
  }
}

HTTP 状态码

代码	含义	使用场景
200	OK	成功的 GET、PUT、DELETE
201	已创建	成功的 POST
400	错误请求	无效的输入数据
404	未找到	资源不存在
422	无法处理的实体	验证错误
500	服务器内部错误	服务器端错误

API 请求流程

用户管理

列出用户

检索所有用户或按条件过滤。

端点: GET /api/subscriber

查询参数:

参数	类型	描述
`enabled`	boolean	按启用状态过滤
`ims_enabled`	boolean	按 IMS 启用状态过滤

示例请求:

curl -k https://hss.example.com:8443/api/subscriber

示例响应:

{
  "data": [
    {
      "id": 1,
      "imsi": "001001123456789",
      "enabled": true,
      "ims_enabled": true,
      "sim_id": 1,
      "key_set_id": 1,
      "epc_profile_id": 1,
      "ims_profile_id": 1,
      "roaming_profile_id": 1,
      "custom_attributes": {},
      "inserted_at": "2025-10-15T10:30:00Z",
      "updated_at": "2025-10-15T10:30:00Z"
    }
  ]
}

根据 ID 获取用户

根据数据库 ID 检索特定用户。

端点: GET /api/subscriber/:id

路径参数:

参数	类型	描述
`id`	integer	用户数据库 ID

示例请求:

curl -k https://hss.example.com:8443/api/subscriber/1

根据 IMSI 获取用户

根据其 IMSI 检索用户。

端点: GET /api/subscriber/imsi/:imsi

路径参数:

参数	类型	描述	格式
`imsi`	string	国际移动用户身份	14-15 位数字

示例请求:

curl -k https://hss.example.com:8443/api/subscriber/imsi/001001123456789

使用场景: 根据其 IMSI 进行特定用户的故障排除。

根据 MSISDN 获取用户

根据其电话号码检索用户。

端点: GET /api/subscriber/msisdn/:msisdn

路径参数:

参数	类型	描述	格式
`msisdn`	string	移动站 ISDN 号码	1-15 位数字 (E.164)

示例请求:

curl -k https://hss.example.com:8443/api/subscriber/msisdn/14155551234

使用场景: 当您只有他们的电话号码时查找用户信息。

创建用户

配置新的用户。

端点: POST /api/subscriber

请求体:

{
  "subscriber": {
    "imsi": "001001123456789",
    "enabled": true,
    "ims_enabled": true,
    "sim_id": 1,
    "key_set_id": 1,
    "epc_profile_id": 1,
    "ims_profile_id": 1,
    "roaming_profile_id": 1,
    "custom_attributes": {
      "note": "测试用户"
    }
  }
}

必填字段:

imsi - 必须为 14-15 位数字，唯一
key_set_id - 必须引用现有的密钥集
epc_profile_id - 必须引用现有的 EPC 配置文件

可选字段:

enabled - 默认: true
ims_enabled - 默认: true
sim_id - 引用 SIM 卡
ims_profile_id - 引用 IMS 配置文件（IMS 服务所需）
roaming_profile_id - 引用漫游配置文件（漫游控制所需）
msisdns - MSISDN ID 数组（电话号码）
static_ips - 用于 APN 分配的静态 IP ID 数组
custom_attributes - 自定义键值对

另见:

完整用户配置示例 - 端到端工作流
多 MSISDN 文档 - 将电话号码分配给用户
静态 IP 管理 - 将静态 IP 分配给 APN

示例请求:

curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "imsi": "001001123456789",
      "key_set_id": 1,
      "epc_profile_id": 1
    }
  }'

配置流程:

更新用户

修改现有用户。

端点: PUT /api/subscriber/:id

路径参数:

参数	类型	描述
`id`	integer	用户数据库 ID

请求体:

{
  "subscriber": {
    "enabled": false,
    "ims_enabled": false,
    "epc_profile_id": 2,
    "custom_attributes": {
      "note": "暂时禁用"
    }
  }
}

可更新字段:

enabled - 启用/禁用所有服务
ims_enabled - 启用/禁用 IMS 服务
sim_id - 更改 SIM 卡分配
key_set_id - 更改加密密钥（小心！）
epc_profile_id - 更�� 数据服务配置文件
ims_profile_id - 更改语音服务配置文件
roaming_profile_id - 更改漫游策略
msisdns - 更新分配给用户的电话号码
static_ips - 更新分配给 APN 的静态 IP
custom_attributes - 更新自定义数据

不可更新:

imsi - 不能更改 IMSI（请删除并重新创建）

另见:

配置文件管理 - 管理服务配置文件

示例请求:

curl -k -X PUT https://hss.example.com:8443/api/subscriber/1 \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "enabled": false
    }
  }'

使用场景:

暂时禁用用户: {"enabled": false}
仅禁用语音服务: {"ims_enabled": false}
更改服务配置文件: {"epc_profile_id": 2} (见 EPC 配置文件)
更新漫游策略: {"roaming_profile_id": 3} (见漫游管理)

删除用户

从系统中移除用户。

端点: DELETE /api/subscriber/:id

路径参数:

参数	类型	描述
`id`	integer	用户数据库 ID

示例请求:

curl -k -X DELETE https://hss.example.com:8443/api/subscriber/1

警告: 这将永久删除用户及所有相关状态数据（PDN 会话、通话等）。删除后可以重用 IMSI。

注意: 删除用户不会删除相关的:

密钥集 - 可以重用于其他用户
SIM - 可以重新分配给新用户
配置文件 - 多个用户共享的资源
MSISDNs - 如果需要，必须单独删除

取消位置请求（强制分离）

发送取消位置请求（CLR）以强制分离用户与其当前注册的 MME。

端点: POST /api/subscriber/cancel_location

请求体:

{
  "imsi": "001001123456789"
}

参数:

参数	类型	必需	描述
`imsi`	string	是	要分离的用户的 IMSI（14-15 位数字）

示例请求:

curl -k -X POST https://hss.example.com:8443/api/subscriber/cancel_location \
  -H "Content-Type: application/json" \
  -d '{"imsi": "001001123456789"}'

成功响应 (200 OK):

{
  "data": {
    "message": "取消位置请求已成功发送",
    "imsi": "001001123456789",
    "destination_host": "mme01.operator.com",
    "destination_realm": "epc.operator.com"
  }
}

错误响�� (404 未找到):

{
  "error": "用户未找到或当前未在任何 MME 注册"
}

行为:

向当前注册的 MME 发送 S6a CLR (subscriber_state.last_seen_mme)
使用 Cancellation-Type: subscription_withdrawal（强制完全分离）
设置 CLR-Flags: {s6a_indicator: 1, reattach_required: 1}（UE 必须重新认证）
如果用户从未注册或 last_seen_mme 为 null，则返回 404
影响所有与 IMSI 关联的 MSISDN（相同的物理设备/SIM）

使用场景:

防止欺诈: 立即分离可疑用户
终止订阅: 当账户被禁用时强制注销
故障排除: 清除过时的 MME 注册以进行调试
迁移: 强制重新认证以应用新的配置文件设置
安全: 立即断开被攻击的用户

多 IMSI 考虑:

使用 CLR 处理多 MSISDN 场景时:

多个 MSISDN，单个 IMSI:

// 用户具有 IMSI 001001123456789 和 MSISDNs ["+1234567890", "+9876543210"]
POST /api/subscriber/cancel_location
{"imsi": "001001123456789"}

// 结果: 发送一个 CLR，两个 MSISDN 受影响（相同设备）

不同 IMSIs（不同设备）:

// 两个用户具有相同的 MSISDN 但不同的 IMSIs（号码移植场景）
// 用户 A: IMSI 001001111111111, MSISDN "+1234567890"
// 用户 B: IMSI 001001222222222, MSISDN "+1234567890"

POST /api/subscriber/cancel_location
{"imsi": "001001111111111"}

// 结果: 仅用户 A 被分离，用户 B 不受影响

重要说明:

基于 IMSI: CLR 始终按 IMSI 发送，而不是按 MSISDN
异步: CLR 是异步发送的；成功响应意味着 CLR 已发送，而不是 MME 处理了它
不验证 MME 状态: 即使 MME 无法访问，也会发送 CLR（标准 HSS 行为）
幂等: 对同一 IMSI 多次调用是安全的

相关文档:

MSISDN 管理

MSISDN（电话号码）可以分配给用户以启用语音服务。有关将多个号码分配给单个用户的详细信息，请参见多 MSISDN 文档。

列出 MSISDN

检索所有电话号码。

端点: GET /api/msisdn

示例请求:

curl -k https://hss.example.com:8443/api/msisdn

获取 MSISDN

检索特定电话号码。

端点: GET /api/msisdn/:id

示例请求:

curl -k https://hss.example.com:8443/api/msisdn/1

创建 MSISDN

创建一个新的电话号码。

端点: POST /api/msisdn

请求体:

{
  "msisdn": {
    "msisdn": "14155551234"
  }
}

验证:

必须为 1-15 位数字
必须唯一
必须遵循 E.164 格式（国际格式，不带 + 符号）

示例请求:

curl -k -X POST https://hss.example.com:8443/api/msisdn \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": {
      "msisdn": "14155551234"
    }
  }'

将 MSISDN 分配给用户

要将电话号码分配给用户，您需要创建一个连接记录。这通常通过用户更新端点或直接数据库操作完成。

多 MSISDN 模式:

请参见多 MSISDN 和多 IMSI 特性以获取详细用法。

删除 MSISDN

移除一个电话号码。

端点: DELETE /api/msisdn/:id

示例请求:

curl -k -X DELETE https://hss.example.com:8443/api/msisdn/1

SIM 管理

SIM 卡记录存储物理 SIM 卡信息，包括 ICCID、供应商详细信息、PIN/PUK 代码和 OTA 密钥。SIM 记录可以选择性地链接到用户。

另见:

多 IMSI 文档 - 在一个物理 SIM 上的多个用户

列出 SIM

检索所有 SIM 卡。

端点: GET /api/sim

示例请求:

curl -k https://hss.example.com:8443/api/sim

获取 SIM

检索特定 SIM 卡。

端点: GET /api/sim/:id

示例请求:

curl -k https://hss.example.com:8443/api/sim/1

创建 SIM

创建一个新的 SIM 卡记录。

端点: POST /api/sim

请求体:

{
  "sim": {
    "iccid": "8991101200003204510",
    "sim_vendor": "Gemalto",
    "batch_name": "2025-Q1-Batch-01",
    "is_esim": false,
    "pin1": "1234",
    "pin2": "5678",
    "puk1": "12345678",
    "puk2": "87654321",
    "adm1": "admin-code-1",
    "kic": "0123456789ABCDEF0123456789ABCDEF",
    "kid": "FEDCBA9876543210FEDCBA9876543210"
  }
}

必填字段:

iccid - 19-20 位数字，唯一

可选但重要的字段:

sim_vendor - 制造商名称
batch_name - 用于跟踪
is_esim - eSIM 的布尔标志
pin1, pin2 - 最终用户 PIN 代码
puk1, puk2 - PIN 解锁代码
adm1-adm10 - 管理代码
kic, kid - OTA 安全密钥（十六进制字符串）

示例请求:

curl -k -X POST https://hss.example.com:8443/api/sim \
  -H "Content-Type: application/json" \
  -d '{
    "sim": {
      "iccid": "8991101200003204510",
      "sim_vendor": "Gemalto"
    }
  }'

更新 SIM

修改 SIM 卡数据。

端点: PUT /api/sim/:id

示例请求:

curl -k -X PUT https://hss.example.com:8443/api/sim/1 \
  -H "Content-Type: application/json" \
  -d '{
    "sim": {
      "batch_name": "更新的批次名称"
    }
  }'

删除 SIM

移除一个 SIM 卡记录。

端点: DELETE /api/sim/:id

警告: 确保在删除之前没有用户引用此 SIM。

密钥集管理

密钥集包含用于通过 Milenage 算法进行用户身份验证的加密材料（Ki、OPC/OP、AMF、SQN）。每个用户必须引用一个密钥集。

另见:

协议流程 - 使用密钥集的身份验证程序

列出密钥集

检索所有加密密钥集。

端点: GET /api/key_set

示例请求:

curl -k https://hss.example.com:8443/api/key_set

获取密钥集

检索特定密钥集。

端点: GET /api/key_set/:id

示例请求:

curl -k https://hss.example.com:8443/api/key_set/1

响应示例:

{
  "data": {
    "id": 1,
    "ki": "0123456789ABCDEF0123456789ABCDEF",
    "opc": "FEDCBA9876543210FEDCBA9876543210",
    "op": null,
    "amf": "8000",
    "sqn": 0,
    "authentication_algorithm": "milenage",
    "ota_counter": 0
  }
}

创建密钥集

创建一个新的加密密钥集。

端点: POST /api/key_set

请求体:

{
  "key_set": {
    "ki": "0123456789ABCDEF0123456789ABCDEF",
    "opc": "FEDCBA9876543210FEDCBA9876543210",
    "amf": "8000",
    "sqn": 0,
    "authentication_algorithm": "milenage"
  }
}

必填字段:

ki - 128 位密钥（32 个十六进制字符）
opc 或 op（OPC 可以从 OP 派生）
authentication_algorithm - 当前仅支持 "milenage"

可选字段:

amf - 默认: "8000"
sqn - 默认: 0
ota_counter - 默认: 0

密钥格式:

所有密钥都是十六进制字符串
Ki、OPC、OP: 32 个十六进制字符（128 位）
AMF: 4 个十六进制字符（16 位）

示例请求:

curl -k -X POST https://hss.example.com:8443/api/key_set \
  -H "Content-Type: application/json" \
  -d '{
    "key_set": {
      "ki": "0123456789ABCDEF0123456789ABCDEF",
      "opc": "FEDCBA9876543210FEDCBA9876543210",
      "authentication_algorithm": "milenage"
    }
  }'

安全警告: 密钥集包含高度敏感的加密材料。相应地保护 API 访问。

更新密钥集

修改现有的密钥集。

端点: PUT /api/key_set/:id

警告: 更改活动用户的密钥将导致身份验证失败。仅在维护窗口或为新用户更新密钥。

影响: 更新会立即影响所有使用此密钥集的用户。活动用户将在下次连接尝试时身份验证失败。

删除密钥集

移除一个密钥集。

端点: DELETE /api/key_set/:id

警告: 确保在删除之前没有用户引用此密钥集。首先查询用户以检查引用。

配置文件管理

EPC 配置文件

EPC（演进分组核心）配置文件定义用户的数据服务参数。这些配置文件在创建用户时被引用。

列出 EPC 配置文件

端点: GET /api/epc/profile

获取 EPC 配置文件

端点: GET /api/epc/profile/:id

创建 EPC 配置文件

端点: POST /api/epc/profile

请求体:

{
  "apn_profiles": [],
  "name": "标准数据计划",
  "network_access_mode": "仅数据包",
  "tracking_area_update_interval_seconds": 600,
  "ue_ambr_dl_kbps": 100000,
  "ue_ambr_ul_kbps": 50000
}

字段:

字段	描述	单位	典型值
`name`	配置文件名称	文本	唯一标识符
`ue_ambr_dl_kbps`	下载带宽限制	Kbps	10000-1000000
`ue_ambr_ul_kbps`	上传带宽限制	Kbps	5000-500000
`network_access_mode`	访问类型	字符串	"仅数据包" 或 "数据包和电路"
`tracking_area_update_interval_seconds`	TAU 定时器	秒	600（典型）
`apn_profiles`	APN 配置文件 ID 列表	数组	[] 或 [1, 2, 3]

示例请求:

curl -k -X POST https://hss.example.com:8443/api/epc/profile \
  -H "Content-Type: application/json" \
  -d '{
    "apn_profiles": [],
    "name": "高级 100Mbps",
    "network_access_mode": "仅数据包",
    "tracking_area_update_interval_seconds": 600,
    "ue_ambr_dl_kbps": 100000,
    "ue_ambr_ul_kbps": 50000
  }'

另见:

配置文件文档 - 详细的配置文件配置指南
完整用户配置 - 在配置中使用 EPC 配置文件

更新 EPC 配置文件

端��: PUT /api/epc/profile/:id

注意: 对 EPC 配置文件的更改会影响所有使用此配置文件的用户。活动会话可能需要重新建立。

删除 EPC 配置文件

端点: DELETE /api/epc/profile/:id

警告: 确保在删除之前没有用户引用此配置文件。

IMS 配置文件

IMS（IP 多媒体子系统）配置文件定义语音服务参数和用户的初始过滤标准（IFC）。在创建启用 IMS 服务的用户时引用这些配置文件。

列出 IMS 配置文件

端点: GET /api/ims/profile

创建 IMS 配置文件

端点: POST /api/ims/profile

请求体:

{
  "name": "标准 VoLTE",
  "ifc_template": "<IMS-XML-模板-在这里>"
}

必填字段:

name - 配置文件名称（必须唯一）
ifc_template - 包含 Liquid 模板变量的 IFC（初始过滤标准）XML 模板

IFC 模板变量:

IFC 模板支持以下 Liquid 模板变量，这些变量会动态替换：

变量	描述	示例值
`{{ imsi }}`	用户 IMSI	`001001123456789`
`{{ msisdns }}`	MSISDN 数组（用于循环）	`["14155551234", "14155555678"]`
`{{ mcc }}`	移动国家代码	`001`
`{{ mnc }}`	移动网络代码	`001`

模板渲染工作原理:

IFC 模板作为 Liquid 模板（类似于 Jinja2）存储，并在 IMS 操作期间动态渲染：

存储: 创建 IMS 配置文件时，模板按原样存储，包含变量如 {{ imsi }} 和 {% for msisdn in msisdns %}
验证: API 通过使用测试数据渲染模板来验证其有效性，以确保有效的 XML 语法
运行时渲染: 当用户执行 IMS 注册（MAA/SAA）时，HSS：
- 检索用户的 IMS 配置文件
- 使用用户的实际数据渲染模板：
  - {{ imsi }} → 用户的 IMSI
  - {{ msisdns }} → 用户的电话号码
  - {{ mcc }} → 配置的移动国家代码
  - {{ mnc }} → 配置的移动网络代码
- 通过 Cx/Diameter 将渲染的 XML 返回给 S-CSCF

模板语法:

<!-- 简单变量替换 -->
{{ imsi }}

<!-- 对数组的循环 -->
{% for msisdn in msisdns %}
  <MSISDN>{{ msisdn }}</MSISDN>
{% endfor %}

<!-- 组合变量 -->
{{ imsi }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org

IFC 模板示例:

<?xml version="1.0" encoding="UTF-8"?>
<IMSSubscription>
<PrivateID>{{ imsi }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</PrivateID>
<ServiceProfile>
{% for msisdn in msisdns %}
<PublicIdentity>
<Identity>sip:{{ msisdn }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</Identity>
<Extension>
<IdentityType>0</IdentityType>
</Extension>
</PublicIdentity>
<PublicIdentity>
<Identity>tel:{{ msisdn }}</Identity>
<Extension>
<IdentityType>0</IdentityType>
</Extension>
</PublicIdentity>
{% endfor %}
<InitialFilterCriteria>
<Priority>10</Priority>
<TriggerPoint>
<ConditionTypeCNF>0</ConditionTypeCNF>
<SPT>
<ConditionNegated>0</ConditionNegated>
<Group>0</Group>
<Method>REGISTER</Method>
</SPT>
</TriggerPoint>
<ApplicationServer>
<ServerName>sip:as.ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</ServerName>
<DefaultHandling>0</DefaultHandling>
</ApplicationServer>
</InitialFilterCriteria>
</ServiceProfile>
</IMSSubscription>

示例请求 (curl):

curl -k -X POST https://hss.example.com:8443/api/ims/profile \
  -H "Content-Type: application/json" \
  -d '{
    "name": "default",
    "ifc_template": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><IMSSubscription><ServiceProfile>...</ServiceProfile></IMSSubscription>"
  }'

示例请求 (Python):

import requests

response = requests.post(
    "https://hss.example.com:8443/api/ims/profile",
    json={
        "name": "default",
        "ifc_template": ifc_template_string
    },
    verify=False  # 对于自签名证书
)

成功响应 (201 已创建):

{
  "status": "success",
  "response": {
    "id": 1,
    "name": "default",
    "ifc_template": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
  }
}

验证:

API 验证 IFC 模板是否为有效的 XML
模板变量使用测试数据渲染以验证语法
name 字段必须唯一且非空

另见:

配置文件文档 - IFC 模板详细信息和示例
协议流程 - IMS 注册和呼叫流程
默认 IFC 模板 - 参考实现

APN 配置文件

APN（接入点名称）配置文件由三个组件组成，它们共同工作：

APN 标识符 - 定义 APN 名称和 IP 版本
APN QoS 配置文件 - 定义服务质量参数
APN 配置文件 - 组合标识符和 QoS，链接到 EPC 配置文件

请参见 PCRF 文档以获取详细的策略配置、QoS 管理和自动重新认证。 另见配置文件文档以获取 APN 配置示例。

列出 APN 标识符

端点: GET /api/apn/identifier

创建 APN 标识符

端点: POST /api/apn/identifier

请求体:

{
  "apn": "internet",
  "ip_version": "ipv4v6"
}

IP 版本值:

"ipv4" - 仅 IPv4
"ipv6" - 仅 IPv6
"ipv4v6" - IPv4v6（双栈）
"ipv4_or_ipv6" - IPv4 或 IPv6（网络选择）

列出 APN QoS 配置文件

端点: GET /api/apn/qos_profile

创建 APN QoS 配置文件

端点: POST /api/apn/qos_profile

请求体:

{
  "name": "最佳努力互联网",
  "allocation_retention_priority": 8,
  "apn_ambr_dl_kbps": 50000,
  "apn_ambr_ul_kbps": 25000,
  "pre_emption_capability": false,
  "pre_emption_vulnerability": true,
  "qci": 9
}

列出 APN 配置文件

端点: GET /api/apn/profile

创建 APN 配置文件

端点: POST /api/apn/profile

请求体:

{
  "apn_identifier_id": 1,
  "apn_qos_profile_id": 1,
  "name": "互联网 APN"
}

必填字段:

apn_identifier_id - 必须引用现有的 APN 标识符
apn_qos_profile_id - 必须引用现有的 APN QoS 配置文件

另见:

完整用户配置 - 包括 APN 设置的完整示例
EPC 配置文件 - APN 配置文件链接到 EPC 配置文件

静态 IP 管理

静态 IP 地址可以分配给特定 APN，以便单个用户在连接到特定 APN 时接收预定的 IPv4 和/或 IPv6 地址，而不是从 DHCP 池中接收动态地址。

架构:

用户连接时的数据流:

更新位置应答 - APN 配置数据映射:

此图显示 S6a 更新位置应答 APN-配置 AVP 中每个字段的确切来源：

关键观察:

上下文标识符: 每个 APN 在配置文件中的顺序索引（0, 1, 2...）
服务选择: 直接来自 apn_identifier.apn（例如，“internet”、“ims”）
PDN 类型: 从 apn_identifier.ip_version 编码（ipv4=0，ipv6=1，ipv4v6=2，ipv4_or_ipv6=3）
QoS 参数: 所有来自 apn_qos_profile 表
AMBR 带宽: 值乘以 1000（kbps → bps 转换）
服务方 IP 地址: 仅在此用户+APN 组合存在静态 IP 时包含
- 查找过程: subscriber.static_ips → 按 apn_profile_id 过滤 → 提取 IP
- 检查 IP 版本兼容性与 apn_identifier.ip_version
VPLMN-动态地址-允许: 硬编码为 0（不允许）- 强制使用静态 IP（如果提供）

关系层次结构:

关键概念:

每 APN 分配: 每个静态 IP 链接到特定的 APN 配置文件
每用户每 APN 仅一个 IP: 用户每个 APN 只能有一个静态 IP 分配
IPv4 和 IPv6 支持: 静态 IP 可以是仅 IPv4、仅 IPv6 或双栈
全局 IP 唯一性: 每个 IP 地址必须在所有静态 IP 记录中全局唯一
- 相同的 IPv4 或 IPv6 地址不能分配给多个用户（即使在不同 APN 上）
- 这防止了路由冲突和 IP 地址歧义
- 通过在 ipv4_static_ip 和 ipv6_static_ip 字段上强制唯一索引来执行
多对多关系: 用户和静态 IP 通过连接表链接

使用场景:

IoT 设备的固定 IP 地址
移动设备上的服务器托管（需要静态 IP 以进行入站连接）
需要特定 IP 地址的遗留应用程序
基于源 IP 的网络策略路由
需要 IP 地址跟踪的合规性

列出静态 IP

检索所有静态 IP 分配。

端点: GET /api/epc/static_ip

示例请求:

curl -k https://hss.example.com:8443/api/epc/static_ip

示例响应:

{
  "data": [
    {
      "id": 1,
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1",
      "ipv6_static_ip": "2606:4700:4700::1111",
      "apn_profile": {
        "id": 5,
        "name": "互联网 APN",
        "apn_identifier": {
          "apn": "internet",
          "ip_version": "ipv4v6"
        }
      },
      "inserted_at": "2025-11-15T10:30:00Z",
      "updated_at": "2025-11-15T10:30:00Z"
    }
  ]
}

获取静态 IP

检索特定静态 IP 分配。

端点: GET /api/epc/static_ip/:id

路径参数:

参数	类型	描述
`id`	integer	静态 IP 数据库 ID

示例请求:

curl -k https://hss.example.com:8443/api/epc/static_ip/1

创建静态 IP

为 APN 创建一个新的静态 IP 分配。

端点: POST /api/epc/static_ip

请求体:

{
  "static_ip": {
    "apn_profile_id": 5,
    "ipv4_static_ip": "100.64.1.1",
    "ipv6_static_ip": "2606:4700:4700::1111"
  }
}

必填字段:

apn_profile_id - 必须引用现有的 APN 配置文件
至少必须指定 ipv4_static_ip 或 ipv6_static_ip

可选字段:

ipv4_static_ip - IPv4 地址（点分十进制表示法）
ipv6_static_ip - IPv6 地址（标准表示法）

IP 格式验证:

IPv4: 标准点分十进制格式（例如，100.64.1.1）
IPv6: 标准冒号分��的十六进制格式（例如，2606:4700:4700::1111）
IPv4 和 IPv6 地址必须在所有静态 IP 记录中 全局唯一
- 这防止网络中的 IP 地址冲突
- 相同的 IP 不能分配给多个用户，即使在不同 APN 上
- 这是通过唯一索引在数据库级别强制执行的

配置选项:

配置	IPv4	IPv6	示例
仅 IPv4	✓	-	`{"ipv4_static_ip": "100.64.1.1"}`
仅 IPv6	-	✓	`{"ipv6_static_ip": "2606:4700:4700::1111"}`
双栈	✓	✓	同时指定两个字段

示例请求:

仅 IPv4 静态 IP:

curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1"
    }
  }'

仅 IPv6 静态 IP:

curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 6,
      "ipv6_static_ip": "2606:4700:4700::1111"
    }
  }'

双栈静态 IP:

curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1",
      "ipv6_static_ip": "2606:4700:4700::1111"
    }
  }'

成功响应 (201 已创建):

{
  "data": {
    "id": 1,
    "apn_profile_id": 5,
    "ipv4_static_ip": "100.64.1.1",
    "ipv6_static_ip": "2606:4700:4700::1111",
    "inserted_at": "2025-11-15T10:30:00Z",
    "updated_at": "2025-11-15T10:30:00Z"
  }
}

另见:

将静态 IP 分配给用户 - 如何将其链接到用户
APN 配置文件 - 管理 APN 配置

更新静态 IP

修改现有的静态 IP 分配。

端点: PUT /api/epc/static_ip/:id

路径参数:

参数	类型	描述
`id`	integer	静态 IP 数据库 ID

请求体:

{
  "static_ip": {
    "ipv4_static_ip": "100.64.1.2",
    "ipv6_static_ip": "2606:4700:4700::1112"
  }
}

可更新字段:

ipv4_static_ip - 更改 IPv4 地址
ipv6_static_ip - 更改 IPv6 地址
apn_profile_id - 更改 APN 分配

不可更新:

id - 主键（只读）

警告: 更改活动用户的 IP 地址将影响他们的下一个 PDN 连接。活动 PDN 会话将继续使用旧 IP，直到他们断开并重新连接。

示例请求:

curl -k -X PUT https://hss.example.com:8443/api/epc/static_ip/1 \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "ipv4_static_ip": "100.64.1.2"
    }
  }'

删除静态 IP

移除静态 IP 分配。

端点: DELETE /api/epc/static_ip/:id

路径参数:

参数	类型	描述
`id`	integer	静态 IP 数据库 ID

示例请求:

curl -k -X DELETE https://hss.example.com:8443/api/epc/static_ip/1

行为:

移除静态 IP 分配
不影响 APN 配置文件（APN 仍可用于其他用户）
使用此静态 IP 的用户将在下次连接时接收动态 IP
删除后，IP 地址可供重用

警告: 如果用户正在使用此静态 IP，删除它将导致他们在下一个 PDN 连接时接收动态 IP。确保用户离线或在删除之前发送取消位置请求。

将静态 IP 分配给用户

要将静态 IP 分配给用户，您需要在创建或更新时将静态 IP 记录与用户关联。

分配模式:

创建静态 IP（见创建静态 IP）
使用 static_ips 字段分配给用户

创建带有静态 IP 的用户:

# 第 1 步: 为 "internet" APN 创建静态 IP
STATIC_IP_ID=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1",
      "ipv6_static_ip": "2606:4700:4700::1111"
    }
  }' | jq -r '.data.id')

# 第 2 步: 创建分配了静态 IP 的用户
curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d "{
    \"subscriber\": {
      \"imsi\": \"001001123456789\",
      \"key_set_id\": 1,
      \"epc_profile_id\": 1,
      \"static_ips\": [$STATIC_IP_ID]
    }
  }"

更新现有用户以包含静态 IP:

curl -k -X PUT https://hss.example.com:8443/api/subscriber/1 \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "static_ips": [1, 2]
    }
  }'

多个静态 IP（不同 APN）:

用户可以拥有多个静态 IP，只要每个 IP 是针对不同的 APN：

# 为 "internet" APN 创建静态 IP
INTERNET_IP=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1"
    }
  }' | jq -r '.data.id')

# 为 "ims" APN 创建静态 IP
IMS_IP=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 6,
      "ipv4_static_ip": "100.64.2.1"
    }
  }' | jq -r '.data.id')

# 将两个 IP 分配给用户
curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d "{
    \"subscriber\": {
      \"imsi\": \"001001123456789\",
      \"key_set_id\": 1,
      \"epc_profile_id\": 1,
      \"static_ips\": [$INTERNET_IP, $IMS_IP]
    }
  }"

验证规则:

✓ 允许: 针对不同 APN 的多个静态 IP
✗ 拒绝: 针对同一 APN 的多个静态 IP

错误示例 - 重复 APN:

# 如果两个静态 IP 都引用相同的 APN，这将失败
curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "imsi": "001001123456789",
      "static_ips": [1, 2]
    }
  }'

# 错误响应:
{
  "errors": {
    "static_ips": [
      "每个用户每个 APN 的静态 IP 必须唯一。例如，用户不能同时被分配静态 IP 100.64.1.1 用于 internet 和 100.64.1.2 用于 internet"
    ]
  }
}

另见:

创建用户 - 用户配置
更新用户 - 修改用户配置
完整静态 IP 配置示例 - 端到端工作流

漫游管理

漫游配置文件控制用户是否可以在访问网络上访问数据和 IMS 服务。配置文件分配给用户，并由 MCC/MNC 匹配的规则组成。

列出漫游配置文件

端点: GET /api/roaming/profile

创建漫游配置文件

端点: POST /api/roaming/profile

请求体:

{
  "roaming_profile": {
    "name": "仅美国运营商",
    "data_action_if_no_rules_match": "deny",
    "ims_action_if_no_rules_match": "deny",
    "roaming_rules": []
  }
}

操作值:

"allow" - 允许
"deny" - 拒绝

默认操作:

data_action_if_no_rules_match - 当没有漫游规则匹配时的操作
ims_action_if_no_rules_match - IMS 特定的默认操作

列出漫游规则

端点: GET /api/roaming/rule

创建漫游规则

端点: POST /api/roaming/rule

请求体:

{
  "roaming_rule": {
    "name": "允许 AT&T",
    "mcc": "310",
    "mnc": "410",
    "data_action": "allow",
    "ims_action": "allow"
  }
}

字段:

mcc - 移动国家代码（3 位数字）
mnc - 移动网络代码（2-3 位数字）
data_action - "allow" 或 "deny" 数据服务
ims_action - "allow" 或 "deny" IMS/语音服务

另见:

漫游文档 - 详细配置和示例
协议流程 - 漫游控制在 Diameter 流中的工作原理

EIR 管理

OmniHSS 通过 S13 Diameter 接口作为设备身份注册（EIR）功能。EIR 规则根据 IMEI 模式控制设备访问。

请参见 EIR 文档以获取详细的设备身份检查、S13 接口流程和 IMEI 验证。

列出 EIR 规则

端点: GET /api/eir/rule

创建 EIR 规则

端点: POST /api/eir/rule

请求体:

{
  "eir_rule": {
    "name": "阻止 iPhone 6",
    "imei_regex": "^35[0-9]{6}0[0-9]{7}$",
    "action": 1
  }
}

字段:

name - 规则的描述性名称
imei_regex - 匹配 IMEI 号码的正则表达式
action - 白名单（0）、黑名单（1）或灰名单（2）

操作值:

0 - 白名单（允许）
1 - 黑名单（拒绝）
2 - 灰名单（允许但跟踪）

使用场景:

阻止被盗设备（黑名单特定 IMEI）
��制设备类型（按 TAC 模式黑名单）
仅允许批准的设备（使用拒绝所有的白名单模式）

另见:

协议流程 - S13 接口和 EIR 检查流程
架构概述 - OmniHSS EIR 功能

其他文档

有关更多信息，请参见以下文档：

状态和健康 - API 健康检查端点
错误处理 - 常见错误和故障排除
API 使用示例 - 完整的配置工作流

← 返回操作指南 | 下一步: 控制面板 →

目录​

API 概述​

基本 URL​

请求格式​

响应格式​

HTTP 状态码​

API 请求流程​

用户管理​

列出用户​

根据 ID 获取用户​

根据 IMSI 获取用户​

根据 MSISDN 获取用户​

创建用户​

更新用户​

删除用户​

取消位置请求（强制分离）​

MSISDN 管理​

列出 MSISDN​

获取 MSISDN​

创建 MSISDN​

将 MSISDN 分配给用户​

删除 MSISDN​

SIM 管理​

列出 SIM​

获取 SIM​

创建 SIM​

更新 SIM​

删除 SIM​

密钥集管理​

列出密钥集​

获取密钥集​

创建密钥集​

更新密钥集​

删除密钥集​

配置文件管理​

EPC 配置文件​

列出 EPC 配置文件​

获取 EPC 配置文件​

创建 EPC 配置文件​

更新 EPC 配置文件​

删除 EPC 配置文件​

IMS 配置文件​

列出 IMS 配置文件​

创建 IMS 配置文件​

APN 配置文件​

列出 APN 标识符​

创建 APN 标识符​

列出 APN QoS 配置文件​

创建 APN QoS 配置文件​

列出 APN 配置文件​

创建 APN 配置文件​

静态 IP 管理​

列出静态 IP​

获取静态 IP​

创建静态 IP​

更新静态 IP​

删除静态 IP​

将静态 IP 分配给用户​

漫游管理​

列出漫游配置文件​

创建漫游配置文件​

列出漫游规则​

创建漫游规则​

EIR 管理​

列出 EIR 规则​

创建 EIR 规则​

其他文档​

目录

API 概述

基本 URL

请求格式

响应格式

HTTP 状态码

API 请求流程

用户管理

列出用户

根据 ID 获取用户

根据 IMSI 获取用户

根据 MSISDN 获取用户

创建用户

更新用户

删除用户

取消位置请求（强制分离）

MSISDN 管理

列出 MSISDN

获取 MSISDN

创建 MSISDN

将 MSISDN 分配给用户

删除 MSISDN

SIM 管理

列出 SIM

获取 SIM

创建 SIM

更新 SIM

删除 SIM

密钥集管理

列出密钥集

获取密钥集

创建密钥集

更新密钥集

删除密钥集

配置文件管理

EPC 配置文件

列出 EPC 配置文件

获取 EPC 配置文件

创建 EPC 配置文件

更新 EPC 配置文件

删除 EPC 配置文件

IMS 配置文件

列出 IMS 配置文件

创建 IMS 配置文件

APN 配置文件

列出 APN 标识符

创建 APN 标识符

列出 APN QoS 配置文件

创建 APN QoS 配置文件

列出 APN 配置文件

创建 APN 配置文件

静态 IP 管理

列出静态 IP

获取静态 IP

创建静态 IP

更新静态 IP

删除静态 IP

将静态 IP 分配给用户

漫游管理

列出漫游配置文件

创建漫游配置文件

列出漫游规则

创建漫游规则

EIR 管理

列出 EIR 规则

创建 EIR 规则

其他文档