Pular para o conteúdo principal

Guia de Configuração do Cliente MAP

← Voltar para a Documentação Principal

Este guia cobre como operar o OmniSS7 como um Cliente MAP. Neste papel, o OmniSS7 se conecta a uma rede SS7 como um Processo de Servidor de Aplicação (ASP). Ele emite operações MAP (Mobile Application Part) em direção a HLRs, MSC/VLRs, SGSNs, GMLCs e outros elementos da rede central. O comportamento do protocolo segue 3GPP TS 29.002.

Interface Web do Cliente MAP

Índice​

  1. O que é o Modo Cliente MAP?
  2. Habilitando o Modo Cliente MAP
  3. Referência de Operações MAP
  4. Exemplos Comuns de Operações
  5. Enviando Solicitações via API
  6. Métricas e Monitoramento
  7. Solução de Problemas

O que é o Modo Cliente MAP?​

Modo Cliente MAP permite que o OmniSS7 se conecte como um Processo de Servidor de Aplicação (ASP) a um par M3UA (STP ou SGP) via SCTP e troque mensagens MAP. Cada operação é exposta como um endpoint HTTP. A API codifica uma solicitação como um diálogo TCAP/MAP e a transporta via SCCP e M3UA para a rede SS7. O OmniSS7 então decodifica a resposta da rede e a retorna de forma síncrona para o chamador.

Usos típicos incluem:

  • Gerenciamento de mobilidade: Atualizar Localização, Cancelar Localização, Purgar MS, Fornecer Número de Roaming
  • Tratamento de chamadas: Enviar Informações de Roteamento, Fornecer Informações do Assinante
  • SMS: SRI-for-SM, MO/MT-ForwardSM, relatório de status de entrega
  • Autenticação: Enviar Informações de Autenticação
  • Dados do assinante: Inserir/Excluir Dados do Assinante, Interrogatório a Qualquer Momento
  • Serviços suplementares: registrar/apagar/ativar/interrogar SS, gerenciamento de senhas
  • Serviços de localização (LCS) e roteamento GPRS

Arquitetura da Rede​

Habilitando o Modo Cliente MAP​

O modo Cliente MAP é configurado em config/runtime.exs. Para a referência completa de conexão M3UA, veja Parâmetros de Conexão M3UA.

config :omniss7,
  # Habilitar o modo Cliente MAP
  map_client_enabled: true,

  # Conexão M3UA para o Cliente MAP (conecta como um ASP a um STP/SGP remoto)
  map_client_m3ua: %{
    mode: "ASP",
    callback: {MapClient, :handle_payload, []},
    process_name: :map_client_asp,
    local_ip: {10, 0, 0, 100},
    local_port: 2905,
    remote_ip: {10, 0, 0, 1},
    remote_port: 2905,
    routing_context: 1
  }

Parâmetros map_client_m3ua​

ParâmetroTipoObrigatórioPadrãoDescrição
modeStringSim-Papel M3UA. "ASP" para modo cliente (conecta-se a um STP/SGP).
callbackTuplaSim-{Módulo, Função, Args} invocado para cada carga M3UA recebida. Para o Cliente MAP, isso é {MapClient, :handle_payload, []}.
process_nameÁtomoSim-Nome registrado do processo M3UA ASP.
local_ipTuplaSim-Endereço de ligação SCTP local como uma tupla IP, por exemplo, {10, 0, 0, 100}.
local_portInteiroNão2905Porta SCTP local. 2905 é a porta M3UA registrada na IANA.
remote_ipTuplaSim-Endereço IP do STP/SGP remoto como uma tupla.
remote_portInteiroNão2905Porta SCTP do STP/SGP remoto.
routing_contextInteiroNão-Valor do Contexto de Roteamento M3UA, quando o par requer um.

Chaves de nível superior: map_client_enabled (Booleano, padrão false) ativa o Cliente MAP; map_client_m3ua (Mapa) contém a conexão acima.

Você configura o endereçamento SCCP para operações de saída (Títulos Globais de Chamadas/Chamadas, SSNs, códigos de ponto) separadamente. Veja a Referência de Configuração.

Referência de Operações MAP​

Cada operação abaixo é acessível como POST /api/<endpoint>. Os opcodes são os códigos de operação MAP do 3GPP TS 29.002. As solicitações são síncronas: a API bloqueia até que a resposta SS7 chegue ou a solicitação expire (veja Códigos de Resposta).

Gerenciamento de Mobilidade​

OperaçãoEndpointOpcodeDescrição
Atualizar Localização/api/updateLocation2Registrar o VLR de atendimento de um assinante com o HLR.
Cancelar Localização/api/cancelLocation3Instruir um VLR a excluir um registro de assinante.
Fornecer Número de Roaming/api/prn4Obter um MSRN do MSC de atendimento.
Purgar MS/api/purgeMS67Marcar um assinante como purgado no HLR.
Enviar Identificação/api/sendIdentification55Recuperar dados de IMSI/autenticação do VLR anterior.
Reiniciar/api/reset37Reinicialização iniciada pelo HLR em direção a um VLR.
Restaurar Dados/api/restoreData57O VLR solicita a restauração dos dados do assinante do HLR.

Tratamento de Chamadas & Dados do Assinante​

OperaçãoEndpointOpcodeDescrição
Enviar Informações de Roteamento/api/sri22Consultar o HLR para informações de roteamento de chamadas de voz.
Fornecer Informações do Assinante/api/provideSubscriberInfo70Solicitar estado/localização do assinante ao VLR.
Excluir Dados do Assinante/api/deleteSubscriberData8Remover dados do assinante no VLR.
Interrogatório a Qualquer Momento/api/anyTimeInterrogation71gsmSCF consulta informações/localização do assinante no HLR.
Interrogatório de Assinatura a Qualquer Momento/api/anyTimeSubscriptionInterrogation62Consultar dados de assinatura no HLR.
Modificação a Qualquer Momento/api/anyTimeModification65Modificar dados de assinatura no HLR.
Notificar Dados do Assinante Modificados/api/noteSubscriberDataModified5HLR notifica o gsmSCF sobre dados alterados.
Notificar Evento MM/api/noteMM-Event89Relatar um evento de gerenciamento de mobilidade ao gsmSCF.

SMS​

OperaçãoEndpointOpcodeDescrição
Enviar Informações de Roteamento para SM/api/sri-for-sm45Consultar o HLR para o nó de atendimento para entrega de SMS.
MT-Forward SM/api/MT-forwardSM44Entregar um SM terminado em móvel ao MSC/SGSN de atendimento.
MO-Forward SM/api/forwardSM46Submeter um SM originado em móvel ao SMSC.
Enviar SM (PDU)/api/sendSM, /api/deliverPDU44Construir e entregar um PDU SMS-DELIVER.
Relatar Status de Entrega de SM/api/reportSM-DeliveryStatus47Relatar o resultado da entrega de SM ao HLR.
Pronto para SM/api/readyForSM66Notificar o HLR que um MS está acessível para SMS.
Alertar Centro de Serviço/api/alertServiceCentre64Alertar um SMSC que um assinante está disponível.

Autenticação & Equipamento​

OperaçãoEndpointOpcodeDescrição
Enviar Informações de Autenticação/api/send-auth-info56Recuperar vetores de autenticação do HLR.
Enviar IMSI/api/sendIMSI58Resolver um MSISDN para seu IMSI no HLR.
Verificar IMEI/api/checkIMEI43Consultar status do equipamento no EIR.

Serviços Suplementares​

OperaçãoEndpointOpcodeDescrição
Registrar SS/api/registerSS10Registrar um serviço suplementar (por exemplo, encaminhamento de chamadas / CFU).
Apagar SS/api/eraseSS11Apagar um serviço suplementar.
Ativar SS/api/activateSS12Ativar um serviço suplementar.
Desativar SS/api/deactivateSS13Desativar um serviço suplementar.
Interrogar SS/api/interrogateSS14Interrogar o status de um serviço suplementar.
Registrar Senha/api/registerPassword17Registrar uma senha SS.
Obter Senha/api/getPassword18Recuperar/verificar uma senha SS.
Encaminhar Verificação de Indicação de SS/api/forwardCheckSS-Indication38Verificação não confirmada em direção a um VLR.

Serviços de Localização (LCS) & GPRS​

OperaçãoEndpointOpcodeDescrição
Enviar Informações de Roteamento para LCS/api/sendRoutingInfoForLCS85GMLC consulta o HLR para roteamento LCS.
Fornecer Localização do Assinante/api/provideSubscriberLocation83Solicitar a localização de um assinante do nó de atendimento.
Relatório de Localização do Assinante/api/subscriberLocationReport86Relatar a localização de um assinante ao GMLC.
Enviar Informações de Roteamento para GPRS/api/sendRoutingInfoForGprs24Consultar o HLR para roteamento GPRS (seleção de GGSN).
Atualizar Localização GPRS/api/updateGprsLocation23Registrar o SGSN de atendimento de um assinante no HLR.

Escopo LCS: as operações de Serviços de Localização são somente de saída (solicitante). O Cliente MAP as aciona em direção a um HLR, nó de atendimento ou GMLC. O nó não atua como um servidor LCS (não responderá a um ProvideSubscriberLocation recebido ou processará um SubscriberLocationReport recebido). Os codificadores transportam os elementos de informação obrigatórios, além das opções principais mencionadas acima. O conjunto de parâmetros LCS mais amplo (QoS, prioridade, formas GAD, palavra-código, número de referência) ainda não está exposto.

CAP / CAMEL & Injeção Bruta​

OperaçãoEndpointDescrição
CAP InitialDP/api/cap/initialDPAcionar um diálogo CAMEL em direção a um gsmSCF.
CAP Connect / Continue / ReleaseCall / ApplyCharging/api/cap/connect, /api/cap/continue, /api/cap/releaseCall, /api/cap/applyChargingOperações de controle de chamada CAMEL. Veja o Guia do Gateway CAMEL.
Raw SCCP/api/raw/sccpInjetar uma carga SCCP construída manualmente (teste/diagnósticos).
Raw M3UA/api/raw/m3uaInjetar uma carga M3UA construída manualmente (teste/diagnósticos).

Exemplos Comuns de Operações​

Enviar Informações de Roteamento para SM (SRI-for-SM)​

Consulta o HLR para o nó de atendimento usado para entregar um SMS. Para como o lado do HLR processa isso, veja SRI-for-SM no Guia do HLR.

Endereçamento SCCP (caminho de entrega de SMS do SMSc). Por padrão, o SRI-for-SM é enviado roteado por GT endereçado ao MSISDN de destino (chamado SSN 6/HLR), o que requer que o STP mantenha uma entrada GTT para esse intervalo de números. Para assinantes on-net, o SMSc endereça o SRI diretamente ao HLR GT configurado. Ele então roteia no próprio endereço de par (já roteável) do HLR, de modo que nenhuma GTT por intervalo é necessária, e o HLR retorna o verdadeiro MSC de atendimento. Isso é selecionado por destino:

Configuração (:omniss7)PropósitoExemplo
hlr_gt_addressGT do HLR de origem para endereçar SRIs on-net"61455501111"
home_msisdn_prefixesPrefixos de MSISDN on-net; uma correspondência endereça o HLR GT["6777"]

Um destino que corresponda a uma entrada home_msisdn_prefixes (com hlr_gt_address definido) é enviado ao HLR GT com SSN chamado 6; tudo o mais mantém o padrão de roteamento por GT por MSISDN. A solicitação SRI-for-SM aceita sccp_opts (:called_party, :called_ssn) para substituir o partido chamado SCCP para qualquer chamador.

Endpoint: POST /api/sri-for-sm

Solicitação:

{
  "msisdn": "447712345678",
  "serviceCenter": "447999123456"
}

Resposta:

{
  "result": {
    "imsi": "234509876543210",
    "locationInfoWithLMSI": {
      "networkNode-Number": "447999555111"
    }
  }
}

cURL:

curl -X POST http://localhost/api/sri-for-sm \
  -H "Content-Type: application/json" \
  -d '{"msisdn": "447712345678", "serviceCenter": "447999123456"}'

Enviar Informações de Roteamento (SRI)​

Endpoint: POST /api/sri

Solicitação:

{
  "msisdn": "447712345678",
  "gmsc": "447999123456"
}

Fornecer Número de Roaming (PRN)​

Endpoint: POST /api/prn

Solicitação:

{
  "msisdn": "447712345678",
  "gmsc": "447999123456",
  "msc_number": "447999555111",
  "imsi": "234509876543210"
}

Enviar Informações de Autenticação​

Endpoint: POST /api/send-auth-info

Solicitação:

{
  "imsi": "234509876543210",
  "vectors": 5
}

Resposta:

{
  "result": {
    "authenticationSetList": [
      {
        "rand": "0123456789ABCDEF0123456789ABCDEF",
        "xres": "ABCDEF0123456789",
        "ck": "0123456789ABCDEF0123456789ABCDEF",
        "ik": "FEDCBA9876543210FEDCBA9876543210",
        "autn": "0123456789ABCDEF0123456789ABCDEF"
      }
    ]
  }
}

Atualizar Localização​

Registra o VLR de atendimento de um assinante no HLR, que responde com a sequência de Inserir Dados do Assinante. Veja Atualizações de Localização no Guia do HLR.

Endpoint: POST /api/updateLocation

Solicitação:

{
  "imsi": "234509876543210",
  "vlr": "447999555111"
}

Interrogatório a Qualquer Momento (ATI)​

Endpoint: POST /api/anyTimeInterrogation

Solicitação:

{
  "hlr_gt": "447999123456",
  "msisdn": "447712345678"
}

Categorias de Operação​

Enviando Solicitações via API​

Usando Swagger UI​

A interface Swagger UI fornece uma interface interativa para cada endpoint.

  1. Navegue até http://your-server/swagger.
  2. Selecione um endpoint (por exemplo, /api/sri-for-sm) e clique em Experimente.
  3. Preencha o corpo da solicitação e clique em Executar.
  4. A resposta SS7 decodificada é exibida abaixo.

O documento OpenAPI bruto está disponível em http://your-server/swagger.json.

Códigos de Resposta da API​

CódigoSignificado
200Sucesso: o resultado decodificado está no corpo da resposta.
400Solicitação inválida: parâmetros inválidos ou ausentes.
504Tempo limite do gateway: sem resposta SS7 dentro do tempo limite da solicitação (padrão de 10 segundos).

Algumas operações são não confirmadas (fire-and-forget) e retornam imediatamente após o envio da mensagem.

Métricas do Cliente MAP​

Todas as métricas são exportadas no endpoint Prometheus (/metrics).

Métrica: map_requests_total Tipo: Contador Descrição: Total de solicitações MAP enviadas. Rótulos: operation: por exemplo sri, sri_for_sm, prn, authentication_info, update_location.

Métrica: map_request_errors_total Tipo: Contador Descrição: Total de solicitações MAP que resultaram em erro ou tempo limite. Rótulos: operation.

Métrica: map_request_duration_milliseconds Tipo: Histograma Descrição: Distribuição dos tempos de ida e volta das solicitações MAP. Rótulos: operation.

Métrica: map_pending_requests Tipo: Gauge Descrição: Solicitações MAP atualmente aguardando uma resposta.

Exemplos de Consultas Prometheus​

# Solicitações SRI-for-SM na última hora
increase(map_requests_total{operation="sri_for_sm"}[1h])

# Tempo médio de resposta SRI
rate(map_request_duration_milliseconds_sum{operation="sri"}[5m])
  / rate(map_request_duration_milliseconds_count{operation="sri"}[5m])

# Taxa de erro por operação
sum(rate(map_request_errors_total[5m])) by (operation)

# Solicitações pendentes atuais
map_pending_requests

Solução de Problemas do Cliente MAP​

Solicitações Expiram (504)​

Sintomas: A API retorna 504; sem resposta do HLR/MSC.

Causas possíveis:

  • A associação M3UA ao STP/SGP não está ATIVA.
  • O STP não tem rota para o Título Global de destino.
  • Endereçamento SCCP incorreto (GT de Chamado/Chamador, SSN) ou Contexto de Roteamento.

Resolução:

  1. Confirme o status da associação M3UA no painel ou através das visualizações de status do Guia STP.
  2. Verifique a conectividade da rede (SCTP) com o STP.
  3. Confirme que o Título Global de destino é roteável e que o subsistema de destino (por exemplo, HLR SSN 6) está em serviço.
  4. Revise os logs em busca de mensagens de retorno SCCP (veja abaixo).

Mensagens de Retorno / Erro SCCP​

Sintomas: Logs mostram mensagens de retorno do Serviço Unitdata SCCP (UDTS).

Causas comuns de retorno:

  • Sem Tradução para o Endereço: o Título Global não está na tabela de roteamento do STP.
  • Falha do Subsistema: o subsistema de destino (por exemplo, HLR SSN 6) está indisponível.
  • Falha / Congestionamento da Rede: problema transitório na rede.

Resolução:

  • Confirme a configuração de roteamento/tradução do STP para o GT de destino.
  • Verifique se o subsistema de destino está operacional.
  • Tente novamente após a limpeza do congestionamento.

Documentação Relacionada​

OmniSS7 por Omnitouch Network Services

Última atualização em