AirVantage API access from Shell command-line
The airvantage-api-shell project aims to provides a light and flexible Shell script that enables to interact with AirVantage M2M Cloud API in command-line.
Prerequisites
AirVantage account
Depending on your location, you need an account on one of AirVantage M2M Cloud datacenters:
- https://na.airvantage.net (North America)
- https://eu.airvantage.net (EMEA)
jq command-line JSON processor
This project requires the jq
command-line JSON processor, which is available at http://stedolan.github.io/jq/
To install it, you only need to:
- Download the appropriate binaries for your system from http://stedolan.github.io/jq/download/
- Put these binaries in your
PATH
.
av
script
Installing the The installation procedure is simple as downloading the script, and include it in your PATH
.
This can be done with the following command lines:
git clone https://github.com/bmiegemolle/airvantage-api-shell.git
export PATH=`pwd`/airvantage-api-shell/scripts:${PATH}
You're now ready to use the av
script! Enjoy!
Get an access token
You can get an access token to AirVantage M2M Cloud API with the av ssh
command:
av ssh host
Example:
av ssh na.airvantage.net
You'll be asked for your username and password, and you'll get an access token to AirVantage M2M Cloud API. This token will be stored in your file system (in the /tmp/av-access-token file), and it will be automatically used by any further av
commands.
Supported production hosts are:
- na.airvantage.net
- eu.airvantage.net
The following integration and validation environments can also be accessed:
- edge.airvantage.net
- dev-airlink.airvantage.net
- qa-branch.airvantage.net
- qa-trunk.airvantage.net
Who am I?
You can retrieve the details of the currently loggued user with the av whoami
command:
av whoami
Example:
av whoami
List entities
The av ls
command will enable you to list some entities of the AirVantage M2M Cloud portal:
av ls [/entities] [--uid-only]
- /entities is optional. If not specified, then systems will be listed.
- --uid-only argument enables to return only a list of entities uid as plain text, instead of entities as JSON objects.
Examples:
# List all systems, and display them as a list of JSON objects
av ls
av ls /systems
# List all users, and display them as a list of plain text UIDs
av ls /users --uid-only
# List all operations, and display them as a list of JSON objects
av ls /operations
Find entities
The av find
command will enable you to search some entities of the AirVantage M2M Cloud portal:
av find -field value [/entities] [--uid-only]
- -field value enables you to specify a search criteria.
- /entities is optional. If not specified, then systems will be searched.
- --uid-only argument enables to return only a list of entities uid as plain text, instead of entities as JSON objects.
Examples:
# Find systems which name contains "test", and display them as a list of JSON objects
av find -name test
# Find systems with a commStatus equals to "ERROR", and display them as a list of plain text UIDs
av find -commStatus ERROR --uid-only
# Find messages received by the system with UID "c996897fa60d4882a720292171debb5a"
av find /systems/c996897fa60d4882a720292171debb5a/messages
# Find users whose name contains "admin", and display them as a list of JSON objects
av find -name admin /users
# Find operations created by the user "administrator@m2mop.net", and display them as a list of JSON objects
av find -user administrator@m2mop.net /operations
Get entities details
Using the av cat
command, you can retrieve the details of a specific entity of the portal:
av cat [arg]
arg can be:
- /entities/uid: display the details of the specified entity
- /uid: idem, but assumes that the entity is a system
- /entities: entities UIDs are retrived from the standard input
- empty: entities UIDs are also retrived from the standard input, but assumes that those entities are systems
Examples:
# Displays the details of the system with UID "c996897fa60d4882a720292171debb5a"
av cat c996897fa60d4882a720292171debb5a
av cat /systems/c996897fa60d4882a720292171debb5a
# Displays the details of the operation with UID "650db7d9ab4547d4b2e7f8e8cb70f7e2"
av cat /operations/650db7d9ab4547d4b2e7f8e8cb70f7e2
# Displays the details of all systems with a commStatus equals to "ERROR"
av find -commStatus ERROR --uid-only | av cat
# Displays the details of all messages received by the system with UID "c996897fa60d4882a720292171debb5a"
av find /systems/c996897fa60d4882a720292171debb5a/messages --uid-only | av cat
# Displays the details of all users
av ls /users --uid-only | av cat /users
The two last commands show how to use the find (or ls) and cat commands in pipeline. The standard output produced by the find (or ls) commands can be directly used by the cat command as long you have used the --uid-only argument to produced only plain text UIDs.
Create an entity
You can create an new entity with the av touch
command. This command opens the vi
editor to enter the different fields of the entity to create. When exiting the editor, those information are sent to the server in order to create the entity.
There are two creation modes:
- Creation from scratch: The
vi
editor is opened with an empty JSON content. You'll need to provide all necessary information to create the entity. - Creation from template: You can use an existing entity as a template, by specifying its UID in the command line arguments. In this case, a first request is done to the server in order to get the entity details. The
vi
editor is then opened with those details. All you have to do is editing the information to match your new entity values.
av touch [/entities] [--template-uid uid]
- /entities is optional. If not specified, then systems will be created.
- --template-uid uid enables you to specify an existing entity to use as a template.
This command outputs the entity details after the creation, or the error message if something bad happened on server-side.
Examples:
# Creates a system from scratch
av touch
av touch /systems
# Creates a gateway from scratch
av touch /gateways
# Creates a gateway using the gateway with UID "590fea92135a46e9acc7b59952843ec9" as a template
av touch /gateways --template-uid 590fea92135a46e9acc7b59952843ec9
Edit an entity
You can edit entities with the av vi
command. In a nutshell, this command retrieves the entity details and opens the vi
editor to edit them. When exiting the editor, the data will automatically be sent to the server in order to update the entity.
av vi arg
arg can be:
- /entities/uid: edit the details of the specified entity
- /uid: idem, but assumes that the entity is a system
This command outputs the entity details after the update, or the error message if something bad happened on server-side.
Examples:
# Edits the system with UID "c996897fa60d4882a720292171debb5a"
av vi c996897fa60d4882a720292171debb5a
av vi /systems/c996897fa60d4882a720292171debb5a
# Edits the gateway with UID "590fea92135a46e9acc7b59952843ec9"
av vi /gateways/590fea92135a46e9acc7b59952843ec9
Delete an entity
It possible to delete entities from the AirVantage M2M Cloud portal by using the av rm
command.
av rm arg
arg can be:
- /entities/uid: delete the specified entity
- /uid: idem, but assumes that the entity is a system
Warning: No confirmation will be prompted before actually deleting the entity. You should be sure of what you're doing when invoking this command!
Examples:
# Deletes the system with UID "c996897fa60d4882a720292171debb5a"
av rm c996897fa60d4882a720292171debb5a
av rm /systems/c996897fa60d4882a720292171debb5a
# Deletes the gateway with UID "590fea92135a46e9acc7b59952843ec9"
av rm /gateways/590fea92135a46e9acc7b59952843ec9
Users CSV export example
By mixing av
commands with standard Shell ones, you have a powerful way to manipulate AirVantage M2M Cloud API.
For example, if you want to export a list of AirVantage users in a CSV file, the following script will do the trick:
# CSV header
echo "UID;EMAIL;NAME;PHONE_NUMBER;COMPANY_UID;COMPANY_NAME" > out.csv
# CSV content
av ls /users --uid-only \
| av cat /users \
| sed '/^$/d' \
| while read line; \
do \
csv_line="`echo $line | jq '.uid, .email, .name, .phoneNumber, .company.uid, .company.name' | tr '\n' ';'`"; \
echo "${csv_line%?}"; \
done >> out.csv
# Have a look at the wonderful generated CSV file
cat out.csv
And that's all! Simple as that! With the av
script, you can do whatever you want. The only limit is your imagination (and the known limitations listed below ;) ).
Known limitations
- All
av
commands only work with API that return a list of items identified by a UID (unique identifier). It does not work with other entities, such as labels. - Pagination is not handled yet by the
av
script. Default pagination will thus be used when accessing to any API (i.e. no offset, and up to 100 items returned).
What's coming next?
Two main topics should be addressed soon:
- Remove the limitations described above.
- Propose alternatives to the use of
vi
to create or edit an entity.