Sh 接口（用户数据检索）

📖 返回主文档

Sh 接口通过 Diameter 提供对 HSS/Repository 中用户资料数据的访问。

什么是 Sh 接口？

Sh 接口是 3GPP 标准化的 Diameter 接口，位于 TAS 和 HSS/Repository（Repo）之间。它提供实时访问：

IMS 用户身份（IMPI/IMPU）
呼叫转移设置（MMTel-Config）
用户服务授权
S-CSCF 分配

Sh 查找何时发生

Sh 查找发生在：

MT 呼叫： 查找被叫方（目标用户）
MO 呼叫： 查找主叫方（源用户）
紧急呼叫： 查找主叫方（用于位置/身份）

在每种情况下，TAS 每个呼叫分支发出一个 UDR。MO 和 MT 使用相同的多数据引用 UDR 形状 — 只有指标标签不同。

多数据引用 UDR（Notif-Eff）

根据 3GPP TS 29.328 §6.1.1.1，当 AS 和 HSS 都支持 Notif-Eff 功能（通过 Supported-Features AVP 协商），一个 UDR 可以携带多个 Data-Reference AVP，HSS 响应一个 UDA，其 User-Data-Sh 是一个单一的 <Sh-Data> 文档，将每个引用子树作为兄弟节点连接在一起。TAS 依赖于此 — 每个 Sh 查找在一次往返中获取系统知道如何处理的所有引用的完整集合。

请求的数据引用（TS 29.328 表 7.6.1）

Ref	元素	TAS 用于填充
0	RepositoryData（`Service-Indication = "MMTEL-Services"`）	`call_forward_all_destination`，`call_forward_not_reachable_destination`，`no_reply_timer`
10	IMSPublicIdentity	`ims_public_identity`，`msisdn`
11	IMSUserState	`ims_user_state`（来自 TS 29.328 §7.6.3 的原始枚举值）
12	SCSCFName	`scscf_address`，`scscf_domain`
13	InitialFilterCriteria	（返回给 TAS 的主体，但当前未作为拨号计划变量显示）
14	LocationInformation	`location_rat_type`，`location_mme_name`，`location_vplmn_id`，`location_age_seconds`
15	UserState	`user_state`（来自 TS 29.328 §7.6.7 的原始枚举值）
17	MSISDN	（与 IMPU 交叉检查）
32	IMSI	`imsi`
33	IMSPrivateUserIdentity	`ims_private_identity`，`ims_domain`（从后缀解析）

所有单字符串字段都作为原始字符串变量显示到拨号计划中 — TAS 不解释它们的值。请参见下面的 从 Sh 数据设置的拨号计划变量 表以获取完整列表。

示例 UDA 主体（已清理）

在实时跟踪中成功合并的响应如下 — 每个引用子树在请求的顺序下出现在一个 <Sh-Data> 包装器中：

[debug] 为 +614xxxxxxxx 获取了呼叫者数据
        (Data-Ref [0, 10, 11, 12, 13, 14, 15, 17, 32, 33],
         SI="MMTEL-Services"): 4453 字节

<?xml version="1.0" encoding="UTF-8"?>
<Sh-Data>
  <RepositoryData></RepositoryData>
  <PublicIdentifiers>
    <IMSPublicIdentity>sip:+614xxxxxxxx@ims.mnc001.mcc999.3gppnetwork.org</IMSPublicIdentity>
    <IMSPublicIdentity>tel:+614xxxxxxxx</IMSPublicIdentity>
  </PublicIdentifiers>
  <ShIMSData>
    <IMSUserState>1</IMSUserState>
  </ShIMSData>
  <ShIMSData>
    <SCSCFName>sip:scscf01.ims.mnc001.mcc999.3gppnetwork.org:5060</SCSCFName>
  </ShIMSData>
  <IMSSubscription>
    <PrivateID>9999990000xxxxx@ims.mnc001.mcc999.3gppnetwork.org</PrivateID>
    <ServiceProfile>
      ... InitialFilterCriteria 条目 ...
    </ServiceProfile>
  </IMSSubscription>
  <ShIMSData>
    <LocationInformation>
      <RAT-Type>eutran</RAT-Type>
      <MMEName>mme01.epc.mnc001.mcc999.3gppnetwork.org</MMEName>
      <VPLMNId>999001</VPLMNId>
      <AgeOfLocationInformation>NNNN</AgeOfLocationInformation>
    </LocationInformation>
  </ShIMSData>
  <IMSPrivateUserIdentity>9999990000xxxxx@ims.mnc001.mcc999.3gppnetwork.org</IMSPrivateUserIdentity>
</Sh-Data>

解析器如何处理合并的主体

TAS 不遍历 XML 树。每个引用解析器是独立的并且是 基于标签 的：它在合并的主体中搜索特定的元素名称（例如 <SCSCFName>、<IMSPublicIdentity>、<CallForwardUnconditional>、 <CallForwardNoReplyTimer>，not-reachable 的 cp:rule 块）并仅提取它关心的值。解析器不识别的子树将被静默忽略。

每个解析器的结果是一个部分用户数据映射；部分映射按顺序与默认映射合并。这使得查找对异构 HSS 实现和部分响应具有鲁棒性 — 请参见下面的 优雅降级 部分。

从 Sh 接口检索的数据

TAS 每个呼叫分支发出一个多数据引用 UDR（请参见多数据引用 UDR（Notif-Eff）上面的请求形状和合并响应）。TAS 从合并的 <Sh-Data> 主体提取的字段分为三组：

1. IMS 身份：

IMPI（私有身份）： 从 <IMSPrivateUserIdentity> 元素解析。格式：{IMSI}@{IMS-domain}。TAS 在 @ 上拆分以独立恢复 IMSI 和 IMS 域。
IMPU（公共身份）： 从 <IMSPublicIdentity> 元素解析。格式：sip:+{MSISDN}@{IMS-domain}。MSISDN 去掉前导 + 并作为 msisdn 拨号计划变量显示。

2. S-CSCF 分配：

当前用户注册的 S-CSCF 服务器名称和域，从 <SCSCFName> 元素解析（数据引用 12）。MT 拨号计划使用该信息将 INVITE 直接路由到注册的 S-CSCF，而不是扩展到 IMS 领域。
注意�� TS 29.328 附录 D 中的规范 XML 元素名称为 SCSCFName （没有连字符）。连字符形式的 "S-CSCF" 仅出现在规范文本中。

3. MMTel 服务（多媒体电话配置）：

在 <RepositoryData> 中返回，以 Service-Indication = "MMTEL-Services" 为键。
用户特定的呼叫转移规则：
- 呼叫转移全部（CFA）： 无条件转移到另一个号码
- 呼叫转移忙（CFB）： 当用户忙时转移
- 呼叫转移无应答（CFNRy）： 超时后转移（定时器值从 <CallForwardNoReplyTimer> 中提取）
- 呼叫转移不可达（CFNRc）： 当用户离线/未注册时转移（从 MMTel-Services 存储文档中的 not-reachable <cp:rule> 中提取）

什么是 MMTel-Config？

MMTel-Config 是用户的多媒体电话服务配置作为透明（存储）数据存储在 HSS 中，以 Service-Indication = "MMTEL-Services" 为键。它作为与身份查找相同的多数据引用 UDR 的一部分获取（数据引用 0 加上服务指示 AVP）。该文档遵循 OMA / 3GPP simservs XCAP 架构，通常包含一个 complete-communication-diversion 块以及一个或多个 cp:rule 条目（busy、noanswer、unregistered、 notreachable）、一个可选的 <NoReplyTimer> 值，以及其他 MMTel 子服务，如通信限制和身份呈现。

TAS 识别的常见 MMTel 服务：

CDIV（通信转移）： 呼叫转移规则 — 当前唯一解析为拨号计划变量的块。notreachable 规则填充 call_forward_not_reachable_destination 和 <NoReplyTimer> 填充 no_reply_timer。
OIP（主叫身份呈现）： 主叫 ID 呈现规则（返回在主体中但当前未被使用）。
TIP（终止身份呈现）： 被叫方号码规则（返回在主体中但当前未被使用）。

从 Sh 数据设置的拨号计划变量

在成功的 Sh 查找后，这些变量被填充：

变量	来源	示例值	描述
`ims_private_identity`	IMPI	`9999990000xxxxx@ims.mnc001.mcc999.3gppnetwork.org`	用于身份验证的私有用户身份
`ims_public_identity`	IMPU	`sip:+614xxxxxxxx@ims.mnc001.mcc999.3gppnetwork.org`	用于路由的公共用户身份
`msisdn`	IMPU（解析）	`614xxxxxxxx`	用户号码（去掉 `+`）
`imsi`	IMPI（解析）	`9999990000xxxxx`	来自私有身份的 IMSI
`ims_domain`	IMPI/IMPU	`ims.mnc001.mcc999.3gppnetwork.org`	IMS 域
`scscf_address`	SCSCFName	`sip:scscf01.ims.mnc001.mcc999.3gppnetwork.org:5060` 或 `"none"`	S-CSCF 服务器地址（已��册）
`scscf_domain`	SCSCFName（解析）	`scscf01.ims.mnc001.mcc999.3gppnetwork.org` 或 `"none"`	S-CSCF 主机（已注册）
`call_forward_all_destination`	MMTel CDIV	数字或 `"none"`	CFA 目标号码
`call_forward_not_reachable_destination`	MMTel CDIV	数字或配置默认值	CFNRc 目标（语音信箱）
`no_reply_timer`	MMTel CDIV	秒数或配置默认值	CFNRy 激活前的超时
`ims_user_state`	IMSUserState（数据引用 11）	`"0"`/`"1"`/`"2"`/`"3"` 或 `"none"`	IMS 注册状态枚举。`1` = 已注册，`0` = 未注册，`2` = 身份验证待定，`3` = 注册未注册服务（TS 29.328 §7.6.3）。原始字符串，TAS 不解释。
`user_state`	UserState（数据引用 15）	原始字符串或 `"none"`	CS/PS 用户状态（TS 29.328 §7.6.7）。原始字符串，TAS 不解释。
`location_rat_type`	LocationInformation/RAT-Type	`"eutran"`、`"utran"`、`"geran"`、`"wlan"`、... 或 `"none"`	最后已知注册的无线接入技术。
`location_mme_name`	LocationInformation/MMEName	MME FQDN 或 `"none"`	为用户服务的 MME 主机。
`location_vplmn_id`	LocationInformation/VPLMNId	`MCCMNC` 数字字符串或 `"none"`	访问的 PLMN 标识符（在拨号计划中用于漫游检测）。
`location_age_seconds`	LocationInformation/AgeOfLocationInformation	数字字符串或 `"none"`	自上次向 HSS 报告位置数据以来的秒数。

优先级：Sh 数据与配置默认值

TAS 对呼叫转移数据使用以下优先级顺序：

来自 Sh 的 MMTel-Config — 最高优先级，用户特定设置。
来自 SS7 MAP 的 HLR 数据 — 在漫游或访问网络中呼叫转移处于活动状态时覆盖 Sh 的 MT 呼叫。请参见 SS7 MAP。
配置默认值 — 最低优先级，当 Sh 或 HLR 未提供值时使用（或当相应子树在 Sh 响应中缺失时 — 请参见下面的优雅降级）。默认值在 runtime.exs 中的 config :tas 下配置 — call_forward_not_reachable_destination 和 default_no_reply_timer。

当 Sh 查找失败时会发生什么

整体请求失败场景：

用户未在 HSS 中配置：
- HSS 返回 Experimental-Result-Code 5001（DIAMETER_ERROR_USER_UNKNOWN）
- TAS 将呼叫分支视为不可解析
- hangup_case 变量设置为 "UNALLOCATED_NUMBER"
- 呼叫被拒绝，返回适当的 SIP 响应
HSS 无法访问 / 超时：
- Sh 请求超时（默认：5000ms，参见 runtime.exs 中的 Diameter request_timeout）
- 记录错误并记录指标
- 呼叫分支以与情况（1）相同的方式失败
HSS 不支持多数据引用 UDR：
- HSS 要么返回错误，要么静默丢弃请求（取决于 HSS）
- 从 TAS 的角度看，这看起来像情况（1）或（2） — 查找整体失败并且呼叫分支被拒绝
- HSS 必须实现 Notif-Eff 功能，以使 TAS 正常工作。请参见 TS 29.328 §6.1.1.1 以获取功能定义。

优雅的每个子树降级

当 UDR 本身成功（Result-Code: 2001）但合并的 <Sh-Data> 主体中的单个子树缺失时，TAS 不会使呼叫失败。每个引用解析器是独立的，当其标签缺失时回退到定义的默认值。操作员只需担心整体请求失败（如上所述）；部分数据降级是自动的，并在调试日志中可观察到。

子树缺失	结果
`<SCSCFName>`（数据引用 12）	`scscf_address` 和 `scscf_domain` 设置为 `"none"`
`<IMSPrivateUserIdentity>`（数据引用 33）	`ims_private_identity`、`imsi`、`ims_domain` 设置为 `"none"`
`<CallForwardUnconditional>` 在 MMTel RepositoryData 中	`call_forward_all_destination` 设置为 `"none"`
`not-reachable`/`<cp:rule>` 块在 MMTel RepositoryData 中	`call_forward_not_reachable_destination` 回退到 `Tas.Config.call_forward_not_reachable_destination()`
`<CallForwardNoReplyTimer>` 在 MMTel RepositoryData 中	`no_reply_timer` 回退到 `Tas.Config.default_no_reply_timer()`
空的 `<RepositoryData></RepositoryData>`	所有 MMTel 派生字段回退到配置默认值
空/缺失的 `<IMSUserState>`、`<LocationInformation>`、`<InitialFilterCriteria>`	当前没有拨号计划副作用（已解析但尚未连接）

唯一硬性要求是响应必须包含一个 <IMSPublicIdentity> 元素。如果该标签缺失，查找返回 {:error, :sh_parse_failed}，呼叫分支被视为不可解析（与上述情况 1 的下游行为相同）。每个其他字段都是 "自由请求，尽量获取你能得到的"。

这使得 TAS 对异构 HSS 部署具有弹性：一个实现 Notif-Eff 但仅填充 IMSPublicIdentity、MSISDN 和 SCSCFName 的 HSS（例如）仍将产生一个有效的呼叫；拨号计划只是回退到配置默认值以获取 MMTel 派生变量。

监控 Sh 接口

关键指标：

# Sh 查找成功率
rate(subscriber_data_lookups_total{result="success"}[5m]) /
rate(subscriber_data_lookups_total[5m]) * 100

# Sh 查找延迟（P95）
histogram_quantile(0.95,
  rate(subscriber_data_duration_milliseconds_bucket[5m]))

# Sh 错误率
rate(subscriber_data_lookups_total{result="error"}[5m])

警报阈值：

P95 延迟 > 100ms：HSS 响应缓慢
错误率 > 5%：HSS 连接问题
错误率 > 20%：HSS 严重故障

故障排除：

检查 Web UI 中的 Diameter 对等体状态（/diameter）
在 Web UI 中测试 Sh 查找（/sh_test），使用已知用户
检查日志中的 "用户数据" 错误
验证 HSS/Repository 是否可以从 TAS 访问
检查 subscriber_data_lookups_total 指标以寻找模式

测试 Sh 接口

使用 Web UI Sh 测试工具（/sh_test）：

在控制面板中导航到 /sh_test
输入用户 MSISDN（例如，+614xxxxxxxx）
点击 "查询 Sh"
查看返回的数据：
- IMPI/IMPU 身份
- S-CSCF 分配
- MMTel 服务
- 呼叫转移配置

常见测试场景：

验证新配置的用户是否在 HSS 中
检查特定用户的呼叫转移设置
验证 IMS 注册后的 S-CSCF 分配
测试 HSS 连接性和响应时间

Sh 接口（用户数据检索）

相关文档

核心文档

呼叫处理集成

相关接口

监控