OmniHSS API 参考

API 概述

基础 URL

https://[hostname]:8443/api

请求格式

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

响应格式

所有响应均为 JSON，具有以下结构：

成功响应:

{
  "data": { ... }
}

错误响应:

{
  "error": "错误消息描述"
}

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 分配给 APNs

示例请求:

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 - 更新分配给 APNs 的静态 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 关联的 MSISDNs（同一物理设备/SIM）

用例:

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

多 IMSI 考虑:

在多 MSISDN 场景中使用 CLR 时：

多个 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

请求体:

{
  "epc_profile": {
    "name": "标准数据计划",
    "ue_ambr_dl_kbps": 100000,
    "ue_ambr_ul_kbps": 50000,
    "network_access_mode": 0,
    "tracking_area_update_interval_seconds": 54
  }
}

字段:

字段	描述	单位	典型值
`name`	配置文件名称	文本	唯一标识符
`ue_ambr_dl_kbps`	下载带宽限制	Kbps	10000-1000000
`ue_ambr_ul_kbps`	上传带宽限制	Kbps	5000-500000
`network_access_mode`	访问类型	枚举	0=仅数据，2=数据+保留
`tracking_area_update_interval_seconds`	TAU 定时器	秒	54（典型）

示例请求:

curl -k -X POST https://hss.example.com:8443/api/epc/profile \
  -H "Content-Type: application/json" \
  -d '{
    "epc_profile": {
      "name": "优质 100Mbps",
      "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

请求体:

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

另见:

配置文件文档 - IFC 模板详细信息和示例
协议流程 - IMS 注册和通话流程

APN 配置文件

APN（接入点名称��配置文件由三个组件组成，这些组件共同工作：

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

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

列出 APN 标识符

端点: GET /api/apn/identifier

创建 APN 标识符

端点: POST /api/apn/identifier

请求体:

{
  "apn_identifier": {
    "apn": "internet",
    "ip_version": 2
  }
}

IP 版本值:

0 - 仅 IPv4
1 - 仅 IPv6
2 - IPv4v6（双栈）
3 - IPv4 或 IPv6（网络选择）

列出 APN QoS 配置文件

端点: GET /api/apn/qos_profile

创建 APN QoS 配置文件

端点: POST /api/apn/qos_profile

请求体:

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

列出 APN 配置文件

端点: GET /api/apn/profile

创建 APN 配置文件

端点: POST /api/apn/profile

请求体:

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

必填字段:

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（不同 APNs）:

用户可以拥有多个静态 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]
    }
  }"

验证规则:

✓ 允许: 针对不同 APNs 的多个静态 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 必须唯一。例如，用户不能同时为 internet 分配静态 IP 100.64.1.1 和 100.64.1.2"
    ]
  }
}

另见:

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

漫游管理

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

列出漫游配置文件

端点: GET /api/roaming/profile

创建漫游配置文件

端点: POST /api/roaming/profile

请求体:

{
  "roaming_profile": {
    "name": "仅限美国运营商",
    "data_action_if_no_rules_match": 1,
    "ims_action_if_no_rules_match": 1
  }
}

操作值:

0 - 允许
1 - 拒绝

默认操作:

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": 0,
    "ims_action": 0
  }
}

字段:

mcc - 移动国家代码（3 位数��）
mnc - 移动网络代码（2-3 位数字）
data_action - 允许 (0) 或拒绝 (1) 数据服务
ims_action - 允许 (0) 或拒绝 (1) IMS/语音服务

另见:

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

EIR 管理

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

有关设备身份检查、S13 接口流程和 IMEI 验证的详细信息，请参见 EIR 文档。

列出 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 规则

附加文档