<!---
(c) Copyright 2019-2021 Hewlett Packard Enterprise Development LP
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
# python-opsramp
A Python language binding for the OpsRamp API
CircleCI [](https://circleci.com/gh/HewlettPackard/python-opsramp)
GitHub Actions [](https://github.com/HewlettPackard/python-opsramp/actions)
## About
This directory tree contains a Python 3 module that provides a convenient way to
access the OpsRamp REST API programmatically. The OpsRamp API documentation is
somewhat opaque and this binding hides some of the details for exactly that reason.
I have also added "assert" statements in various places to guard against pitfalls
that I ran into that are not obvious from the API docs.
### Build
This repo includes standard Python packaging using pyproject.toml and setuptools.
Source and wheel distributions can be built using `python3 -m build` in the usual way.
### Scope
The basic framework of this library is in place and the
scope has increased incrementally over time. The supplied samples
exercise most of the main API sections and are described
later in this document.
Note however that all of our wrapper objects also provide an `api` property that
can be used to access REST URLs further down the API tree
where we have not written a specific wrapper class yet.
While you can use these api objects to work directly with OpsRamp at a REST level,
please consider taking the small amount of time needed to add a proper wrapper class
here instead, for your own benefit and that of future users.
### Return values
All functions in this binding return regular Python objects (not JSON strings).
In general you will need to look at the OpsRamp API docs to see exactly what
sort of object and/fields the response will contain; typically we return exactly
what the API gave us, or an equivalent Python object if it returned JSON.
## Public Object Tree
Following is a summary of the object tree currently available in this OpsRamp language binding. See
the "Samples" section later in this document for an illustration of how to use them.
You start by calling `opsramp.binding.connect()`
which returns a single "OpsRamp" object to represent the entire REST API instance
that you want to access, and make a series of calls that return progressively lower level objects to access
lower level information from OpsRamp. For clarity in these end-user instructions I have omitted several Python
classes that are internal implementation detail in the module and not intended for direct use by external callers.
Here's an illustration of a simple use of the binding. See the Samples section for more detailed ones.
```
import opsramp.binding
ormp = opsramp.binding.connect(OPSRAMP_URL, KEY, SECRET)
cfg = ormp.config()
print('alert types', cfg.get_alert_types())
print('timezones', cfg.get_timezones())
```
### Class diagram
This diagram is an overview of the public classes and their relationship to each other.
The individual classes are described in detail in the following section. This diagram
was produced using [Graphviz](https://www.graphviz.org/) `apt-get install graphviz`
and to edit it you need to modify the
source file classes.dot and regenerate the PNG from that.
`dot -Tpng < classes.dot > classes.png`
I have used color to highlight the subset of classes that implement a "create" method.
### Class definitions
import opsramp.binding
- def connect(url, key, secret) _returns an instance of the class Opsramp that is connected to the specified API endpoint_
This function posts a login request to the specified endpoint URL using the key and secret given. This post
returns an access token, which the function uses to construct an Opsramp object and returns that.
- class Opsramp(url, token) _an object representing the complete API tree of one OpsRamp instance_
- config() -> returns a GlobalConfig object that can be used to access global settings for this OpsRamp instance.
- tenant(uuid) -> returns a Tenant object representing the API subtree for one specific tenant.
- metrics() -> returns a MetricsApi object that can be used to access the raw metrics api of this OpsRamp instance.
import opsramp.globalconfig
- class GlobalConfig() _read-only access to global settings on this OpsRamp instance_
- get\_alert\_types() -> returns a list of the global alert types that are defined on this OpsRamp instance.
- get\_channels() -> returns a list of the "channels" that are defined on this OpsRamp instance. See the OpsRamp docs for details.
- get\_countries() -> a list of dicts each describing one country known to this OpsRamp instance.
- get\_timezones() -> a list of dicts each describing one timezone known to this OpsRamp instance.
- get\_alert\_technologies() -> a list of dicts each describing one alert technology known to this OpsRamp instance.
- get\_nocs() -> a list of dicts each describing one NOC known to this OpsRamp instance.
- get\_device\_types() -> a list of dicts each describing device type known to this OpsRamp instance.
import opsramp.metrics
- class MetricsApi() _the metrics API subtree for this OpsRamp instance_
- get(pattern) -> returns metric definitions or time series values, depending on the pattern.
This a raw interface to the GET portions of the OpsRamp metrics API and you should consult the OpsRamp
documentation for the syntax that is permitted in pattern.
- search(pattern) -> returns metric _time series_ values matching the pattern. These patterns
can be quite complex and you should refer to the OpsRamp API documentation for the syntax.
import opsramp.tenant
- class Tenant(uuid) _the API subtree for one specific tenant_
- get\_alert\_script() -> Returns a string containing the appropriate Python script to run on a Linux node
to install the OpsRamp agent there and connect it to this Tenant. This text contains the tenant's access keys
so think twice before printing it to the screen or logs.
- integrations() -> returns an Integrations object representing all integrations on this Tenant.
- rba() -> returns an Rba object representing all runbook automation information for this Tenant.
- monitoring() -> returns a Monitoring object representing all monitoring information for this Tenant.
- policies() -> returns a Policies object representing the device management policies on this Tenant.
- clients() -> returns a Clients object representing all OpsRamp clients on this Tenant. _Note that
this is only valid for MSP-level tenants because an OpsRamp client cannot contain other clients._
- discovery() -> returns a Discovery object representing all OpsRamp Discovery profiles for this Tenant.
- credential\_sets() -> returns a Credential set object representing all OpsRamp Discovery profiles for this Tenant.
- permission\_sets() -> returns a PermissionSets object representing all OpsRamp RBAC permission sets for this Tenant.
- roles() -> returns a Roles object representing all OpsRamp RBAC roles for this Tenant.
- escalations() -> returns an Escalations object representing the Alert Escalation Policies of this Tenant.
- mgmt\_profiles() -> returns a Profiles object representing the Management Profiles of this Tenant. These are used
to connect OpsRamp gateway node to the SaaS.
- sites() -> returns a Sites object. Sites are used to organize devices based on location.
- service\_maps() -> returns a ServiceMaps object. Service maps are used to create directed graphs of dependencies
that are used in the OpsRamp UI to present human-readable graphs of the impact of service failures on each other.
- kb() -> returns a KnowledgeBase object. These are used to organize
knowledge base articles and categories related to this tenant.
- resources() -> returns a Resources object representing all OpsRamp resources on this Tenant
- first_response() -> returns an First_Response object representing the Alert First Response Policies of this Tenant
import opsramp.service\_maps
- class ServiceMaps() _the ServiceMaps that are defined for this specific Tenant_
- create(definition) -> Creates a new service map in this Tenant. "definition" is a Python dict.
- update(uuid, definition) -> Updates an existing service map
- delete(uuid) -> Deletes an existing service map
- get(uuid=None, minimal=False) -> returns a list of dicts, each one containing details for one service map.
import opsramp.roles
- class PermissionSets() _the RBAC permission sets that are defined for this specific Tenant_
- search(pattern) -> returns a list of dicts, each containing a single description.
- class Roles() _the subtree of RBAC roles that are defined for this specific Tenant_
- create(definition) -> Creates a new RBAC role in this Tenant. "definition" is a Python dict.
- update(uuid, definition) -> Updates an existing role.
- delete(uuid) -> Deletes an existing role.
- search(pattern) -> returns a list of dicts, each containing a single role description.
import opsramp.sites
- class Sites() _the subtree of Sites that are defined for this specific Tenant_
- create(definition) -> Creates a new site in this Tenant. "definition" is a Python dict.
- update(uuid, definition) -> Updates an existing site
- delete(uuid) -> Deletes an existing site
- search(pattern) -> returns a list of dicts, each containing a single site.
- get() -> returns a list of dicts, each one containing minimal details for one site.
import opsramp.monitoring
- class Monitoring() _the monitoring information subtree for one specific Tenant_
- templates() -> returns a Templates object representing the set of monitoring templates on this Tenant.
- class Templates() _the set of monitoring templates for one Tenant_
- search(pattern) -> returns a list of templates that match the pattern. See the OpsRamp API docs for details
on the format of the pattern string.
import opsramp.rba
- class Rba() _the runbook automation subtree of one specific Tenant_
- categories() -> the subtree containing the RBA categories of this Tenant
- class Categories() _the subtree for the RBA categories of one specific Tenant_
- get() -> Return a list of all the script categories in this Tenant RBA subtree.
- get(uuid) -> returns the definition of one specific category as a Python dict.
See the OpsRamp API docs for detailed contents of these dicts.
- create(name, optional parent\_uuid) -> creates a new *category* on this Tenant and
returns its uuid. Optionally takes the uuid of a pre-existing category under which to nest the new one.
- category(uuid) -> returns a Category object representing the API subtree for one specific category.
- update(uuid, definition) -> Updates an existing category
- delete(uuid) -> Deletes an existing category
- class Category() _the subtree for one RBA category_
- get() -> returns a list of the scripts in this category.
- get(uuid) -> returns the definition of one specific script as a Python dict.
See the OpsRamp API docs for detailed contents of these dicts.
- create(definition) -> creates a new *script* in this category. "definition" is a Python dict
specifying details of the script to be created. The content of these structs is complex so helper
functions for creating them are provided below.
- @staticmethod mkParameter(name, description, datatype, optional=False, default=None) -> helper function that returns a
Python dict describing one parameter of a proposed new script.
- @staticmethod mkScript(name, description, platforms, execution\_type, payload=None, payload\_file=None, parameters=[], script\_name=None, install\_timeout=0, registry\_path=None, registry\_value=None, process\_name=None, service\_name=None, output\_directory=None, output\_file=None) -> helper function that returns
a Python dict describing a proposed new script. There are lots of optional arguments because these structs
have variable content depending on the type of script and also some are only applicable on Linux, some only on Windows.
The function contains `assert` statements to flag violations of (some of) those rules.
I may add another layer of helpers later that are more specificially targetted (like "mkPythonLinuxScript" for example)
and implement those by calling mkScript() internally with appropriate arguments.
- update(uuid, definition) -> Updates an existing *script* in this category given the uuid of the script.The Python dict, "definition" is similar to the one used for create call and the helper functions used for create can be used for update too.
import opsramp.msp
- class Clients() _the subtree containing all clients of this MSP-level tenant_
An OpsRamp client cannot contain other clients so this is class is only useful with MSP-level tenants.
- get() -> returns a list of dicts, each one containing minimal details for one client. It's worth
noting that the main ID field in the objects that get returned is called *uniqueId* and this is the
value you need to use everywhere in this binding that a client ID is required.
- get(uuid) -> returns the definition of one specific client as a Python dict.
See the OpsRamp API docs for detailed contents of these dicts.
- search(self, pattern='') -> returns a list of client ids matching the specified search pattern, the format of
which is described in the OpsRamp documentation.
- create(definition) -> creates a new Client in this Tenant. "definition" is a Python dict
specifying details of the client to be created.
The content of these structs is complex so helper functions for creating them are provided below.
- update(uuid, definition) -> "definition" is a Python dict specifying the changes to be made to this client.
The contents are described in the OpsRamp docs and helper functions for creating these dicts are provided here.
- activate(uuid) -> marks the client as "active" in OpsRamp.
- suspend(uuid) -> marks the client as "suspended" in OpsRamp. _This takes 10+ seconds to run._
- terminate(uuid) -> terminates the client in OpsRamp. _The API docs say that this call deletes the client but in
reality it just goes onto an "inactive" list that is retrievable through the API and visible in the UI. OpsRamp
say that clients on the inactive list will get garbage collected eventually, but I couldn't get clarity on
how long "eventually" is._
- @staticmethod mkHours(day\_start=datetime.time(9, 0),
day\_end=datetime.time(17, 0),
week\_start=2, week\_end=6,
sms\_voice\_notification=False) -> returns a dict that can be used to define
customer working and opening hours in OpsRamp.
- @staticmethod mkClient(name, address, time\_zone, country, hours=None) -> returns a dict that can be
used to create a new client.
import opsramp.devmgmt
- class Policies() _the policies subtree of one specific Tenant_
- get() -> returns a list of dicts, each containing a single policy definition.
- get(uuid) -> returns the definition of one specific policy as a Python dict.
See the OpsRamp API docs for detailed contents of these dicts.
- search(pattern) -> Search for a policy with a specific name. The syntax is defined in the OpsRamp docs.
- create(definition) -> creates a new policy in this Tenant. "definition" is a Python dict
specifying details of the policy to be created.
The contents are described in the OpsRamp docs and helper functions for creating these dicts are provided here.
- update(uuid, definition) -> Updates an existing policy.
"definition" is a Python dict specifying the changes to be made.
The contents are described in the OpsRamp docs and helper functions for creating these dicts are provided here.
- run(uuid) -> sends a request to the OpsRamp server to run this policy now. _The actual run is asynchronous._
- delete(uuid) -> deletes this policy from the OpsRamp server.
- class Discovery() _the discovery profile subtree of one specific Tenant_
- search(pattern) -> returns a list of dicts, each containing a single discovery profile.
- create(definition) -> Creates a new discovery profile in this Tenant. "definition" is a Python dict.
- update(definition) -> Updates an existing discovery profile.
- rescan(discoveryProfileId) -> Causes a discovery profile to run.
- delete(discoveryProfileId) -> Deletes this discovery profile.
- class CredentialSets() _the Credential set subtree of one specific Tenant_
- get(credentialSetId, minimal) -> Returns a Credential set definition.
- create(definition) -> Creates a new Credential set in this Tenant.
- update(credentialSetId, definition) -> Update an existing Credential set.
- delete(credentialSetId) -> Delete a Credential set.
import opsramp.integrations
- class Integrations() _the integrations subtree of one specific Tenant_
- itypes() -> Returns a Types object describing all the *types*
of integrations that are available to be installed on this Tenant. Each
represents a *category* like CUSTOM, AZURE, rather than specific instances
of those.
- instances() -> Returns an Instances object representing all the actual
instances of integrations that are installed on this Tenant.
- _available() -> A synonym for "types()" that I included because that's
the name of the API endpoint in OpsRamp that returns this set of data.
It took a while to figure out what the returned data means though,
so we went with the more obvious name "types" here instead._
- _installed() -> A synonym for "instances()" that I included because that's
the name of the API endpoint in OpsRamp that returns this set of data.
It took a while to figure out what the returned data means though,
so we went with the more obvious name "instances" here instead._
- class Types() _a set of integration types_
- get() -> returns a list of dicts, each containing a single integration type.
- get(uuid) -> returns the definition of one specific type as a Python dict.
- search(pattern) -> Search for an integration type with a specific name or
other attributes. The syntax of the pattern is defined in the OpsRamp docs.
Returns a list of type definition dicts.
- class Instances() _the actual integration instances on one specific Tenant_
- get() -> returns a list of dicts, each containing a single integration instance.
- get(uuid) -> returns the definition of one specific integration instance as a Python dict.
- search(pattern) -> Search for existing integration instances with specific name or
other attributes. The syntax of the pattern is defined in the OpsRamp docs.
Returns a list of instance definition dicts.
- create(type\_name, definition) -> creates a new instance of a specific
integration type on this Tenant. "definition" is a Python dict specifying
details of the integration instance that is to be created.
The contents are described in the OpsRamp docs and helper functions for creating these dicts are provided here.
- update(definition) -> "definition" is a Python dict specifying the changes
to be made to this instance. The contents are described in the OpsRamp docs
and helper functions to construct them exist in the Integrations class.
- get\_kubernetes\_configuration(uuid) -> Returns the content of the Kubernetes
configuation file for a given integration as a string. Raises an exception if
that concept has no meaning for the type of integration specified.
- set\_auth\_type(self, auth\_type) -> sets the authentication type for this
integration to one of "OAUTH2", "WEBHOOK", "BASIC" and returns a dict that
contains the keys etc that are needed to connect to this integration using
that auth method. Note that OAUTH2 secret values are redacted by default in
the API response.
- enable(uuid) -> marks a specific instance as "enabled" in OpsRamp.
- disable(uuid) -> marks a specific instance as "disabled" in OpsRamp.
- notifier(uuid, definition) -> configures a notifier on one specific instance.
"definition" is a Python dict specifying details of the new configuration.
The syntax is defined in the OpsRamp docs. Helper functions for creating
these dicts will be added later.
- @staticmethod mkEmailAlert(display\_name, logo\_fname=None) ->
helper function that returns a Python dict suitable for creating or updating
an integration instance of type EMAILALERT.
- @staticmethod mkCustom(display\_name, logo\_fname=None, parent\_uuid=None, inbound\_auth\_type=None) ->
helper function that returns a Python dict suitable for creating or updating
an integration instance of type CUSTOM.
- @staticmethod mkAzureARM(display\_name, arm\_subscription\_id,
arm\_tenant\_id, arm\_client\_id, arm\_secret\_key) ->
helper function that returns a Python dict suitable for creating or updating
an integration instance of type AZUREARM. Note that ARM and ASM integrations
are different and each has its own helper function.
- @staticmethod mkAzureASM(display\_name, arm\_subscription\_id,
arm\_mgmt\_cert, arm\_keystore\_pass) ->
helper function that returns a Python dict suitable for creating or updating
an integration instance of type AZUREASM. Note that ARM and ASM integrations
are different and each has its own helper function.
- class Escalations() _the subtree of Alert Escalation Policies that are defined for this specific Tenant_
- create(definition) -> Creates a new escalation policy in this Tenant. "definition" is a Python dict.
- update(uuid, definition) -> Updates an existing escalation policy.
- delete(uuid) -> Deletes an existing escalation policy.
- search(pattern) -> returns a list of dicts, each containing a single policy.
- enable(uuid) -> marks a specific instance as "enabled" in OpsRamp.
- disable(uuid) -> marks a specific instance as "disabled" in OpsRamp.
- class Profiles() _the subtree of Management Profiles that are defined for this specific Tenant_
- create(definition) -> Creates a new mgmt profile in this Tenant. "definition" is a Python dict.
- update(uuid, definition) -> Updates an existing mgmt profile.
- delete(uuid) -> Deletes an existing mgmt profile.
- search(pattern) -> returns a list of dicts, each containing a single profile.
- attach(uuid) -> This is used to attach OpsRamp Gateway and returns an activation token.
- detach(uuid) -> Detach the existing gateway and invalidate its activation token.
- reconnect(uuid) -> Error recovery should happen automatically but this can be called
to "do it now". _It's unclear at this time in what circumstances this would be used._
- class KnowledgeBase() _the subtree of knowledge base that is defined for this specific Tenant_
- categories() -> Returns a KBcategories object representing the knowledge base
categories for this tenant.
- articles() -> Returns a KBarticles object representing the knowledge base
articles for this tenant.
- templates() -> Returns a KBtemplates object representing the knowledge base
templates for this tenant.
- class First_Response() _the subtree of Alert First Response Policies that are defined for this specific Tenant_
- create(definition) -> Creates a new first response policy in this Tenant. "definition" is a Python dict.
- policy_detail(uuid) -> returns the detaail for a specific first response policy
- update(uuid, definition) -> Updates an existing first response policy.
- delete(uuid) -> Deletes an existing first response policy.
- search(pattern) -> returns a list of dicts, each containing in a client.
- enable(uuid) -> marks a specific instance as "enabled" in OpsRamp.
- disable(uuid) -> marks a specific instance as "disabled" in OpsRamp.
- class KBcategories() _the subtree of knowledge base categories for this specific Tenant_
- create(definition) -> creates a KB category.
- update(uuid, definition) -> updates an existing KB category.
- delete(uuid) -> deletes an existing KB category.
- search(pattern) -> searches for categories matching a pattern.
- children(uuid) -> returns a list of the child categories of uuid.
- restore(uuid) -> undeletes category uuid (if it has not been
garbage collected yet).
- class KBarticles() _the subtree of knowledge base articles for this specific Tenant_
- create(definition) -> creates a KB article.
- update(uuid, definition) -> updates an existing KB article.
- delete(uuid) -> deletes an existing KB article.
- search(pattern) -> searches for articles matching a pattern.
- share(uuid) -> marks article uuid as "shared" _I don't know what that means_
- comments(uuid) -> returns a list of the comments on article uuid.
- class KBtemplates() _the subtree of knowledge base templates for this specific Tenant_
- create(definition) -> creates a KB template.
- update(uuid, definition) -> updates an existing KB template.
- delete(uuid) -> deletes an existing KB template.
- search(pattern) -> searches for templates matching a pattern.
import opsramp.resources
- class Resources() _the subtree of Resources that are defined for this specific Tenant_
- create(definition) -> Creates a new resource in this Tenant. "definition" is a Python dict.
- update(uuid, definition) -> updates an existing resource.
- delete(uuid) -> deletes an existing resource.
- search(pattern) -> searches for resources matching a pattern.
- minimal(pattern) -> similar to search but returns minimal details about each resource to
improve performance and reduce runtime. _This appears to work only on OpsRamp *clients.*_
- applications(uuid) -> This endpoint is used to fetch list of applications running on a resource.
- availability(uuid, start\_epoch, end\_epoch) -> fetch the availability details of a resource
within a specific time frame. The times are Unix epoch timestamps.
## Samples and examples
The `samples` subdirectory contains a series of short Python scripts illustrating
the use of most of the major API sections that we cover. These are supposed to be
self-explanatory so I will not document them in detail here. If any of the samples
are not obvious then please submit a PR that adds comments to the appropriate
source file explaining how it works, as an aid to other users.
All of the samples expect to be run as modules, like this:
```
ls -l samples/*.py
python3 -m samples.timezone_list
python3 -m samples.integration_list
python3 -m samples.category_list
python3 -m samples.client_list
... etc ...
```
### OpsRamp credentials
Each of the samples depends on the existence of some environment variables to tell it which OpsRamp
endpoint to use and the relevant creds. You can see those at the top of timezones.py
for example, and you must set them appropriately in your environment before running it.
```
export OPSRAMP_URL='https://my-org.api.try.opsramp.com'
export OPSRAMP_TENANT_ID='client_1234'
export OPSRAMP_KEY='whatever'
export OPSRAMP_SECRET='whatever'
```
The tenant id, key and secret are obtained from an "integration" in the OpsRamp UI.
You need to go to "setup", "integrations" and look for (or create) a row containing
a custom integration that uses OAUTH2. It doesn't matter what it's called, you just
need its id and creds to call the REST API.
On the list of integrations, click on the integration name in the appropriate row
and a screen appears with the "Tenant Id", "Key" and "Secret" fields that you need.
The UI even gives sample curl commands at the bottom and you can cut the URL value
out of those if it's not obvious. It's just the bit as far as opsramp.com like the
example above.
It's not obvious, but the creds you're getting here are for *the entire Tenant*
(aka client) and will be the same for all integrations on that Tenant. Be careful
with them, don't put them in logs or post them online by accident.
If there isn't a suitable integration already (or you want your own) then create a new
one by selecting the "other" tab in the Available Integrations section at the bottom
of the page and then "custom". Give it a name and leave the image file field blank.
The name will appear in access logs but otherwise has no real meaning. Select OAUTH2
as the authentication type and hit Save. This will bring you to the screen with keys
and curl commands etc as described above.
### examples.py
The file `examples.py` collects together a series of examples and illustrates most of
the major areas of the API that we cover. It uses the same environment variables as
the samples to tell it which OpsRamp tenant to examine.
`python3 -m opsramp.examples`
### Simple CLI prototype
I wrote a simple Python program that uses this binding to perform some simple
read-only operations on OpsRamp. Uses the same environment variables as above.
```
$ python3 -m opsramp.cli tenant rba categories | jq -S .
[
{
"id": 346,
"name": "Day to day actions"
},
{
"id": 698,
"name": "DR procedures"
}
]
$ python3 -m opsramp.cli tenant monitoring templates
538 monitoring templates found
$ python3 -m opsramp.cli tenant agent script | wc -l
763
$
```
## The API objects and direct REST calls
If we don't have a class that exposes the piece of the API that you want to use, then you can use the `ApiObject` base
class to make REST calls to that part directly while still using the correct wrapper classes for everything else.
The general approach would be to navigate to the nearest object for which we do have a wrapper and use its `api` property
to get an instance of the `ApiObject` class that you can then use to make direct REST calls to the tree below that point.
This still has an advantage over raw curl or "requests" calls because the enclosing object class will have set up the
URLs and access tokens for you.
### API object example
```
monitoring_api = ormp.tenant('client_9234').monitoring().api
result = monitoring_api.get('/templates')
print(result)
```
This uses a REST get() to retrieve the list of templates directly from OpsRamp, by starting from the api object
of a Monitoring object. The Monitoring object will have already done all the work to set up the correct tenant,
credentials and other context for that call so it's still much easier than making httplib, requests or curl
calls yourself.
- ApiObject() _an object representing some subtree of a REST API_
- get(suffix='', headers={}) -> performs a GET to the specified REST endpoint and returns the body of the
server's reply. "headers" is an optional dict containing any additional HTTP headers that you want to send
with the GET.
- post(suffix='', headers={}, data=None, json=None) -> performs a POST to the specified REST endpoint and
returns the body of the server's reply. "headers" is an optional dict containing any additional HTTP headers
that you want to send, "data" is the text body, or "json" is a Python struct to be converted to a JSON
string and sent as a body. _Specifying both "data" and "json" in the same call results in undefined behavior
and should be avoided._
- put(suffix='', headers={}, data=None, json=None) -> performs a PUT to the specified REST endpoint and
returns the body of the server's reply. "headers" is an optional dict containing any additional HTTP headers
that you want to send, "data" is the text body, or "json" is a Python struct to be converted to a JSON
string and sent as a body. _Specifying both "data" and "json" in the same call results in undefined behavior
and should be avoided._
- delete(suffix='', headers={}) -> performs a DELETE to the specified REST endpoint and returns the body of
the server's reply. "headers" is an optional dict containing any additional HTTP headers that you want to send.
- patch(suffix='', headers={}, data=None, json=None) -> performs a PATCH to the specified REST endpoint and
returns the body of the server's reply. "headers" is an optional dict containing any additional HTTP headers
that you want to send, "data" is the text body, or "json" is a Python struct to be converted to a JSON
string and sent as a body. _Specifying both "data" and "json" in the same call results in undefined behavior
and should be avoided._
- _we will add other http actions if/when a specific need for them arises_
Raw data
{
"_id": null,
"home_page": "https://github.com/HewlettPackard/python-opsramp",
"name": "python-opsramp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "opsramp",
"author": "HPE GreenLake SRE",
"author_email": "eemz@hpe.com",
"download_url": "https://files.pythonhosted.org/packages/19/34/4c5351b74f211f1000d93ad14a86d6933d458e3eedfcf7015134ba6affcd/python_opsramp-3.4.1.tar.gz",
"platform": null,
"description": "<!---\n(c) Copyright 2019-2021 Hewlett Packard Enterprise Development LP\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n-->\n# python-opsramp\nA Python language binding for the OpsRamp API\n\nCircleCI [](https://circleci.com/gh/HewlettPackard/python-opsramp)\nGitHub Actions [](https://github.com/HewlettPackard/python-opsramp/actions)\n\n## About\nThis directory tree contains a Python 3 module that provides a convenient way to\naccess the OpsRamp REST API programmatically. The OpsRamp API documentation is\nsomewhat opaque and this binding hides some of the details for exactly that reason.\nI have also added \"assert\" statements in various places to guard against pitfalls\nthat I ran into that are not obvious from the API docs.\n\n### Build\nThis repo includes standard Python packaging using pyproject.toml and setuptools.\nSource and wheel distributions can be built using `python3 -m build` in the usual way.\n\n### Scope\nThe basic framework of this library is in place and the\nscope has increased incrementally over time. The supplied samples\nexercise most of the main API sections and are described\nlater in this document.\n\nNote however that all of our wrapper objects also provide an `api` property that\ncan be used to access REST URLs further down the API tree\nwhere we have not written a specific wrapper class yet.\n\nWhile you can use these api objects to work directly with OpsRamp at a REST level,\nplease consider taking the small amount of time needed to add a proper wrapper class\nhere instead, for your own benefit and that of future users.\n\n### Return values\nAll functions in this binding return regular Python objects (not JSON strings).\nIn general you will need to look at the OpsRamp API docs to see exactly what\nsort of object and/fields the response will contain; typically we return exactly\nwhat the API gave us, or an equivalent Python object if it returned JSON.\n\n## Public Object Tree\nFollowing is a summary of the object tree currently available in this OpsRamp language binding. See\nthe \"Samples\" section later in this document for an illustration of how to use them.\n\nYou start by calling `opsramp.binding.connect()`\nwhich returns a single \"OpsRamp\" object to represent the entire REST API instance\nthat you want to access, and make a series of calls that return progressively lower level objects to access\nlower level information from OpsRamp. For clarity in these end-user instructions I have omitted several Python\nclasses that are internal implementation detail in the module and not intended for direct use by external callers.\n\nHere's an illustration of a simple use of the binding. See the Samples section for more detailed ones.\n```\nimport opsramp.binding\n\normp = opsramp.binding.connect(OPSRAMP_URL, KEY, SECRET)\ncfg = ormp.config()\nprint('alert types', cfg.get_alert_types())\nprint('timezones', cfg.get_timezones())\n```\n\n### Class diagram\nThis diagram is an overview of the public classes and their relationship to each other.\nThe individual classes are described in detail in the following section. This diagram\nwas produced using [Graphviz](https://www.graphviz.org/) `apt-get install graphviz`\nand to edit it you need to modify the\nsource file classes.dot and regenerate the PNG from that.\n\n`dot -Tpng < classes.dot > classes.png`\n\n\n\nI have used color to highlight the subset of classes that implement a \"create\" method.\n\n### Class definitions\n\nimport opsramp.binding\n\n- def connect(url, key, secret) _returns an instance of the class Opsramp that is connected to the specified API endpoint_\n This function posts a login request to the specified endpoint URL using the key and secret given. This post\n returns an access token, which the function uses to construct an Opsramp object and returns that.\n- class Opsramp(url, token) _an object representing the complete API tree of one OpsRamp instance_\n - config() -> returns a GlobalConfig object that can be used to access global settings for this OpsRamp instance.\n - tenant(uuid) -> returns a Tenant object representing the API subtree for one specific tenant.\n - metrics() -> returns a MetricsApi object that can be used to access the raw metrics api of this OpsRamp instance.\n\nimport opsramp.globalconfig\n\n- class GlobalConfig() _read-only access to global settings on this OpsRamp instance_\n - get\\_alert\\_types() -> returns a list of the global alert types that are defined on this OpsRamp instance.\n - get\\_channels() -> returns a list of the \"channels\" that are defined on this OpsRamp instance. See the OpsRamp docs for details.\n - get\\_countries() -> a list of dicts each describing one country known to this OpsRamp instance.\n - get\\_timezones() -> a list of dicts each describing one timezone known to this OpsRamp instance.\n - get\\_alert\\_technologies() -> a list of dicts each describing one alert technology known to this OpsRamp instance.\n - get\\_nocs() -> a list of dicts each describing one NOC known to this OpsRamp instance.\n - get\\_device\\_types() -> a list of dicts each describing device type known to this OpsRamp instance.\n\nimport opsramp.metrics\n\n- class MetricsApi() _the metrics API subtree for this OpsRamp instance_\n - get(pattern) -> returns metric definitions or time series values, depending on the pattern.\n This a raw interface to the GET portions of the OpsRamp metrics API and you should consult the OpsRamp\n documentation for the syntax that is permitted in pattern.\n - search(pattern) -> returns metric _time series_ values matching the pattern. These patterns\n can be quite complex and you should refer to the OpsRamp API documentation for the syntax.\n\nimport opsramp.tenant\n\n- class Tenant(uuid) _the API subtree for one specific tenant_\n - get\\_alert\\_script() -> Returns a string containing the appropriate Python script to run on a Linux node\n to install the OpsRamp agent there and connect it to this Tenant. This text contains the tenant's access keys\n so think twice before printing it to the screen or logs.\n - integrations() -> returns an Integrations object representing all integrations on this Tenant.\n - rba() -> returns an Rba object representing all runbook automation information for this Tenant.\n - monitoring() -> returns a Monitoring object representing all monitoring information for this Tenant.\n - policies() -> returns a Policies object representing the device management policies on this Tenant.\n - clients() -> returns a Clients object representing all OpsRamp clients on this Tenant. _Note that\n this is only valid for MSP-level tenants because an OpsRamp client cannot contain other clients._\n - discovery() -> returns a Discovery object representing all OpsRamp Discovery profiles for this Tenant.\n - credential\\_sets() -> returns a Credential set object representing all OpsRamp Discovery profiles for this Tenant.\n - permission\\_sets() -> returns a PermissionSets object representing all OpsRamp RBAC permission sets for this Tenant.\n - roles() -> returns a Roles object representing all OpsRamp RBAC roles for this Tenant.\n - escalations() -> returns an Escalations object representing the Alert Escalation Policies of this Tenant.\n - mgmt\\_profiles() -> returns a Profiles object representing the Management Profiles of this Tenant. These are used\n to connect OpsRamp gateway node to the SaaS.\n - sites() -> returns a Sites object. Sites are used to organize devices based on location.\n - service\\_maps() -> returns a ServiceMaps object. Service maps are used to create directed graphs of dependencies\n that are used in the OpsRamp UI to present human-readable graphs of the impact of service failures on each other.\n - kb() -> returns a KnowledgeBase object. These are used to organize\n knowledge base articles and categories related to this tenant.\n - resources() -> returns a Resources object representing all OpsRamp resources on this Tenant\n - first_response() -> returns an First_Response object representing the Alert First Response Policies of this Tenant\n\nimport opsramp.service\\_maps\n\n- class ServiceMaps() _the ServiceMaps that are defined for this specific Tenant_\n - create(definition) -> Creates a new service map in this Tenant. \"definition\" is a Python dict.\n - update(uuid, definition) -> Updates an existing service map\n - delete(uuid) -> Deletes an existing service map\n - get(uuid=None, minimal=False) -> returns a list of dicts, each one containing details for one service map.\n\nimport opsramp.roles\n\n- class PermissionSets() _the RBAC permission sets that are defined for this specific Tenant_\n - search(pattern) -> returns a list of dicts, each containing a single description.\n\n- class Roles() _the subtree of RBAC roles that are defined for this specific Tenant_\n - create(definition) -> Creates a new RBAC role in this Tenant. \"definition\" is a Python dict.\n - update(uuid, definition) -> Updates an existing role.\n - delete(uuid) -> Deletes an existing role.\n - search(pattern) -> returns a list of dicts, each containing a single role description.\n\nimport opsramp.sites\n\n- class Sites() _the subtree of Sites that are defined for this specific Tenant_\n - create(definition) -> Creates a new site in this Tenant. \"definition\" is a Python dict.\n - update(uuid, definition) -> Updates an existing site\n - delete(uuid) -> Deletes an existing site\n - search(pattern) -> returns a list of dicts, each containing a single site.\n - get() -> returns a list of dicts, each one containing minimal details for one site.\n\nimport opsramp.monitoring\n\n- class Monitoring() _the monitoring information subtree for one specific Tenant_\n - templates() -> returns a Templates object representing the set of monitoring templates on this Tenant.\n\n- class Templates() _the set of monitoring templates for one Tenant_\n - search(pattern) -> returns a list of templates that match the pattern. See the OpsRamp API docs for details\n on the format of the pattern string.\n\nimport opsramp.rba\n\n- class Rba() _the runbook automation subtree of one specific Tenant_\n - categories() -> the subtree containing the RBA categories of this Tenant\n\n- class Categories() _the subtree for the RBA categories of one specific Tenant_\n - get() -> Return a list of all the script categories in this Tenant RBA subtree.\n - get(uuid) -> returns the definition of one specific category as a Python dict.\n See the OpsRamp API docs for detailed contents of these dicts.\n - create(name, optional parent\\_uuid) -> creates a new *category* on this Tenant and\n returns its uuid. Optionally takes the uuid of a pre-existing category under which to nest the new one.\n - category(uuid) -> returns a Category object representing the API subtree for one specific category.\n - update(uuid, definition) -> Updates an existing category\n - delete(uuid) -> Deletes an existing category\n\n- class Category() _the subtree for one RBA category_\n - get() -> returns a list of the scripts in this category.\n - get(uuid) -> returns the definition of one specific script as a Python dict.\n See the OpsRamp API docs for detailed contents of these dicts.\n - create(definition) -> creates a new *script* in this category. \"definition\" is a Python dict\n specifying details of the script to be created. The content of these structs is complex so helper\n functions for creating them are provided below.\n - @staticmethod mkParameter(name, description, datatype, optional=False, default=None) -> helper function that returns a\n Python dict describing one parameter of a proposed new script.\n - @staticmethod mkScript(name, description, platforms, execution\\_type, payload=None, payload\\_file=None, parameters=[], script\\_name=None, install\\_timeout=0, registry\\_path=None, registry\\_value=None, process\\_name=None, service\\_name=None, output\\_directory=None, output\\_file=None) -> helper function that returns\n a Python dict describing a proposed new script. There are lots of optional arguments because these structs\n have variable content depending on the type of script and also some are only applicable on Linux, some only on Windows.\n The function contains `assert` statements to flag violations of (some of) those rules.\n I may add another layer of helpers later that are more specificially targetted (like \"mkPythonLinuxScript\" for example)\n and implement those by calling mkScript() internally with appropriate arguments.\n - update(uuid, definition) -> Updates an existing *script* in this category given the uuid of the script.The Python dict, \"definition\" is similar to the one used for create call and the helper functions used for create can be used for update too.\n\nimport opsramp.msp\n\n- class Clients() _the subtree containing all clients of this MSP-level tenant_\n An OpsRamp client cannot contain other clients so this is class is only useful with MSP-level tenants.\n - get() -> returns a list of dicts, each one containing minimal details for one client. It's worth\n noting that the main ID field in the objects that get returned is called *uniqueId* and this is the\n value you need to use everywhere in this binding that a client ID is required.\n - get(uuid) -> returns the definition of one specific client as a Python dict.\n See the OpsRamp API docs for detailed contents of these dicts.\n - search(self, pattern='') -> returns a list of client ids matching the specified search pattern, the format of\n which is described in the OpsRamp documentation.\n - create(definition) -> creates a new Client in this Tenant. \"definition\" is a Python dict\n specifying details of the client to be created.\n The content of these structs is complex so helper functions for creating them are provided below.\n - update(uuid, definition) -> \"definition\" is a Python dict specifying the changes to be made to this client.\n The contents are described in the OpsRamp docs and helper functions for creating these dicts are provided here.\n - activate(uuid) -> marks the client as \"active\" in OpsRamp.\n - suspend(uuid) -> marks the client as \"suspended\" in OpsRamp. _This takes 10+ seconds to run._\n - terminate(uuid) -> terminates the client in OpsRamp. _The API docs say that this call deletes the client but in\n reality it just goes onto an \"inactive\" list that is retrievable through the API and visible in the UI. OpsRamp\n say that clients on the inactive list will get garbage collected eventually, but I couldn't get clarity on\n how long \"eventually\" is._\n - @staticmethod mkHours(day\\_start=datetime.time(9, 0),\n day\\_end=datetime.time(17, 0),\n week\\_start=2, week\\_end=6,\n sms\\_voice\\_notification=False) -> returns a dict that can be used to define\n customer working and opening hours in OpsRamp.\n - @staticmethod mkClient(name, address, time\\_zone, country, hours=None) -> returns a dict that can be\n used to create a new client.\n\nimport opsramp.devmgmt\n\n- class Policies() _the policies subtree of one specific Tenant_\n - get() -> returns a list of dicts, each containing a single policy definition.\n - get(uuid) -> returns the definition of one specific policy as a Python dict.\n See the OpsRamp API docs for detailed contents of these dicts.\n - search(pattern) -> Search for a policy with a specific name. The syntax is defined in the OpsRamp docs.\n - create(definition) -> creates a new policy in this Tenant. \"definition\" is a Python dict\n specifying details of the policy to be created.\n The contents are described in the OpsRamp docs and helper functions for creating these dicts are provided here.\n - update(uuid, definition) -> Updates an existing policy.\n \"definition\" is a Python dict specifying the changes to be made.\n The contents are described in the OpsRamp docs and helper functions for creating these dicts are provided here.\n - run(uuid) -> sends a request to the OpsRamp server to run this policy now. _The actual run is asynchronous._\n - delete(uuid) -> deletes this policy from the OpsRamp server.\n\n- class Discovery() _the discovery profile subtree of one specific Tenant_\n - search(pattern) -> returns a list of dicts, each containing a single discovery profile.\n - create(definition) -> Creates a new discovery profile in this Tenant. \"definition\" is a Python dict.\n - update(definition) -> Updates an existing discovery profile.\n - rescan(discoveryProfileId) -> Causes a discovery profile to run.\n - delete(discoveryProfileId) -> Deletes this discovery profile.\n\n- class CredentialSets() _the Credential set subtree of one specific Tenant_\n - get(credentialSetId, minimal) -> Returns a Credential set definition.\n - create(definition) -> Creates a new Credential set in this Tenant.\n - update(credentialSetId, definition) -> Update an existing Credential set.\n - delete(credentialSetId) -> Delete a Credential set.\n\nimport opsramp.integrations\n\n- class Integrations() _the integrations subtree of one specific Tenant_\n - itypes() -> Returns a Types object describing all the *types*\n of integrations that are available to be installed on this Tenant. Each\n represents a *category* like CUSTOM, AZURE, rather than specific instances\n of those.\n - instances() -> Returns an Instances object representing all the actual\n instances of integrations that are installed on this Tenant.\n - _available() -> A synonym for \"types()\" that I included because that's\n the name of the API endpoint in OpsRamp that returns this set of data.\n It took a while to figure out what the returned data means though,\n so we went with the more obvious name \"types\" here instead._\n - _installed() -> A synonym for \"instances()\" that I included because that's\n the name of the API endpoint in OpsRamp that returns this set of data.\n It took a while to figure out what the returned data means though,\n so we went with the more obvious name \"instances\" here instead._\n\n- class Types() _a set of integration types_\n - get() -> returns a list of dicts, each containing a single integration type.\n - get(uuid) -> returns the definition of one specific type as a Python dict.\n - search(pattern) -> Search for an integration type with a specific name or\n other attributes. The syntax of the pattern is defined in the OpsRamp docs.\n Returns a list of type definition dicts.\n\n- class Instances() _the actual integration instances on one specific Tenant_\n - get() -> returns a list of dicts, each containing a single integration instance.\n - get(uuid) -> returns the definition of one specific integration instance as a Python dict.\n - search(pattern) -> Search for existing integration instances with specific name or\n other attributes. The syntax of the pattern is defined in the OpsRamp docs.\n Returns a list of instance definition dicts.\n - create(type\\_name, definition) -> creates a new instance of a specific\n integration type on this Tenant. \"definition\" is a Python dict specifying\n details of the integration instance that is to be created.\n The contents are described in the OpsRamp docs and helper functions for creating these dicts are provided here.\n - update(definition) -> \"definition\" is a Python dict specifying the changes\n to be made to this instance. The contents are described in the OpsRamp docs\n and helper functions to construct them exist in the Integrations class.\n - get\\_kubernetes\\_configuration(uuid) -> Returns the content of the Kubernetes\n configuation file for a given integration as a string. Raises an exception if\n that concept has no meaning for the type of integration specified.\n - set\\_auth\\_type(self, auth\\_type) -> sets the authentication type for this\n integration to one of \"OAUTH2\", \"WEBHOOK\", \"BASIC\" and returns a dict that\n contains the keys etc that are needed to connect to this integration using\n that auth method. Note that OAUTH2 secret values are redacted by default in\n the API response.\n - enable(uuid) -> marks a specific instance as \"enabled\" in OpsRamp.\n - disable(uuid) -> marks a specific instance as \"disabled\" in OpsRamp.\n - notifier(uuid, definition) -> configures a notifier on one specific instance.\n \"definition\" is a Python dict specifying details of the new configuration.\n The syntax is defined in the OpsRamp docs. Helper functions for creating\n these dicts will be added later.\n - @staticmethod mkEmailAlert(display\\_name, logo\\_fname=None) ->\n helper function that returns a Python dict suitable for creating or updating\n an integration instance of type EMAILALERT.\n - @staticmethod mkCustom(display\\_name, logo\\_fname=None, parent\\_uuid=None, inbound\\_auth\\_type=None) ->\n helper function that returns a Python dict suitable for creating or updating\n an integration instance of type CUSTOM.\n - @staticmethod mkAzureARM(display\\_name, arm\\_subscription\\_id,\n arm\\_tenant\\_id, arm\\_client\\_id, arm\\_secret\\_key) ->\n helper function that returns a Python dict suitable for creating or updating\n an integration instance of type AZUREARM. Note that ARM and ASM integrations\n are different and each has its own helper function.\n - @staticmethod mkAzureASM(display\\_name, arm\\_subscription\\_id,\n arm\\_mgmt\\_cert, arm\\_keystore\\_pass) ->\n helper function that returns a Python dict suitable for creating or updating\n an integration instance of type AZUREASM. Note that ARM and ASM integrations\n are different and each has its own helper function.\n\n- class Escalations() _the subtree of Alert Escalation Policies that are defined for this specific Tenant_\n - create(definition) -> Creates a new escalation policy in this Tenant. \"definition\" is a Python dict.\n - update(uuid, definition) -> Updates an existing escalation policy.\n - delete(uuid) -> Deletes an existing escalation policy.\n - search(pattern) -> returns a list of dicts, each containing a single policy.\n - enable(uuid) -> marks a specific instance as \"enabled\" in OpsRamp.\n - disable(uuid) -> marks a specific instance as \"disabled\" in OpsRamp.\n \n- class Profiles() _the subtree of Management Profiles that are defined for this specific Tenant_\n - create(definition) -> Creates a new mgmt profile in this Tenant. \"definition\" is a Python dict.\n - update(uuid, definition) -> Updates an existing mgmt profile.\n - delete(uuid) -> Deletes an existing mgmt profile.\n - search(pattern) -> returns a list of dicts, each containing a single profile.\n - attach(uuid) -> This is used to attach OpsRamp Gateway and returns an activation token.\n - detach(uuid) -> Detach the existing gateway and invalidate its activation token.\n - reconnect(uuid) -> Error recovery should happen automatically but this can be called\n to \"do it now\". _It's unclear at this time in what circumstances this would be used._\n\n- class KnowledgeBase() _the subtree of knowledge base that is defined for this specific Tenant_\n - categories() -> Returns a KBcategories object representing the knowledge base\n categories for this tenant.\n - articles() -> Returns a KBarticles object representing the knowledge base\n articles for this tenant.\n - templates() -> Returns a KBtemplates object representing the knowledge base\n templates for this tenant.\n\n- class First_Response() _the subtree of Alert First Response Policies that are defined for this specific Tenant_\n - create(definition) -> Creates a new first response policy in this Tenant. \"definition\" is a Python dict.\n - policy_detail(uuid) -> returns the detaail for a specific first response policy\n - update(uuid, definition) -> Updates an existing first response policy.\n - delete(uuid) -> Deletes an existing first response policy.\n - search(pattern) -> returns a list of dicts, each containing in a client.\n - enable(uuid) -> marks a specific instance as \"enabled\" in OpsRamp.\n - disable(uuid) -> marks a specific instance as \"disabled\" in OpsRamp. \n\n- class KBcategories() _the subtree of knowledge base categories for this specific Tenant_\n - create(definition) -> creates a KB category.\n - update(uuid, definition) -> updates an existing KB category.\n - delete(uuid) -> deletes an existing KB category.\n - search(pattern) -> searches for categories matching a pattern.\n - children(uuid) -> returns a list of the child categories of uuid.\n - restore(uuid) -> undeletes category uuid (if it has not been\n garbage collected yet).\n\n- class KBarticles() _the subtree of knowledge base articles for this specific Tenant_\n - create(definition) -> creates a KB article.\n - update(uuid, definition) -> updates an existing KB article.\n - delete(uuid) -> deletes an existing KB article.\n - search(pattern) -> searches for articles matching a pattern.\n - share(uuid) -> marks article uuid as \"shared\" _I don't know what that means_\n - comments(uuid) -> returns a list of the comments on article uuid.\n\n- class KBtemplates() _the subtree of knowledge base templates for this specific Tenant_\n - create(definition) -> creates a KB template.\n - update(uuid, definition) -> updates an existing KB template.\n - delete(uuid) -> deletes an existing KB template.\n - search(pattern) -> searches for templates matching a pattern.\n\nimport opsramp.resources\n\n- class Resources() _the subtree of Resources that are defined for this specific Tenant_\n - create(definition) -> Creates a new resource in this Tenant. \"definition\" is a Python dict.\n - update(uuid, definition) -> updates an existing resource.\n - delete(uuid) -> deletes an existing resource.\n - search(pattern) -> searches for resources matching a pattern.\n - minimal(pattern) -> similar to search but returns minimal details about each resource to\n improve performance and reduce runtime. _This appears to work only on OpsRamp *clients.*_\n - applications(uuid) -> This endpoint is used to fetch list of applications running on a resource.\n - availability(uuid, start\\_epoch, end\\_epoch) -> fetch the availability details of a resource\n within a specific time frame. The times are Unix epoch timestamps.\n\n## Samples and examples\nThe `samples` subdirectory contains a series of short Python scripts illustrating\nthe use of most of the major API sections that we cover. These are supposed to be\nself-explanatory so I will not document them in detail here. If any of the samples\nare not obvious then please submit a PR that adds comments to the appropriate\nsource file explaining how it works, as an aid to other users.\n\nAll of the samples expect to be run as modules, like this:\n```\nls -l samples/*.py\npython3 -m samples.timezone_list\npython3 -m samples.integration_list\npython3 -m samples.category_list\npython3 -m samples.client_list\n... etc ...\n```\n\n### OpsRamp credentials\nEach of the samples depends on the existence of some environment variables to tell it which OpsRamp\nendpoint to use and the relevant creds. You can see those at the top of timezones.py\nfor example, and you must set them appropriately in your environment before running it.\n```\nexport OPSRAMP_URL='https://my-org.api.try.opsramp.com'\nexport OPSRAMP_TENANT_ID='client_1234'\nexport OPSRAMP_KEY='whatever'\nexport OPSRAMP_SECRET='whatever'\n```\nThe tenant id, key and secret are obtained from an \"integration\" in the OpsRamp UI.\nYou need to go to \"setup\", \"integrations\" and look for (or create) a row containing\na custom integration that uses OAUTH2. It doesn't matter what it's called, you just\nneed its id and creds to call the REST API.\n\nOn the list of integrations, click on the integration name in the appropriate row\nand a screen appears with the \"Tenant Id\", \"Key\" and \"Secret\" fields that you need.\nThe UI even gives sample curl commands at the bottom and you can cut the URL value\nout of those if it's not obvious. It's just the bit as far as opsramp.com like the\nexample above.\n\nIt's not obvious, but the creds you're getting here are for *the entire Tenant*\n(aka client) and will be the same for all integrations on that Tenant. Be careful\nwith them, don't put them in logs or post them online by accident.\n\nIf there isn't a suitable integration already (or you want your own) then create a new\none by selecting the \"other\" tab in the Available Integrations section at the bottom\nof the page and then \"custom\". Give it a name and leave the image file field blank.\nThe name will appear in access logs but otherwise has no real meaning. Select OAUTH2\nas the authentication type and hit Save. This will bring you to the screen with keys\nand curl commands etc as described above.\n\n### examples.py\nThe file `examples.py` collects together a series of examples and illustrates most of\nthe major areas of the API that we cover. It uses the same environment variables as\nthe samples to tell it which OpsRamp tenant to examine.\n\n`python3 -m opsramp.examples`\n\n### Simple CLI prototype\nI wrote a simple Python program that uses this binding to perform some simple\nread-only operations on OpsRamp. Uses the same environment variables as above.\n```\n$ python3 -m opsramp.cli tenant rba categories | jq -S .\n[\n {\n \"id\": 346,\n \"name\": \"Day to day actions\"\n },\n {\n \"id\": 698,\n \"name\": \"DR procedures\"\n }\n]\n$ python3 -m opsramp.cli tenant monitoring templates\n538 monitoring templates found\n$ python3 -m opsramp.cli tenant agent script | wc -l\n763\n$\n```\n\n## The API objects and direct REST calls\nIf we don't have a class that exposes the piece of the API that you want to use, then you can use the `ApiObject` base\nclass to make REST calls to that part directly while still using the correct wrapper classes for everything else.\n\nThe general approach would be to navigate to the nearest object for which we do have a wrapper and use its `api` property\nto get an instance of the `ApiObject` class that you can then use to make direct REST calls to the tree below that point.\nThis still has an advantage over raw curl or \"requests\" calls because the enclosing object class will have set up the\nURLs and access tokens for you.\n\n### API object example\n```\nmonitoring_api = ormp.tenant('client_9234').monitoring().api\nresult = monitoring_api.get('/templates')\nprint(result)\n```\nThis uses a REST get() to retrieve the list of templates directly from OpsRamp, by starting from the api object\nof a Monitoring object. The Monitoring object will have already done all the work to set up the correct tenant,\ncredentials and other context for that call so it's still much easier than making httplib, requests or curl\ncalls yourself.\n\n- ApiObject() _an object representing some subtree of a REST API_\n - get(suffix='', headers={}) -> performs a GET to the specified REST endpoint and returns the body of the\n server's reply. \"headers\" is an optional dict containing any additional HTTP headers that you want to send\n with the GET.\n - post(suffix='', headers={}, data=None, json=None) -> performs a POST to the specified REST endpoint and\n returns the body of the server's reply. \"headers\" is an optional dict containing any additional HTTP headers\n that you want to send, \"data\" is the text body, or \"json\" is a Python struct to be converted to a JSON\n string and sent as a body. _Specifying both \"data\" and \"json\" in the same call results in undefined behavior\n and should be avoided._\n - put(suffix='', headers={}, data=None, json=None) -> performs a PUT to the specified REST endpoint and\n returns the body of the server's reply. \"headers\" is an optional dict containing any additional HTTP headers\n that you want to send, \"data\" is the text body, or \"json\" is a Python struct to be converted to a JSON\n string and sent as a body. _Specifying both \"data\" and \"json\" in the same call results in undefined behavior\n and should be avoided._\n - delete(suffix='', headers={}) -> performs a DELETE to the specified REST endpoint and returns the body of\n the server's reply. \"headers\" is an optional dict containing any additional HTTP headers that you want to send.\n - patch(suffix='', headers={}, data=None, json=None) -> performs a PATCH to the specified REST endpoint and\n returns the body of the server's reply. \"headers\" is an optional dict containing any additional HTTP headers\n that you want to send, \"data\" is the text body, or \"json\" is a Python struct to be converted to a JSON\n string and sent as a body. _Specifying both \"data\" and \"json\" in the same call results in undefined behavior\n and should be avoided._\n - _we will add other http actions if/when a specific need for them arises_\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Python language binding for the Opsramp API",
"version": "3.4.1",
"project_urls": {
"Homepage": "https://github.com/HewlettPackard/python-opsramp"
},
"split_keywords": [
"opsramp"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c7b3d2945ff9d1eeba6238ec7632af2e25e7e6095cae79ef2dc3b52a13b3d900",
"md5": "f55b778604700e504ddd4e8f1eb0f11e",
"sha256": "9bcd692d203afde69502dd0e621fddbee408bfdaf9d8e591222434efb77dcdc5"
},
"downloads": -1,
"filename": "python_opsramp-3.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f55b778604700e504ddd4e8f1eb0f11e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 45405,
"upload_time": "2024-08-01T22:12:54",
"upload_time_iso_8601": "2024-08-01T22:12:54.679218Z",
"url": "https://files.pythonhosted.org/packages/c7/b3/d2945ff9d1eeba6238ec7632af2e25e7e6095cae79ef2dc3b52a13b3d900/python_opsramp-3.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "19344c5351b74f211f1000d93ad14a86d6933d458e3eedfcf7015134ba6affcd",
"md5": "ad605f4952af60cbe54d474efc1bf59e",
"sha256": "f89a490780f534a3a7bb3caf498c2774172d858a4ec1a4f93d406cef0ba4ef1d"
},
"downloads": -1,
"filename": "python_opsramp-3.4.1.tar.gz",
"has_sig": false,
"md5_digest": "ad605f4952af60cbe54d474efc1bf59e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 305305,
"upload_time": "2024-08-01T22:12:57",
"upload_time_iso_8601": "2024-08-01T22:12:57.627549Z",
"url": "https://files.pythonhosted.org/packages/19/34/4c5351b74f211f1000d93ad14a86d6933d458e3eedfcf7015134ba6affcd/python_opsramp-3.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-01 22:12:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HewlettPackard",
"github_project": "python-opsramp",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"circle": true,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "simplejson",
"specs": []
},
{
"name": "urllib3",
"specs": []
}
],
"tox": true,
"lcname": "python-opsramp"
}
JSON
