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.
StreamsConnection
is the entry point to using the Streams REST API
from Python. 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
StreamingAnalyticsConnection |
Creates a connection to a running Streaming Analytics service and exposes methods to retrieve the state of the service and its instance. |
StreamsConnection |
Creates a connection to a running distributed IBM Streams instance and exposes methods to retrieve the state of that instance. |
-
class
streamsx.rest.
StreamingAnalyticsConnection
(vcap_services=None, service_name=None)¶ 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: Domain
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: Instance
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: StreamingAnalyticsService
-
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: StreamingAnalyticsConnection
-
resource_url
¶ str – Root URL for IBM Streams REST API
-
class
streamsx.rest.
StreamsConnection
(username=None, password=None, resource_url=None)¶ 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 the
- environment variable. If the STREAMS_USERNAME environment variable is not set, (STREAMS_USERNAME) –
- default streamsadmin is used. (the) –
- password (str) – Password for username
- None, the password is taken from the STREAMS_PASSWORD environment variable. If the (If) –
- environment variable is not set, the default passw0rd is used. (STREAMS_PASSWORD) –
- resource_url (str, optional) – Root URL for IBM Streams REST API.
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
– Requests session object for making REST calls.
-
get_domain
(id)¶ Retrieves available domain matching a specific domain ID
Parameters: id (str) – domain ID Returns: Domain matching id Return type: Domain
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: Instance
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
-
resource_url
¶ str – Root URL for IBM Streams REST API