X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=doc%2FPLCAPI.xml.in;h=02ed26248f83561fb75e57084a29ef2ec259a63e;hb=e70e20fdbececafef842ec7b330fd48db42e614e;hp=f52353ecef3c61960f3e9555d8c41e2f2f93f93d;hpb=d910a6190fec258ddbf0e26d01539839ac3fdc76;p=plcapi.git
diff --git a/doc/PLCAPI.xml.in b/doc/PLCAPI.xml.in
index f52353e..02ed262 100644
--- a/doc/PLCAPI.xml.in
+++ b/doc/PLCAPI.xml.in
@@ -1,4 +1,5 @@
+
@@ -122,16 +123,16 @@
Filters
- Most of the Get functions take a
+ Most of the Get methods take a
filter argument. Filters may be arrays of integer (and sometimes
string) identifiers, or a struct representing a filter on the
- attributes of the entities being queried. For example,
+ attributes of the entities being queried. For example,
-# plcsh code fragment (see below)
-GetNodes([1,2,3])
-GetNodes({'node_id': [1,2,3]})
+>>> GetNodes([1,2,3])
+>>> GetNodes({'node_id': [1,2,3]})
+
Would be equivalent queries. Attributes that are
themselves arrays (such as interface_ids
@@ -139,28 +140,311 @@ GetNodes({'node_id': [1,2,3]})
filters.
Filters support a few extra features illustrated in the following examples.
+
+
+ Pattern Matching
+ * can be used in a text value and have the usual meaning, so all nodes in the fr can be obtained with:
+ GetNodes ( { 'hostname' : '*.fr' } )
+
+
+
+
+ Negation
+ Fields starting with a ~ are negated, so non-local nodes can be fetched with:
+ GetNodes( { '~peer_id' : None } )
+
+
+
+
+ Numeric comparisons
+ Strictly greater/smaller operations are achieved by prepending the field name like in:
+ GetEvents( { '>time' : 1178531418 } )
+
+ Greater/smaller or equal:
+ GetEvents( { ']event_id' : 2305 } )
+
+
+
+
+ Filtering on a sequence field
+ A field starting with '&' or '|' should refer to a sequence type;
+ the semantics is then that the object's value (expected to be a list)
+ should contain all (&) or any (|) value specified in the corresponding
+ filter value.
+ GetPersons ( { '|role_ids' : [ 20, 40 ] } )
+ GetPersons ( { '|roles' : ['tech', 'pi'] } )
+ GetPersons ( { '&roles' : ['admin', 'tech'] } )
+ GetPersons ( { '&roles' : 'tech' } )
+
+
+
+
+ Sorting and Clipping
+ The following 3 special fields can be used to extract only a subset of the results for pagination:
+ GetNodes( { '-SORT' : 'hostname' , '-OFFSET' : 30 , '-LIMIT' : 25 }
+
+
+
+
+
+ All criteria / Any criteria
+ The default in the vast majority of the code is to select
+ objects that match ALL the criteria specified in the struct. It
+ is possible to search for objects that match ANY of these by
+ adding the special '-OR' key (the value is then ignored), as in:
+ GetPersons ( { '-OR' : 'anything', 'site_id':2, '&roles':['admin'] } )
+
+
+
+
-
+
+ Nodegroups
+
+ In earlier versions up to v4.2, NodeGroups
+ used to be defined extensively. So you would,
+ basically, create an empty nodegroup instance, and then use
+ AddNodeToNodeGroup or
+ DeleteNodeFromNodeGroup to manage the nodegroup's
+ contents.
+
+ The new model has been redefined as follows. You now define
+ a nodegroup as the set of nodes for which a given Tag
+ has a given value, which are defined once and for good
+ when creating the NodeGroup object.
+
+ So for instance for managing the set of nodes that are
+ running various levels of software code, PLC has defined two
+ NodeGroups named alpha
+ and beta . With the new model, we would now do
+ something like the following, using the built-in
+ deployment tag that is created for that purpose:
+
+### creating node groups
+>>> AddNodeGroup('alphanodes','deployment','alpha')
+21
+>>> AddNodeGroup('betanodes','deployment','beta')
+22
+### checking contents (no node has 'deployment' set to either 'alpha' or 'beta' yet)
+>>> for ng in GetNodeGroups(['alphanodes','betanodes'],['groupname','node_ids']): print ng
+{'groupname': u'alphanodes', 'node_ids': []}
+{'groupname': u'betanodes', 'node_ids': []}
+
+### displaying node ids
+>>> for n in GetNodes({'hostname':'*.inria.fr'},['hostname','node_id']): print n
+{'hostname': u'vnode01.inria.fr', 'node_id': 1}
+{'hostname': u'vnode02.inria.fr', 'node_id': 2}
+
+### setting 'deployment' for these two nodes
+>>> SetNodeDeployment('vnode01.inria.fr','alpha')
+>>> for ng in GetNodeGroups(['alphanodes','betanodes'],['groupname','node_ids']): print ng
+{'groupname': u'alphanodes', 'node_ids': [1]}
+{'groupname': u'betanodes', 'node_ids': []}
+>>> SetNodeDeployment('vnode02.inria.fr','beta')
+
+### checking contents again
+>>> for ng in GetNodeGroups(['alphanodes','betanodes'],['groupname','node_ids']): print ng
+{'groupname': u'alphanodes', 'node_ids': [1]}
+{'groupname': u'betanodes', 'node_ids': [2]}
+
+
+
+
+
+
PlanetLab shell
A command-line program called plcsh
@@ -240,6 +524,48 @@ nodes = GetNodes([121], ['node_id', 'hostname'])
nodes = plc.GetNodes([121], ['node_id', 'hostname'])
+
+
+ Using regular python
+
+ It is also possible to write simple regular-python scripts,
+ as illustrated in the example below. The only difference with the
+ examples above is that all API calls need to be passed a first
+ argument for authentication. This example would write in a file
+ the name of all the hosts attached to a given slice.
+
+
+#!/usr/bin/env python
+
+import xmlrpclib
+
+plc_host='www.planet-lab.eu'
+
+slice_name='inria_heartbeat'
+
+auth = { 'AuthMethod' : 'password',
+ 'Username' : 'thierry.parmentelat@inria.fr',
+ 'AuthString' : 'xxxxxx',
+}
+
+api_url="https://%s:443/PLCAPI/"%plc_host
+
+plc_api = xmlrpclib.ServerProxy(api_url,allow_none=True)
+
+# the slice's node ids
+node_ids = plc_api.GetSlices(auth,slice_name,['node_ids'])[0]['node_ids']
+
+# get hostname for these nodes
+slice_nodes = plc_api.GetNodes(auth,node_ids,['hostname'])
+
+# store in a file
+with ('mynodes.txt','a') as f:
+ for node in slice_nodes:
+ f.write(node['hostname'] + "\n")
+f.close()
+
+
+