Pular para o conteúdo principal

Interface Sh (Recuperação de Dados do Assinante)

📖 Voltar à Documentação Principal

A interface Sh fornece acesso aos dados do perfil do assinante do HSS/Repository via Diameter.

Documentação Relacionada​

Documentação Principal​

Integração de Processamento de Chamadas​

Interfaces Relacionadas​

Monitoramento​

Interface Sh (Recuperação de Dados do Assinante)​

A interface Sh é usada para recuperar dados do perfil do assinante do HSS/Repository antes do processamento de chamadas. Esses dados incluem identidades de assinantes, serviços e configuração MMTel.

O que é a Interface Sh?​

A interface Sh é uma interface Diameter padronizada pela 3GPP entre o TAS e o HSS/Repository (Repo). Ela fornece acesso em tempo real a:

  • Identidades de assinantes IMS (IMPI/IMPU)
  • Configurações de encaminhamento de chamadas (MMTel-Config)
  • Autorização de serviços do assinante
  • Atribuição de S-CSCF

Quando Ocorrências de Consulta Sh Acontecem​

Consultas Sh Acontecem Em:

  • Chamadas MT: Consulta parte chamada (assinante de destino)
  • Chamadas MO: Consulta parte chamadora (assinante de origem)
  • Chamadas de Emergência: Consulta parte chamadora (para localização/identidade)

Em todos os casos, o TAS emite exatamente uma UDR por perna de chamada. Tanto MO quanto MT usam a mesma forma de UDR multi-Data-Reference — apenas os rótulos das métricas diferem.

Multi-Data-Reference UDR (Notif-Eff)​

De acordo com 3GPP TS 29.328 §6.1.1.1, quando tanto o AS quanto o HSS suportam o Notif-Eff recurso (negociado via o AVP Supported-Features), uma única UDR pode carregar múltiplos AVPs Data-Reference e o HSS responde com uma UDA cujo User-Data-Sh é um único documento <Sh-Data> concatenando as subárvores por referência como irmãs. O TAS depende disso — cada consulta Sh busca o conjunto completo de referências que o sistema sabe como consumir em uma viagem de ida e volta.

Referências de Dados solicitadas (TS 29.328 Tabela 7.6.1)​

RefElementoUsado pelo TAS para preencher
0RepositoryData (com Service-Indication = "MMTEL-Services")call_forward_all_destination, call_forward_not_reachable_destination, no_reply_timer
10IMSPublicIdentityims_public_identity, msisdn
11IMSUserStateims_user_state (valor enum bruto da TS 29.328 §7.6.3)
12SCSCFNamescscf_address, scscf_domain
13InitialFilterCriteria(corpo retornado ao TAS, mas não atualmente exposto como uma variável de dialplan)
14LocationInformationlocation_rat_type, location_mme_name, location_vplmn_id, location_age_seconds
15UserStateuser_state (valor enum bruto da TS 29.328 §7.6.7)
17MSISDN(verificado contra IMPU)
32IMSIimsi
33IMSPrivateUserIdentityims_private_identity, ims_domain (analisado a partir do sufixo)

Todos os campos de string única são expostos ao dialplan como variáveis de string bruta — o TAS não interpreta seus valores. Veja a tabela Variáveis de Dialplan Definidas a partir de Dados Sh abaixo para a lista completa.

Exemplo de corpo UDA (sanitizado)​

Uma resposta mesclada bem-sucedida no rastreamento ao vivo se parece com isso — as subárvores por referência aparecem sob um único wrapper <Sh-Data> na ordem em que as referências foram solicitadas:

[debug] Dados do chamador buscados para +614xxxxxxxx
        (Data-Ref [0, 10, 11, 12, 13, 14, 15, 17, 32, 33],
         SI="MMTEL-Services"): 4453 bytes

<?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>
      ... Entradas de 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>

Como os parsers consomem o corpo mesclado​

O TAS não percorre a árvore XML. Cada parser por referência é independente e baseado em tags: ele busca o corpo mesclado por um nome de elemento específico (ex.: <SCSCFName>, <IMSPublicIdentity>, <CallForwardUnconditional>, <CallForwardNoReplyTimer>, o bloco cp:rule not-reachable) e extrai apenas o valor que lhe interessa. Subárvores que o parser não reconhece são ignoradas silenciosamente.

O resultado de cada parser é um mapa de dados do assinante parcial; os parciais são mesclados em ordem sobre um mapa de padrões. Isso torna a consulta robusta para implementações heterogêneas do HSS e respostas parciais — veja a seção degradação graciosa abaixo.

Dados Recuperados da Interface Sh​

O TAS emite uma única UDR multi-Data-Reference por perna de chamada (veja Multi-Data-Reference UDR (Notif-Eff) acima para a forma de solicitação e a resposta mesclada). Os campos que o TAS extrai do corpo mesclado <Sh-Data> se dividem em três grupos:

1. Identidades IMS:

  • IMPI (Identidade Privada): analisada a partir do elemento <IMSPrivateUserIdentity>. Formato: {IMSI}@{domínio-IMS}. O TAS divide em @ para recuperar o IMSI e o domínio IMS de forma independente.
  • IMPU (Identidade Pública): analisada a partir do elemento <IMSPublicIdentity>. Formato: sip:+{MSISDN}@{domínio-IMS}. O MSISDN é despojado do + inicial e exposto como a variável de dialplan msisdn.

2. Atribuição de S-CSCF:

  • Nome do servidor S-CSCF e domínio onde o assinante está atualmente registrado, analisado a partir do elemento <SCSCFName> (Data-Reference 12). Usado pelo MT dialplan para direcionar o INVITE diretamente para o S-CSCF registrado em vez de se espalhar pelo domínio IMS.
  • Nota: o nome do elemento XML canônico na TS 29.328 Anexo D é SCSCFName (sem hífen). A forma com hífen "S-CSCF" aparece apenas na prosa da especificação.

3. Serviços MMTel (Configuração de Telefonia Multimídia):

  • Retornados dentro de <RepositoryData> com chave Service-Indication = "MMTEL-Services".
  • Regras de encaminhamento de chamadas específicas do assinante:
    • Encaminhamento de Chamadas Todas (CFA): Encaminhamento incondicional para outro número
    • Encaminhamento de Chamadas Ocupado (CFB): Encaminhar quando o assinante está ocupado
    • Encaminhamento de Chamadas Sem Resposta (CFNRy): Encaminhar após o tempo limite (valor do temporizador extraído de <CallForwardNoReplyTimer>)
    • Encaminhamento de Chamadas Não Acessíveis (CFNRc): Encaminhar quando o assinante está offline/não registrado (extraído do bloco not-reachable <cp:rule> dentro do documento do repositório MMTel-Services)

O que é MMTel-Config?​

MMTel-Config é a configuração do serviço de Telefonia Multimídia do assinante armazenada como dados transparentes (repositório) no HSS, com chave Service-Indication = "MMTEL-Services". É buscado como parte da mesma UDR multi-Data-Reference que a consulta de identidade (Data-Reference 0 mais o AVP de indicação de serviço). O documento segue o esquema OMA / 3GPP simservs XCAP e normalmente contém um bloco complete-communication-diversion com uma ou mais entradas cp:rule (busy, noanswer, unregistered, notreachable), um valor opcional <NoReplyTimer>, e outros sub-serviços MMTel como Proibição de Comunicação e Apresentação de Identidade.

Serviços MMTel Comuns que o TAS reconhece:

  • CDIV (Desvio de Comunicação): Regras de encaminhamento de chamadas — o único bloco atualmente analisado de ponta a ponta em variáveis de dialplan. A regra notreachable preenche call_forward_not_reachable_destination e <NoReplyTimer> preenche no_reply_timer.
  • OIP (Apresentação de Identidade de Origem): Regras de apresentação de ID do chamador (retornadas no corpo, mas não atualmente consumidas).
  • TIP (Apresentação de Identidade de Destino): Regras de número da parte chamada (retornadas no corpo, mas não atualmente consumidas).

Variáveis de Dialplan Definidas a partir de Dados Sh​

Após uma consulta Sh bem-sucedida, essas variáveis são preenchidas:

VariávelFonteValor de ExemploDescrição
ims_private_identityIMPI9999990000xxxxx@ims.mnc001.mcc999.3gppnetwork.orgIdentidade de usuário privada para autenticação
ims_public_identityIMPUsip:+614xxxxxxxx@ims.mnc001.mcc999.3gppnetwork.orgIdentidade de usuário pública para roteamento
msisdnIMPU (analisado)614xxxxxxxxNúmero do assinante (+ removido)
imsiIMPI (analisado)9999990000xxxxxIMSI da identidade privada
ims_domainIMPI/IMPUims.mnc001.mcc999.3gppnetwork.orgDomínio IMS
scscf_addressSCSCFNamesip:scscf01.ims.mnc001.mcc999.3gppnetwork.org:5060 ou "none"Endereço do servidor S-CSCF (registrado)
scscf_domainSCSCFName (analisado)scscf01.ims.mnc001.mcc999.3gppnetwork.org ou "none"Host S-CSCF (registrado)
call_forward_all_destinationMMTel CDIVnumérico ou "none"Número de destino CFA
call_forward_not_reachable_destinationMMTel CDIVnumérico ou padrão de configuraçãoDestino CFNRc (caixa de correio)
no_reply_timerMMTel CDIVsegundos, ou padrão de configuraçãoTempo limite antes da ativação do CFNRy
ims_user_stateIMSUserState (Data-Ref 11)"0"/"1"/"2"/"3" ou "none"Enumeração do estado de registro IMS. 1 = REGISTRADO, 0 = NÃO_REGISTRADO, 2 = AUTENTICAÇÃO_PENDENTE, 3 = REGISTRADO_SERVIÇOS_NÃO_REGISTRADOS (TS 29.328 §7.6.3). String bruta, o TAS não interpreta.
user_stateUserState (Data-Ref 15)string bruta ou "none"Estado do usuário CS/PS (TS 29.328 §7.6.7). String bruta, o TAS não interpreta.
location_rat_typeLocationInformation/RAT-Type"eutran", "utran", "geran", "wlan", ... ou "none"Tecnologia de acesso rádio do último registro conhecido.
location_mme_nameLocationInformation/MMENameFQDN do MME ou "none"Host MME atendendo o assinante.
location_vplmn_idLocationInformation/VPLMNIdstring de dígitos MCCMNC ou "none"Identificador PLMN visitado (útil para detecção de roaming no dialplan).
location_age_secondsLocationInformation/AgeOfLocationInformationstring numérica ou "none"Segundos desde que as informações de localização foram relatadas pela última vez ao HSS.

Prioridade: Dados Sh vs Padrões de Configuração​

O TAS usa esta ordem de prioridade para dados de encaminhamento de chamadas:

  1. MMTel-Config do Sh — maior prioridade, configurações específicas do assinante.
  2. Dados HLR do SS7 MAP — substitui o Sh para chamadas MT se roaming ou encaminhamento de chamadas estiver ativo na rede visitada. Veja SS7 MAP.
  3. Padrões de Configuração — menor prioridade, usados quando nem o Sh nem o HLR fornecem um valor (ou quando a subárvore correspondente estava ausente da resposta Sh — veja a degradação graciosa abaixo). Os padrões são configurados em runtime.exs sob config :tas — call_forward_not_reachable_destination e default_no_reply_timer.

O que Acontece Quando a Consulta Sh Falha​

Cenários de falha de solicitação inteira:

  1. Assinante Não Provisionado no HSS:

    • O HSS retorna Experimental-Result-Code 5001 (DIAMETER_ERROR_USER_UNKNOWN)
    • O TAS trata a perna da chamada como não resolvível
    • Variável hangup_case definida como "UNALLOCATED_NUMBER"
    • Chamada rejeitada com a resposta SIP apropriada

  2. HSS Inacessível / Tempo Limite:

    • A solicitação Sh expira (padrão: 5000ms, veja request_timeout do Diameter em runtime.exs)
    • Erro registrado e métrica registrada
    • A perna da chamada falha da mesma forma que o caso (1)

  3. HSS não suporta UDRs multi-Data-Reference:

    • O HSS retorna um erro ou descarta a solicitação silenciosamente (dependente do HSS)
    • Do lado do TAS, isso se parece com o caso (1) ou (2) — a consulta falha completamente e a perna da chamada é rejeitada
    • O HSS deve implementar o recurso Notif-Eff para que o TAS funcione. Veja TS 29.328 §6.1.1.1 para a definição do recurso.

Degradação graciosa por subárvore​

Quando a UDR em si é bem-sucedida (Result-Code: 2001), mas subárvores individuais do corpo mesclado <Sh-Data> estão ausentes, o TAS não falha a chamada. Cada parser por referência é independente e recorre a um padrão definido quando sua tag está ausente. Os operadores só precisam se preocupar com falhas de solicitação inteira (acima); a degradação de dados parciais é automática e observável nos logs de depuração.

Subárvore ausenteResultado
<SCSCFName> (Data-Ref 12)scscf_address e scscf_domain definidos como "none"
<IMSPrivateUserIdentity> (Data-Ref 33)ims_private_identity, imsi, ims_domain definidos como "none"
<CallForwardUnconditional> dentro de RepositoryData do MMTelcall_forward_all_destination definido como "none"
bloco not-reachable/<cp:rule> dentro de RepositoryData do MMTelcall_forward_not_reachable_destination recorre a Tas.Config.call_forward_not_reachable_destination()
<CallForwardNoReplyTimer> dentro de RepositoryData do MMTelno_reply_timer recorre a Tas.Config.default_no_reply_timer()
<RepositoryData></RepositoryData> vazioTodos os campos derivados de MMTel recorrem a padrões de configuração
<IMSUserState>, <LocationInformation>, <InitialFilterCriteria> vazios/ausentesAtualmente sem efeito colateral no dialplan (analisado, mas ainda não conectado)

A única exigência rígida é que a resposta contenha um elemento <IMSPublicIdentity>. Se essa tag estiver ausente, a consulta retorna {:error, :sh_parse_failed} e a perna da chamada é tratada como não resolvível (comportamento a jusante igual ao caso 1 acima). Todos os outros campos são "pergunte livremente, leve o que puder obter".

Isso torna o TAS resiliente a implantações heterogêneas do HSS: um HSS que implementa Notif-Eff, mas apenas preenche IMSPublicIdentity, MSISDN e SCSCFName (por exemplo), ainda produzirá uma chamada funcional; o dialplan apenas recorre a padrões de configuração para as variáveis derivadas de MMTel.

Monitoramento da Interface Sh​

Métricas Chave:

# Taxa de sucesso da consulta Sh
rate(subscriber_data_lookups_total{result="success"}[5m]) /
rate(subscriber_data_lookups_total[5m]) * 100

# Latência da consulta Sh (P95)
histogram_quantile(0.95,
  rate(subscriber_data_duration_milliseconds_bucket[5m]))

# Taxa de erro da consulta Sh
rate(subscriber_data_lookups_total{result="error"}[5m])

Limiares de Alerta:

  • Latência P95 > 100ms: Respostas lentas do HSS
  • Taxa de erro > 5%: Problemas de conectividade com o HSS
  • Taxa de erro > 20%: Falha crítica do HSS

Solução de Problemas:

  1. Verifique o status do par Diameter na interface Web (/diameter)
  2. Teste a consulta Sh na interface Web (/sh_test) com assinante conhecido
  3. Revise os logs em busca de erros "Dados do Assinante"
  4. Verifique se o HSS/Repository é acessível a partir do TAS
  5. Verifique a métrica subscriber_data_lookups_total em busca de padrões

Testando a Interface Sh​

Use a ferramenta de Teste Sh da interface Web (/sh_test):

  1. Navegue até /sh_test no Painel de Controle
  2. Insira o MSISDN do assinante (ex.: +614xxxxxxxx)
  3. Clique em "Consultar Sh"
  4. Revise os dados retornados:
    • Identidades IMPI/IMPU
    • Atribuição de S-CSCF
    • Serviços MMTel
    • Configuração de encaminhamento de chamadas

Cenários de Teste Comuns:

  • Verifique se assinantes recém-provisionados estão no HSS
  • Verifique as configurações de encaminhamento de chamadas para um assinante específico
  • Valide a atribuição de S-CSCF após o registro IMS
  • Teste a conectividade e os tempos de resposta do HSS