Using Python REST API SDK
PyPi Package
HPE Aruba Networking Central is a unified cloud-based network management and configuration platform for campus, branch, remote and data center networks. There are various needs for automation and programmability like automating repetitive tasks, configuring multiple devices, monitoring and more. This python package is to programmatically interact with Central via REST APIs.
How to Install?
Install using Python package manager
pip3 install pycentral
To install with extras, which displays log messages in color, install package with the following command
pip3 install pycentral[colorLog]
Package structure
The dir structure of the pycentral
package is as follows.
│ README.md
│ Contributions.md
│ ...
│
└───pycentral
│ │ base.py
│ │ configuration.py
│ │ ...
│ │
│ └───workflows
│ │ config_apsettings_from_csv.py
│ │ ...
│
└───docs
│ ...
pycentral
The pycentral
subfolder contains the Central Python modules. Each module contains multiple Python classes. Each Class is a representation of some Central API categories as mentioned in the API Reference section. Each class has its own function definitions that are used to make a single REST API call.
In addition to using the modules provided by the package, there is also a module base.py
containing function ArubaCentralBase.command()
. This function can make any REST API call using the API endpoint URL, HTTP Method, HTTP query params and HTTP payload as required by an API endpoint. The REST API calls are made using the Python requests library by ArubaCentralBase.command()
, as supported by Central API Gateway endpoints.
Module Documentation
To get list of implemented modules and its documentation visit python module documentation.
Gathering requirements
Gathering variables required for the package base class ArubaCentralBase
.
- base_url
You can find the base URL of the Central account's API Gateway from the table here. The base URL is based on the geographical Central cluster in which the account is registered.
- client_id and client_secret
Obtain client_id and client_secret variables by creating an API Gateway client in Aruba Central. Refer the Aruba API Gateway section for more details.
-
access_token: You can create an API access token for Central from -
-
customer_id
Obtain the customer_id by clicking on the figure icon on top right corner of the Central WebUI.
- username and password
Central user's username and password. The access token generated by the OAUTH APIs will have the same role/privileges as the provided Central user credentials.
Execution
ArubaCentralBase class requirements
ArubaCentralBase
class requires one mandatory argument central_info. Other optional arguments are token_store and ssl_verify.
1. central_info
One of the following options can be used.
a. Either Provide variables obtained from Gather Requirements
section directly to Aruba Central Base class in Python dict structure.
central_info = {
"base_url": "<api-gateway-domain-url>",
"token": {
"access_token": "<api-gateway-access-token>"
}
}
central_info = {
"username": "<aruba-central-account-username>",
"password": "<aruba-central-account-password>",
"client_id": "<api-gateway-client-id>",
"client_secret": "<api-gateway-client-secret>",
"customer_id": "<aruba-central-customer-id>",
"base_url": "<api-gateway-domain-url>"
}
b. OR Provide the required variables using JSON/YAML file. Use pycentral.workflows_utils.get_conn_from_file()
function which accepts name of the file and returns the ArubaCentralBase
instance object. YAML examples are provided below.
central_info:
base_url: "<api-gateway-domain-url>"
token:
access_token: "<api-gateway-access-token>"
ssl_verify: true
central_info:
username: "<aruba-central-account-username>"
password: "<aruba-central-account-password>"
client_id: "<api-gateway-client-id>"
client_secret: "<api-gateway-client-secret>"
customer_id: "<aruba-central-customer-id>"
base_url: "<api-gateway-domain-url>"
token_store:
type: "local"
path: "temp"
ssl_verify: true
2. token_store
As provided in the above YAML file, token_store default settings are type "local" and path "temp". When OAUTH APIs approach is used, a new access token will generated and cached in the mentioned path of local python host machine. This assists in access_token re-use and help in refreshing expired tokens by the package instead of creating a new access_token.
3. ssl_verify
This argument is of boolean type and default setting is "true". When set to "true", the python client will validate Central's SSL certs while making HTTPS requests.
Security Note
File accepted by
pycentral.workflows_utils.get_conn_from_file()
are not encrypted. Implement your preferred security encryption method for added security.In addition, by taking OAUTH APIs approach the pycentral package will cache generated access_token in local machine in unencrypted JSON file. Override
ArubaCentralBase.storeToken()
andArubaCentralBase.loadToken()
by leveraging theArubaCentralBase.token_store
variable to implement your own secure token storage mechanism.
Sample scripts
- Making API call using pycentral base
Using the base classArubaCentralBase
, any Central supported REST API calls can be made. A list of groups from Central can be obtained from the script below. Obtain the HTTP Path, HTTP Method and HTTP query params from Central Swagger documentation or API references section.
Execute the script ,after filling central_info
variable, with command python3 pycentral_base_sample.py
.
from pycentral.base import ArubaCentralBase
from pprint import pprint
# Create an instance of ArubaCentralBase using API access token
# or API Gateway credentials.
central_info = {
"base_url": "<api-gateway-domain-url>",
"token": {
"access_token": "<api-gateway-access-token>"
}
}
ssl_verify = True
central = ArubaCentralBase(central_info=central_info,
ssl_verify=ssl_verify)
# Sample API call using 'ArubaCentralBase.command()'
# GET groups from Aruba Central
apiPath = "/configuration/v2/groups"
apiMethod = "GET"
apiParams = {
"limit": 20,
"offset": 0
}
base_resp = central.command(apiMethod=apiMethod,
apiPath=apiPath,
apiParams=apiParams)
pprint(base_resp)
Security Note
Please note that you would not want to hardcode access_token directly in a production script.
- Making API call using pycentral modules
Some API endpoints supported by Central are implemented as modules in the Python package.pycentral.configuration
module andGroups
class is used below to obtain list of groups from Central.
Execute the script, after filling central_info
variable, with command python3 pycentral_module_sample.py
.
# Import Aruba Central Base
from pycentral.base import ArubaCentralBase
from pprint import pprint
# Create an instance of ArubaCentralBase using API access token
# or API Gateway credentials.
central_info = {
"base_url": "<api-gateway-domain-url>",
"token": {
"access_token": "<api-gateway-access-token>"
}
}
ssl_verify = True
central = ArubaCentralBase(central_info=central_info,
token_store=None,
ssl_verify=ssl_verify)
# Sample API call using Configuration sub-module `pycentral.configuration`
from pycentral.configuration import Groups
# Get groups max limit 20, apply offset and fetch other groups in loop
g = Groups()
module_resp = g.get_groups(central)
pprint(module_resp)
Workflows
Workflows are used to achieve an automation use-case which generally involves multiple API calls or dealing with scale and repetitive tasks with ease. Check out the central-python-workflows repository to check out workflows that utilize the Pycentral library.
Updated about 1 month ago