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
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
.. image:: /images/hpe_logo2.png
:width: 150pt
|
.. toctree::
:maxdepth: 1
===========
Quick Start
===========
This will cover object creation, a simple call to the API, and a response object.
Scripts of the information provided below are available at: `quickstart_redfish.py <https://github.com/HewlettPackard/python-ilorest-library/tree/master/examples/quickstart_redfish.py>`__
and `quickstart_legacy_rest.py <https://github.com/HewlettPackard/python-ilorest-library/tree/master/examples/quickstart_legacy_rest.py>`__.
For more elaborate examples that use the Redfish API and python-ilorest-library check out the `Examples <Examples.html>`__ section.
The python-ilorest-library provides support for communication using both remote using HTTPS and local in-band using CHIF.
Importing Redfish
==================
Make sure that the redfish library is imported.
.. code-block:: python
import redfish
The very first thing that needs to be done for a restful request is to create a **LegacyRestClient** or **RedfishClient** object.
A **RedfishClient** is for interacting with a Redfish API and a **LegacyRestClient** is for interacting with HPE's Legacy Rest API.
For maximum compatibility between iLOs and other vendor hardware that implements Redfish it is recommended to use the Redfish API whenever possible.
.. note:: HPE's Legacy Rest API is available starting in **iLO 4 2.00**. iLO 4 is Redfish conformant starting with **iLO 4 2.30**. In iLO 5 and above the iLO RESTful API is Redfish only.
Creating a Remote Object
============================
Creating a remote client requires including the iLO hostname or ip address and credentials.
Create a Redfish Object
-----------------------
.. note:: *New in version 3.0.0*
Creation of a Redfish object instance is done using the **RedfishClient** class instead of the **redfish_client** function.
**RedfishClient** takes as parameters iLO hostname/ip address, username, password, and other optional arguments.
For a full list of optional arguments see `here <Reference.html#redfish.rest.v1.RedfishClient>`__.
.. code-block:: python
REST_OBJ = redfish.RedfishClient(base_url=iLO_host, username=login_account, password=login_password)
Create a LegacyRest Object
--------------------------
.. note:: *New in version 3.0.0*
Creation of a Legacy Rest object instance is done using the **LegacyRestClient** class instead of the **rest_client** function.
**LegacyRestClient** takes as parameters iLO hostname/ip address, username, password, and other optional arguments.
For a full list of optional arguments see `here <Reference.html#redfish.rest.v1.LegacyRestClient>`__.
.. code-block:: python
REST_OBJ = redfish.LegacyRestClient(base_url=iLO_host, username=login_account, password=login_password)
Creating a Local Object
===========================
Requirements
-----------------------
* You must be running on a server with iLO and the latest iLO drivers from the SPP.
* You will need to download the iLOrest Chif DLL/SO for your corresponding operating system and place it in your working environment path.
By downloading, you agree to the terms and conditions of the `Hewlett Packard Enterprise Software License Agreement`_.
Windows Download: ilorest_chif.dll_
Linux Download: ilorest_chif.so_
.. _`Hewlett Packard Enterprise Software License Agreement` : https://www.hpe.com/us/en/software/licensing.html
.. _ilorest_chif.dll: https://downloads.hpe.com/pub/softlib2/software1/pubsw-windows/p1463761240/v167985/ilorest_chif.dll
.. _ilorest_chif.so: https://downloads.hpe.com/pub/softlib2/software1/pubsw-linux/p1093353304/v168967/ilorest_chif.so
Create a Redfish or LegacyRest Object
-------------------------------------
If you create a **LegacyRest** or **Redfish** object without a base_url argument it will automatically create an object configured for a local CHIF connection.
A username and password may be included in object creation if they are required.
For **most** operations in **Production** security mode no credentials are required locally.
Some reasons credentials may be required locally:
* iLO is operating in a higher security mode (Such as HighSecurity).
* Some operations require the credentials of an account with a specific privilege to complete (Even in Production security mode).
.. code-block:: python
REST_OBJ = redfish.RedfishClient()
Create a login session
============================
Next the rest object's **login** method is called to initiate a rest session. The login method takes the credentials specified in the REST object we created.
Login also takes an authentication type optional parameter, if the argument is not included the Client will choose an authentication type for you based on the arguments given with `session` being the default.
For `session` authentication, a session key is generated through a rest request, the default for username and password arguments.
For `basic` authentication, the username and password is base64 encoded and sent in a header for each request. For security, session authentication is preferred.
.. code-block:: python
REST_OBJ.login(auth="session")
Remember to call **logout** method once the session is completed to free up sessions.
Perform your first Restful API GET operation
============================================
The following example performs a GET operation on the systems resource (/redfish/v1/systems/1) using the HPE Restful API for iLO.
It does an HTTP GET request on the iLO SSL(HTTPS) port (typically 443 but the iLO can be configured to use another port as well).
The interface is not available over open HTTP (port 80), so SSL handshake must be used.
Perform a HTTP **GET** request by using the **get** method.
>>> response = REST_OBJ.get('/redfish/v1/systems/1')
Response Object
===============
A **Response** object called *response* is now available for us to inspect.
The **status** property returns the HTTP response to our request:
>>> response.status
200
The **dict** property returns the response json body as a Python dictionary:
>>> response.dict
The **getheaders()** method returns a dictionary of all http response headers:
>>> response.getheaders()
{'Transfer-Encoding': 'chunked', 'X_HP-CHRP-Service-Version': '1.0.3', 'ETag': 'W/"0129EA9F"',
'Link': '</redfish/v1/SchemaStore/en/ComputerSystem.json>;
rel=describedby', 'Allow': 'GET, HEAD, POST, PATCH',
'Cache-Control': 'no-cache', 'Date': 'Tue, 06 Aug 2019 19:42:26 GMT',
'OData-Version': '4.0', 'X-Frame-Options': 'sameorigin', 'Content-type': 'application/json; charset=utf-8'}
You can also print the Response object directly:
>>> sys.stdout.write("%s\n" % response)
Response status:
200
Response header:
| Transfer-Encoding chunked
| X_HP-CHRP-Service-Version 1.0.3
| ETag W/"E4BDA463"
| Link </redfish/v1/SchemaStore/en/ComputerSystem.json>; rel=describedby
| Allow GET, HEAD, POST, PATCH
| Cache-Control no-cache
| Date Thu, 01 Aug 2019 19:13:17 GMT
| OData-Version 4.0
| X-Frame-Options sameorigin
| Content-type application/json; charset=utf-8
The formated Response body (Truncated for size):
.. literalinclude:: redfish_quick.json
:language: JSON
A full description of the Response Object is available in the reference `here <Reference.html#redfish.rest.containers.RestResponse>`__.
Other HTTP Requests
============================
Other HTTP Requests **HEAD**, **PATCH**, **POST**, **DELETE**, and **PUT** are just as simple to use as **GET**.
>>> response = REST_OBJ.head('/redfish/v1/systems/1')
>>> response = REST_OBJ.patch('/redfish/v1/systems/1', {'AssetTag': 'newtag'})
>>> response = REST_OBJ.post('/redfish/v1/Systems/1/Actions/ComputerSystem.Reset/', {'ResetType': 'ForceRestart'})
>>> response = REST_OBJ.delete(REST_OBJ.session_location)
>>> response = REST_OBJ.put('<uri>', 'data')
Close the login session
============================
Logout of the current session. This is only required for `session` based authentication.
.. code-block:: python
REST_OBJ.logout()
Continued Reading
=================
That's it! You're ready to perform some Redfish requests! If you are looking for more advanced topics like
*setting timeouts*, more detail on the *response* object, or configuration of the *Redfish* or *LegacyRest* objects check out the `Advanced Usage <Advanced-Usage.html>`__ section.
|
