7a48522615
Just general improvements that felt appropriate after landing the recent API refactor. Change-Id: Ia345e9d7ec2f0dc38ee5bfff13c9fc7bfa206931
88 lines
3.2 KiB
ReStructuredText
88 lines
3.2 KiB
ReStructuredText
Using ARA API clients
|
|
=====================
|
|
|
|
When installing ARA, you are provided with a REST API server and two API
|
|
clients out of the box:
|
|
|
|
- ``AraOfflineClient`` can query the API without needing an API server to be running
|
|
- ``AraHttpClient`` is meant to query a specified API server over http
|
|
|
|
ARA Offline API client
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If your use case doesn't require a remote or persistent API server, the offline
|
|
client lets you query the API without needing to start an API server.
|
|
|
|
In order to use this client, you would instanciate it like this::
|
|
|
|
#!/usr/bin/env python3
|
|
# Import the client
|
|
from ara.clients.offline import AraOfflineClient
|
|
|
|
# Instanciate the offline client
|
|
client = AraOfflineClient()
|
|
|
|
ARA HTTP API client
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
``AraHttpClient`` works with the same interface, methods and behavior as
|
|
``AraOfflineClient``.
|
|
|
|
You can set your client to communicate with a remote ``ara-server`` API by
|
|
specifying an endpoint parameter::
|
|
|
|
#!/usr/bin/env python3
|
|
# Import the client
|
|
from ara.clients.http import AraHttpClient
|
|
|
|
# Instanciate the HTTP client with an endpoint where an API server is listening
|
|
client = AraHttpClient(endpoint="https://api.demo.recordsansible.org")
|
|
|
|
Example API usage
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
For more details on the API endpoints, see :ref:`api-documentation:API Documentation`.
|
|
|
|
Otherwise, once you've instanciated your client, you're ready to query the API.
|
|
|
|
Here's a code example to help you get started:
|
|
|
|
.. code-block:: python
|
|
|
|
#!/usr/bin/env python3
|
|
# Import the client
|
|
from ara.clients.http import AraHttpClient
|
|
|
|
# Instanciate the HTTP client with an endpoint where an API server is listening
|
|
client = AraHttpClient(endpoint="https://api.demo.recordsansible.org")
|
|
|
|
# Get a list of failed playbooks
|
|
# /api/v1/playbooks?status=failed
|
|
playbooks = client.get("/api/v1/playbooks", status="failed")
|
|
|
|
# If there are any results from our query, get more information about the
|
|
# failure and print something helpful
|
|
template = "{timestamp}: {host} failed '{task}' ({task_file}:{lineno})"
|
|
for playbook in playbooks["results"]:
|
|
# Get a detailed version of the playbook that provides additional context
|
|
detailed_playbook = client.get("/api/v1/playbooks/%s" % playbook["id"])
|
|
|
|
# Iterate through the playbook to get the context
|
|
# Playbook -> Play -> Task -> Result <- Host
|
|
for play in detailed_playbook["plays"]:
|
|
for task in play["tasks"]:
|
|
for result in task["results"]:
|
|
if result["status"] in ["failed", "unreachable"]:
|
|
print(template.format(
|
|
timestamp=result["ended"],
|
|
host=result["host"]["name"],
|
|
task=task["name"],
|
|
task_file=task["file"]["path"],
|
|
lineno=task["lineno"]
|
|
))
|
|
|
|
Running this script would then provide an output that looks like the following::
|
|
|
|
2019-03-20T16:18:41.710765: localhost failed 'smoke-tests : Return false' (tests/integration/roles/smoke-tests/tasks/test-ops.yaml:25)
|
|
2019-03-20T16:19:17.332663: localhost failed 'fail' (tests/integration/failed.yaml:22)
|