X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=doc%2FPLCAPI.xml.in;h=02ed26248f83561fb75e57084a29ef2ec259a63e;hb=19d4a01ccf66af9e00914351b3eacd5fc880f988;hp=2b05b190062da3f77475c5c42e1dd362b456f318;hpb=6e2d8b11dc94c065c4dfb4733ef6d09666104fa0;p=plcapi.git
diff --git a/doc/PLCAPI.xml.in b/doc/PLCAPI.xml.in
index 2b05b190..02ed2624 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]}
@@ -435,14 +540,12 @@ nodes = plc.GetNodes([121], ['node_id', 'hostname'])
import xmlrpclib
plc_host='www.planet-lab.eu'
-login='thierry.parmentelat@sophia.inria.fr'
-password='xxxxxxxx'
slice_name='inria_heartbeat'
auth = { 'AuthMethod' : 'password',
- 'Username' : login,
- 'AuthString' : password,
+ 'Username' : 'thierry.parmentelat@inria.fr',
+ 'AuthString' : 'xxxxxx',
}
api_url="https://%s:443/PLCAPI/"%plc_host
@@ -456,9 +559,9 @@ node_ids = plc_api.GetSlices(auth,slice_name,['node_ids'])[0]['node_ids']
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']
+with ('mynodes.txt','a') as f:
+ for node in slice_nodes:
+ f.write(node['hostname'] + "\n")
f.close()