Client Session¶
This guide explains how you can make a connection to the AOS-server and using the elements of the Session.
Creating a Session¶
The first step is creating a client Session to the AOS-Server:
>>> from apstra.aosom.session import Session
>>> aos = Session('192.168.59.250', user='admin', passwd='admin)
>>> aos.login()
The first parameter is the AOS-server IP address or hostname. The remaining key/value arguments are documented in
the API reference section. The user and passwd both default to admin
if not provided.
The login()
method will make the request to authenticate a login and provide back a session token. If for any
reason the login attempt fails, an exception will be raised. See session.Session.login()
for
details. You can verify the login session information by examining the Session.session
.
The value of the aos.session
value looks like:
>>> aos.session
{'port': 8888,
'server': 'aos-server',
'token': u'eyJhbGci<~snip~>MTUiMP0skQ'}
Making use of a Session¶
The general use of the Session an interface to the exposed API features, such as the Device-Manager, using resources,
design elements, and managing network services. You can see a list of the existing API features exposed via the
aos-pyez library by examining the Session.ModuleCatalog
data:
['Blueprints', 'IpPools', 'DesignTemplates', 'ExternalRouters',
'AsnPools', 'RackTypes', 'LogicalDevices', 'Devices', 'LogicalDeviceMaps']
To access any of these features, you simple use the name of the module as an attribute of the Session. For example, to show a list of IP Pool names managed by AOS, you would do the following:
>>> aos.IpPools.names
[u'Switches-IpAddrs', u'Servers-IpAddrs']
The modules are generally managed as a collection.Collection
and you can manage an item within a collection
as a collection.CollectionItem
. The use of Collections and CollectionItems will be covered on separate
guide pages.
Resuming an Existing Session¶
In some cases, you may want to pass around the session information between programs. Do do this you can use the
Session.session
property. For example returning the session as JSON data:
>>> keep_session = aos.session
>>> json.dump(keep_session, open('keep_session.json', 'w+'), indent=2)
And then in a different program, you can use this session data to restore a connection:
>>> aos = Session()
>>> had_session = json.load(open('keep_session.json'))
>>> aos.session = had_session
And now the session is again active. If the session could not be restored for any reason, then an exceptions will
be raised. See the Session.session.login()
for details on those exceptions.
Session.api.requests¶
The Session instance maintains properties that allows you direct Requests level access, should you need it for
any reason. For example, you may want access to API capabilities not presently exposed by the aos-pyez library.
You can use the Session.api
and Session.api.requests
values. The api.url
maintains the top
level HTTP URL to the AOS-Server:
>>> aos.api.url
'http://aos-server:8888/api'
And the api.requests
is a Requests Session object used for direct access. Here is an example of directly
invoking a GET on API version build information:
>>> aos.api.requests.get("%s/versions/build" % aos.api.url)
<Response [200]>
And the data returned by using the api.requests
is the same Requests Response object:
>>> got = aos.api.requests.get("%s/versions/build" % aos.api.url)
>>> got.json()
{u'version': u'1.1.0-11', u'build_datetime': u'2016-12-12_16:46:51_PST'}
The Session.api.requests
property stores the necessary headers from the login authentication. This
means that you do not need to explicitly provide the headers=
value on the requests call. For example, doing a GET
on the IP Pools would require an authentication token. Here is how you could directly invoke the requests library
to do the same data retrieval as shown before, in this case getting the raw JSON output.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | # each collection has a url property as well!
>>> aos.IpPools.url
'http://aos-server:8888/api/resources/ip-pools'
>>> got = aos.api.requests.get(aos.IpPools.url)
>>> print json.dumps(got.json(), indent=2)
{
"items": [
{
"status": "in_use",
"subnets": [
{
"status": "pool_element_in_use",
"network": "172.20.0.0/16"
}
],
"display_name": "Switches-IpAddrs",
"tags": [],
"created_at": "2017-01-28T19:57:12.887618Z",
"last_modified_at": "2017-01-28T19:57:12.887618Z",
"id": "65dfbc77-1c77-4a99-98a6-e36c5aa7e4d0"
},
{
"status": "in_use",
"subnets": [
{
"status": "pool_element_in_use",
"network": "172.21.0.0/16"
}
],
"display_name": "Servers-IpAddrs",
"tags": [],
"created_at": "2017-01-28T19:57:13.096657Z",
"last_modified_at": "2017-01-28T19:57:13.096657Z",
"id": "0310d821-d075-4075-bdda-55cc6df57258"
}
]
}
|