6.6. Using the
Asterisk Database (AstDB)
Having fun yet? It gets even better!
Asterisk provides a powerful mechanism for
storing values, called the Asterisk database (AstDB). The AstDB
provides a simple way to store data for use within your
dialplan.
|
For those of you with experience using
relational databases such as PostgreSQL or MySQL, the Asterisk
database is not a traditional relational database. It is a Berkeley
DB Version 1 database . There are
several ways to store data from Asterisk in a relational database,
but this book will not delve into them.
|
|
The Asterisk database stores its data in
groupings called families, with
valuesidentified by keys. Within a
family, a key may be used only once. For example, if we had a
family called test, we could store only one value with a
key called count. Each stored value must be associated
with a family.
6.6.1. Storing Data in the AstDB
To store a new value in the Asterisk database,
we use the Set( ) application, but instead of using it to set
a channel variable, we use it to set an AstDB variable. For
example, to assign the count key in the test
family the value of 1:
exten => 456,1,Set(${DB(test/count)=1})
If a key named count already exists in
the test family, its value will be overwritten with the
new value. You can also store values from the Asterisk command
line, by running the command database put family key
value. For our example, you would type
database put test count 1.
6.6.2. Retrieving Data from the
AstDB
To retrieve a value from the Asterisk database
and assign it to a variable, we use the Set( ) application
again. Let's retrieve the value of count (again, from the
test family), assign it to a variable called
COUNT, and then speak the value to the caller:
exten => 456,1,Set(DB(test/count)=1)
exten => 456,2,Set(COUNT=${DB(test/count)})
exten => 456,3,SayNumber(${COUNT})
You may also check the value of a given key from
the Asterisk command line by running the command database
get family key. To view the entire
contents of the AstDB, use the database show
command.
6.6.3. Deleting Data from the
AstDB
There are two ways to delete data from the
Asterisk database. To delete a key, use the DBdel( )
application. It takes the family and key as arguments, like
this:
exten => 457,1,DBdel(test/count)
You can also delete an entire key family by
using the DBdeltree( ) application. The DBdeltree(
) application takes a single argument: the name of the key
family to delete. To delete the entire test family, do the
following:
exten => 457,1,DBdeltree(test)
To delete keys and key families from the AstDB
via the command-line interface, use the database del
key and database deltree
family commands, respectively.
6.6.4. Using the AstDB in the
Dialplan
There are an infinite number of ways to use the
Asterisk database in a dialplan. To introduce the AstDB, we'll show
two simple examples. The first is a simple counting example to show
that the Asterisk database is persistent (meaning that it survives
system reboots). In the second example, we'll use the
LookupBlacklist( ) application to evaluate whether or not
a number is on the blacklist and should be blocked.
To begin the counting example, let's first
retrieve a number (the value of the count key) from the
database and assign it to a variable named COUNT. If the
key doesn't exist, DBget( ) will send us to priority
n+101, where we will set the value to 1. The next
priority will send us back to priority 1. This will happen the very
first time we dial this extension:
exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,102,Set(DB(test/count)=1)
exten => 678,103,Goto(1)
Next, we'll say the current value of
COUNT, and then increment COUNT:
exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,2,SayNumber(${COUNT})
exten => 678,3,Set(COUNT=$[${COUNT} + 1])
exten => 678,102,Set(DB(test/count)=1)
exten => 678,103,Goto(1)
Now that we've incremented COUNT, let's
put the new value back into the database. Remember that storing a
value for an existing key overwrites the previous value:
exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,2,SayNumber(${COUNT})
exten => 678,3,Set(COUNT=$[${COUNT} + 1])
exten => 678,4,Set(DB(test/count)=${COUNT})
exten => 678,102,Set(DB(test/count)=1)
exten => 678,103,Goto(1)
Finally, we'll loop back to the first priority.
This way, the application will continue counting:
exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,2,SayNumber(${COUNT})
exten => 678,3,SetVar(COUNT=$[${COUNT} + 1]
exten => 678,4,Set(DB(test/count)=${COUNT})
exten => 678,5,Goto(1)
exten => 678,102,Set(DB(test/count)=1)
exten => 678,103,Goto(1)
Go ahead and try this example. Listen to it
count for a while, and then hang up. When you dial this extension
again, it should continue counting from where it left off. The
value stored in the database will be persistent, even across a
restart of Asterisk.
In the next example, we'll create dialplan logic
around the LookupBlacklist( ) application, which checks to
see if the current Caller ID number exists in the blacklist. (The
blacklist is simply a family called blacklist in the
AstDB.) If LookupBlacklist( ) finds the number in the
blacklist, it sends the call to priority n+101. Otherwise,
the call continues on with the next priority:
exten => 124,1,LookupBlacklist( )
exten => 124,2,Dial(${JOHN})
exten => 124,102,Playback(privacy-you-are-blacklisted)
exten => 124,103,Playback(vm-goodbye)
exten => 124,104,Hangup( )
To add a number to the blacklist, run the
database put blacklist number 1
command from the Asterisk command-line interface. |
