streamsx.rest¶
REST API bindings for IBM® Streams & Streaming Analytics service.
Streams REST API¶
The Streams REST API provides programmatic access to configuration and status information for IBM Streams objects such as domains, instances, and jobs.
IBM Cloud Pak for Data (Streams 5)¶
Integrated configuration within project¶
of_service()
is the entry point to using the Streams REST API bindings,
returning an Instance
.
The configuration required to connect is obtained from ipcd_util.get_service_details
passing in the IBM Streams service instance name.
Integrated & standalone configurations¶
of_endpoint()
is the entry point
to using the Streams REST API bindings, returning an Instance
.
IBM Streams On-premises (4.2, 4.3)¶
StreamsConnection
is the entry point to using the Streams REST API bindings.
Through its functions and the returned objects status information
can be obtained for items such as instances
and jobs
.
Streaming Analytics REST API¶
You can use the Streaming Analytics REST API to manage your service instance and the IBM Streams jobs that are running on the instance. The Streaming Analytics REST API is accessible from IBM Cloud applications that are bound to your service instance or from an application outside of IBM Cloud that is configured with the service instance VCAP information.
StreamingAnalyticsConnection
is the entry point to using the
Streaming Analytics REST API. The function get_streaming_analytics()
returns a StreamingAnalyticsService
instance which is the wrapper around the Streaming Analytics REST API. This API allows functions such as start
and stop
the service instance.
In addition StreamingAnalyticsConnection extends from StreamsConnection
and thus provides access to the Streams REST API for the service instance.
See also
- IBM Streams REST API overview
Reference documentation for the Streams REST API.
- Streaming Analytics REST API
Reference documentation for the Streaming Analytics service REST API.
See also
Module contents¶
Classes
Creates a connection to a running Streaming Analytics service and exposes methods to retrieve the state of the service and its instance. |
|
Creates a connection to a running distributed IBM Streams instance and exposes methods to retrieve the state of that instance. |
-
class
streamsx.rest.
StreamsConnection
(username=None, password=None, resource_url=None, auth=None)¶ Bases:
streamsx.rest._AbstractStreamsConnection
Creates a connection to a running distributed IBM Streams instance and exposes methods to retrieve the state of that instance.
Streams maintains information regarding the state of its resources. For example, these resources could include the currently running Jobs, Views, PEs, Operators, and Domains. The
StreamsConnection
provides methods to retrieve that information.- Parameters
username (str) – Username of an authorized Streams user. If
None
, the username is taken from theSTREAMS_USERNAME
environment variable. If theSTREAMS_USERNAME
environment variable is not set, the default streamsadmin is used.password (str) – Password for username If
None
, the password is taken from theSTREAMS_PASSWORD
environment variable. If theSTREAMS_PASSWORD
environment variable is not set, the default passw0rd is used to match the Streams Quick Start edition setup.resource_url (str) – Root URL for IBM Streams REST API. If
None
, the URL is taken from theSTREAMS_REST_URL
environment variable. If theREST_URL
environment variable is not set, thenstreamtool geturl --api
is used to obtain the URL.
Example
>>> resource_url = "https://streamsqse.localdomain:8443/streams/rest/resources" >>> sc = StreamsConnection("streamsadmin", "passw0rd", resource_url) >>> sc.session.verify=False # manually disable SSL verification, if needed >>> instances = sc.get_instances() >>> jobs_count = 0 >>> for instance in instances: >>> jobs_count += len(instance.get_jobs()) >>> print("There are {} jobs across all instances.".format(jobs_count)) There are 10 jobs across all instances.
-
session
¶ Requests session object for making REST calls.
- Type
requests.Session
-
get_domain
(id)¶ Retrieves available domain matching a specific domain ID
- Parameters
id (str) – domain ID
- Returns
Domain matching id
- Return type
- Raises
ValueError – No matching domain exists.
-
get_domains
()¶ Retrieves available domains.
- Returns
List of available domains
- Return type
list
ofDomain
-
get_installations
()¶ Retrieves a list of all known Streams installations.
- Returns
List of all Installation resources.
- Return type
list
ofInstallation
-
get_instance
(id)¶ Retrieves available instance matching a specific instance ID.
- Parameters
id (str) – Instance identifier to retrieve.
- Returns
Instance matching id.
- Return type
- Raises
ValueError – No matching instance exists or multiple matching instances exist.
-
get_instances
()¶ Retrieves available instances.
- Returns
List of available instances
- Return type
list
ofInstance
-
get_resources
()¶ Retrieves a list of all known Streams high-level REST resources.
- Returns
List of all Streams high-level REST resources.
- Return type
list
ofRestResource
-
property
resource_url
¶ Root URL for IBM Streams REST API
- Type
str
-
class
streamsx.rest.
StreamingAnalyticsConnection
(vcap_services=None, service_name=None)¶ Bases:
streamsx.rest.StreamsConnection
Creates a connection to a running Streaming Analytics service and exposes methods to retrieve the state of the service and its instance.
- Parameters
vcap_services (str, optional) – VCAP services (JSON string or a filename whose content contains a JSON string). If not specified, it uses the value of VCAP_SERVICES environment variable.
service_name (str, optional) – Name of the Streaming Analytics service. If not specified, it uses the value of STREAMING_ANALYTICS_SERVICE_NAME environment variable.
Example
>>> # Assume environment variable VCAP_SERVICES has correct information >>> sc = StreamingAnalyticsConnection(service_name='Streaming-Analytics') >>> print(sc.get_streaming_analytics().get_instance_status()) {'plan': 'Standard', 'state': 'STARTED', 'enabled': True, 'status': 'running'}
-
get_domain
(id)¶ Retrieves available domain matching a specific domain ID
- Parameters
id (str) – domain ID
- Returns
Domain matching id
- Return type
- Raises
ValueError – No matching domain exists.
-
get_domains
()¶ Retrieves available domains.
- Returns
List of available domains
- Return type
list
ofDomain
-
get_installations
()¶ Retrieves a list of all known Streams installations.
- Returns
List of all Installation resources.
- Return type
list
ofInstallation
-
get_instance
(id)¶ Retrieves available instance matching a specific instance ID.
- Parameters
id (str) – Instance identifier to retrieve.
- Returns
Instance matching id.
- Return type
- Raises
ValueError – No matching instance exists or multiple matching instances exist.
-
get_instances
()¶ Retrieves available instances.
- Returns
List of available instances
- Return type
list
ofInstance
-
get_resources
()¶ Retrieves a list of all known Streams high-level REST resources.
- Returns
List of all Streams high-level REST resources.
- Return type
list
ofRestResource
-
get_streaming_analytics
()¶ Returns a
StreamingAnalyticsService
to allow further interaction with the Streaming Analytics service.- Returns
Object for interacting with the Streaming Analytics service.
- Return type
-
static
of_definition
(service_def)¶ Create a connection to a Streaming Analytics service.
The single service is defined by service_def which can be one of
The service credentials copied from the Service credentials page of the service console (not the Streams console). Credentials are provided in JSON format. They contain such as the API key and secret, as well as connection information for the service.
A JSON object (dict) of the form:
{ "type": "streaming-analytics", "name": "service name", "credentials": {...} }
with the service credentials as the value of thecredentials
key.
- Parameters
service_def (dict) – Definition of the service to connect to.
- Returns
Connection to defined service.
- Return type
-
property
resource_url
¶ Root URL for IBM Streams REST API
- Type
str