X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=doc%2FPLCAPI.xml.in;h=79fb1a8e83fbe32c016e24e9a9e95c618c5f18a0;hb=fc277519867535062fdacdcea9093e7a8a89b534;hp=b3777a0eadfa1093a763507f0710cdf73e8e5ab4;hpb=599dacb3567c6453feb82e7674b59ecd590c9cad;p=plcapi.git
diff --git a/doc/PLCAPI.xml.in b/doc/PLCAPI.xml.in
index b3777a0..79fb1a8 100644
--- a/doc/PLCAPI.xml.in
+++ b/doc/PLCAPI.xml.in
@@ -156,7 +156,7 @@
- Nueric comparisons
+ Numeric comparisons
Strictly greater/smaller operations are achieved by prepending the field name like in:
GetEvents( { '>time' : 1178531418 } )
@@ -165,6 +165,19 @@
+
+ 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:
@@ -173,13 +186,23 @@
+
+ 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'] } )
+
+
+
@@ -280,8 +360,8 @@
- The current limitation about tags as opposed to native
- fields is that, for performance, tags won't get returned
+ The current limitations about tags, as opposed to native
+ fields, is that for performance, tags won't get returned
when using the implicit set of columns. So for instance:
# get all details for 'pl1.foo.com'
@@ -289,6 +369,20 @@
# this did not return the 'arch' tag
>>> 'arch' in node
False
+
+
+
+
+ For a similar reason, any tag used in the filter argument will have to be mentioned in the list of returned columns as well. For example:
+
+# if 'hrn' is not part of the result, this does not work
+>>> ns=GetNodes({'hrn':'ple.*'},['hostname'])
+Database error b59e068c-589a-4ad5-9dd8-63cc38f2a2eb:
+column "hrn" does not exist
+LINE 1: ...M view_nodes WHERE deleted IS False AND (True AND hrn ILIKE ...
+... abridged ...
+# this can be worked around by just returning 'hrn' as well
+>>> ns=GetNodes({'hrn':'ple.*'},['hrn','hostname'])
@@ -319,21 +413,32 @@ False
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')
-21
+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('vnode01.inria.fr','beta')
+>>> SetNodeDeployment('vnode02.inria.fr','beta')
+
+### checking contents again
>>> for ng in GetNodeGroups(['alphanodes','betanodes'],['groupname','node_ids']): print ng
-{'groupname': u'alphanodes', 'node_ids': []}
-{'groupname': u'betanodes', 'node_ids': [1]}
+{'groupname': u'alphanodes', 'node_ids': [1]}
+{'groupname': u'betanodes', 'node_ids': [2]}
@@ -419,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
+f=open('mynodes.txt','w')
+for node in slice_nodes:
+ print >>f,node['hostname']
+f.close()
+
+
+