In my previous blog post, I covered how to navigate the SoftLayer Services website, and how to query the SoftLayer API efficiently. In this post, I'll cover additional aspects of using the SoftLayer API with the python client.
If you read part 1 of the series, you have a lot of good techniques for querying the data of resources in SoftLayer such that from any service you can efficiently follow the data trail to other services to get to all of the information you want. The last big thing you need to know about querying the SoftLayer API is: Where are the best places in the enormous SoftLayer Services website to begin these trails? The Account service is a good place to start for many data types, but always starting there will not get you to everything. Even if you can eventually get to the data you want by starting with the Account service, there are often shortcuts to be found by starting somewhere else. I've put together a list of useful trail heads and what data types can be found down each trail. This is by no means an exhaustive list, but will hopefully get you started.
Now that you are an expert at querying the SoftLayer API, let's move on to SoftLayer API calls that modify SoftLayer resources. The basics are similar: Find the right service and method within that service, fill out a data structure similar to what it would be like if you queried it, and if this is an existing resource, use the id to identify it. There are many SoftLayer API methods that modify resources, but to give you a feel for what they are like, I'll list a few and then give you a detailed example of one.
For our detailed example, we will associate VLANs to a network gateway. On the SoftLayer Services website, we find that the Network_Gateway_Vlan service has a method called createObjects that will associate VLANs to a gateway. We see that the argument the method takes is an array of Network_Gateway_Vlan data type objects. So this example will:
import SoftLayer
import pprint
Get the SoftLayer API client object
client = SoftLayer.Client(username=myuser, api_key=mykey, endpoint_url=SoftLayer.API_PUBLIC_ENDPOINT)
Get the id of the gateway you want to associate the VLANs to
gateways = client[‘Account’].getNetworkGateways(mask=‘id, name’, filter={’networkGateways’: {’name’: {‘operation’: ‘v1’}}})
gatewayid = gateways[0][‘id’]
Get all of the VLANs that are allowed to be associated with this gateway.
For this example, we assume we want to associate all of them.
vlans = client[‘Network_Gateway’].getPossibleInsideVlans(id=gatewayid, mask=‘id, vlanNumber’)
Build the array of Network_Gateway_Vlan objects.
It’s local properties are: bypassFlag, id, networkGatewayId, networkVlanId.
objs = []
for v in vlans:
# Fill in the object properties. We set id to None, because SoftLayer will fill that in when the
# objects are created.
objs.append({‘bypassFlag’:True, ‘id’:None, ’networkGatewayId’:gatewayid, ’networkVlanId’:v[‘id’]})
Use the Network_Gateway_Vlan service to associate them
assocVlans = client[‘Network_Gateway_Vlan’].createObjects(objs)
the output is the created Network_Gateway_Vlan objects
pprint.pprint(assocVlans)
You probably noticed that none of the example code had error checking. That's because I was waiting to cover SoftLayer exceptions here. The main SoftLayer API exception class is SoftLayer.exceptions.SoftLayerAPIError, and it has two members: faultCode and faultString. You can catch API errors like this:
import SoftLayer
client = SoftLayer.Client(username=myuser, api_key=mykey, endpoint_url=SoftLayer.API_PUBLIC_ENDPOINT)
try: # A sample API call gatewayid = 1 # an id that does not exist gw = client[‘Network_Gateway’].getObject(id=gatewayid, mask=‘id’) except SoftLayer.exceptions.SoftLayerAPIError as e: print ‘SoftLayer exception occurred: ’ + str(e.faultCode) + ‘: ’ + e.faultString
You can see some of the common faultStrings at the bottom of http://sldn.softlayer.com/article/Exception-Handling-SoftLayer-API in case you want to handle some of them individually in the "except" section of your code.
In my next blog post I'll cover in detail how to order SoftLayer resources using the API.