Monday, October 16, 2017 Register  Login
Visualizzazione per categorie
Categories
CreatedTitleAuthors

  
 Print   
Articolo

Le API di Asterisk - Asterisk Manager

Asterisk Manager consente ad un programma client di connettersi ad una istanza Asterisk ed impartire comandi o rilevare eventi del PBX su una connessione TCP/IP.
Gli sviluppatori possono basare su questa interfaccia diversi tipi di applicazione, da quelle relative al monitoraggio dello stato delle chiamate, ad applicazioni CRM basate sul click-to-call.

La comunicazione tra client e Asterisk server attraverso l'interfaccia manager avviene tramite un semplice protocollo testuale di tipo request/response basato su linee strutturate come "chiave: valore". Le linee sono terminate da CRLF.
Farà uso del remine "messaggio" da ora in avanti per riferirmi ad un set di linee "chiave: valore" terminate da un ulteriore carriage return.

Il protocollo ha le seguenti caratteristiche:

  • E' necessario prima di tutto stabilire una sessione.
  • I messaggi possono essere transmessi in ciascuna direzione in qualsiasi momenti una volta avvenuta l'autenticazione.
  • La prima linea di un messaggio contiene una chiave "Action" quando inviata dal client, una chiave "Event" o "Response" quando inviata invece da Asterisk.
  • L'ordine delle linee all'interno di un messaggio è irrilevante.

Tipi di messaggio

Il tipo di un messaggio viene determinato dalla presenza di una delle chiavi appena citate:

  • Action: Un messaggio inviato dal client ad Asterisk, con la richiesta che venga effettuata una particolare azione. Esiste un certo (estendibile) set di azioni a disposizione del client, determinato dai moduli attualmente caricati nell'engine Asterisk. Solo una azione alla volta può essere invocata. Il messaggio Action contiene il nome della operazione da attuarsi con tutti i parametri necessari. I messaggi Action costituiscono le API dell'interfaccia manager.
  • Response: La risposta inviata da Asterisk relativamente al messaggio Action inviato dal client.
  • Event: Un messaggio riguardante un evento generato dal nucleo di Asterisk o da un suo modulo.

In genere il client invia dei messaggi Action al server Asterisk, il quale esegue la operazione richiesta e ritorna il risultato (spesso solamente Success oppure Failure) in un messaggio Response. Dal momento che non esiste alcuna garanzia circa l'ordine di ricezione dei messaggi Response, il client di solito include un parametro ActionID in ogni messaggio Action, il quale viene rispedito indietro da Asterisk nel corrispondente messaggio Response. In tal modo il client più facilmente relazionare richieste e risposte continuando ad inviare messaggi Action al ritmo voluto, senza dover aspettare la ridposta al precedente.

I messaggi Event vengono usati in due differenti ambiti: Da un lato essi informano i clients circa i cambiamenti di stato in Asterisk (come nuovi channels creati nel frattempo ed hungups oppure agents che dsi colleghino o scolleghino), dall'altro sono usati per trasportare il contenuto delle risposte per azioni che restituiscono una lista di dati (azioni che generano eventi). Quando un client invia un messaggio Action che genera eventi, Asterisk invia un messaggio Response indicante riuscita e contenente una linea "Response: Follows". Quindi esso invia zero o più eventi specifici e da ultimo un evento indicante che tutti i dati sono stati inviati. Gli eventi inviati in risposta ad una azione in grado di generare eventi e l'evento di avvenuta esecuzione contengono l' ActionID del messaggio Action originante, in modo che siano facilmente relazionabili. Un esempio di azione che genera eventi è la action Status che genera eventi riguardanti lo Status per ogni channel attivo. Quando tutti gli eventi Status sono stati inviati, un evento finale di StatusComplete viene inviato.

Apertura di una sessione Manager ed Autenticazione Utente

Per accedere all'interfaccia Asterisk Manager un utente necessita di stabilire una sessione con la richiesta di una connessione TCP/IP ad una porta (di solito la 5038) sulla quale l'istanza Asterisk si trova in ascolto e quindi di autenticarsi tramite la action 'Login'. Ciò richiede un account precedentemente registrato presso il server Asterisk.
Gli accounts degli utenti sono configurati in /etc/asterisk/manager.conf. Un account consiste in un insieme di hosts o IP, di una password di autenticazione e di una a lista di permessi, compresi in un set determinato, ciascuno definito tramite una capacità di "read", "write", oppure "read/write". Se ad un client viene assicurata la capacità di leggere una determinata classe, Asterisk gli notificherà gli eventi relativi a tale classe. Se ad un client viene assicurata la capacità di scrivere una data classe, potrà inviare messaggi actions di tale classe.

Un esempio di autenticazione:

# telnet localhost 5038
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Asterisk Call Manager/1.0
Action: login
Username: agent
Secret: 007

Response: Success
Message: Authentication accepted

Messaggi Action

Quando si invia un messaggio Action ad Asterisk, chiavi extra possono (o devono) essere fornite per meglio specificare l'operazione da compiere. Per esempio, potreste specificare un numero da chiamare, oppure un channel da disconnettere. Inoltre, se la vostra action fa in modo che Asterisk esegua una entry nel dialplan, potreste voler passare variabili al dialplan, secondo lo schema seguente:

Action: 
:
:
...
Variable: =
Variable: =

Le possibili action (Asterisk versione 1.2.0):

 

Action Privilege Synopsis
AbsoluteTimeout call,all Imposta Absolute Timeout
AgentCallbackLogin agent,all Imposta un agent come registrato da callback
AgentLogoff agent,all Imposta un agent come non più registrato
Agents agent,all Elenca gli agents ed il loro status
ChangeMonitor call,all Cambio il monitoring filename di un channel
Command command,all Esegue un comando Asterisk CLI
DBGet system,all Ottiene una DB Entry
DBPut system,all Memorizza una DB Entry
Events none Attiva/disattiva l'output del flusso degli Events
ExtensionState call,all Controlla lo status di una Extension
Getvar call,all Ottiene una Channel Variable
Hangup call,all Hangup Channel
IAXnetstats none Mostra IAX Netstats
IAXpeers none Elenca IAX Peers
ListCommands none Elenca i comandi manager disponibili
Logoff none Logoff
MailboxCount call,all Controlla il numero di messaggi in una Mailbox
MailboxStatus call,all Controlla lo stato di una Mailbox
Monitor call,all Monitorizza un channel
Originate call,all Origina una chiamata
ParkedCalls none Elenca le chiamate parcheggiate
Ping none Comando Keepalive
QueueAdd agent,all Aggiunge una interfaccia ad una coda.
QueuePause agent,all Rende un membro di una coda temporaneamente indisponibile
QueueRemove agent,all Rimuove una interfaccia da una coda
Queues none Accoda
QueueStatus none Ottiene lo stato di una coda
Redirect call,all Redireziona (transfer) una chiamata
SetCDRUserField call,all Imposta il CDR UserField
Setvar call,all Imposta una variabile Channel
SIPpeers system,all Elenca i SIP peers
SIPshowpeer system,all Mostra le caratteristiche di un peer SIP
Status call,all Elenca gli stati dei channel attivi
StopMonitor call,all Termina di monitorare un channel
ZapDialOffhook none Dial over Zap channel while offhook
ZapDNDoff none Pone a OFF DND (Do Not Disturb) su un Zap channel
ZapDNDon none Pone a ON il DND (Do Not Disturb) su un Zap channel
ZapHangup none Provoca l'hangup di un Zap Channel
ZapShowChannels none Mostra lo stato dei zapata channels
ZapTransfer none Trasferisce un Zap Channel

Author: Anonymous Anonymous
 


 

 Print   
Terms Of Use | Privacy Statement | Si Parla Di
Copyright 2007-2009 by SiParlaDi