Services

Note

Some services are limited to only running in a Cloud Foundry environment (PostgreSQL, Blob Store) but others can be reached from anywhere connectivity is available (Time Series, Asset) on the edge or your workstation.

App Manifest

The App Manifest is an approach to configuring your application for deployment to platforms based on Cloud Foundry such as Predix. The Administration Apps allow you to automate the management of your space through the creation of services with a side-effect of generating a manifest configuration file.

The mechanics of this are described in the Getting Started section.

App Manifest API

class predix.app.Manifest(manifest_path='manifest.yml', app_name='my-predix-app', manifest_key='~/.predix/manifest_key', encrypted=False, debug=False)

Cloud Foundry utilizes a MANIFEST.yml file as the source of application configuration. As we setup services and run our applications the manifest is a place to store important configuration details.

Parameters:
  • app_name – the name of your application which will be used by default in the route
  • manifest_key – if encrypting your manifest this is the key for cryptography
  • encrypted – whether to manifest values should be encrypted
  • debug – enable additional debugging
add_env_var(key, value)

Add the given key / value as another environment variable.

add_service(service_name)

Add the given service to the manifest.

create_manifest()

Create a new manifest and write it to disk.

get_acs()

Returns an instance of the Asset Control Service.

get_asset()

Returns an instance of the Asset Service.

get_client_id()

Return the client id that should have all the needed scopes and authorities for the services in this manifest.

get_client_secret()

Return the client secret that should correspond with the client id.

get_manifest_version()

Returns the version of PredixPy used to generate the manifest.

get_timeseries(*args, **kwargs)

Returns an instance of the Time Series Service.

get_uaa()

Returns an insstance of the UAA Service.

get_weather()

Returns an instance of the Weather Service.

read_manifest(encrypted=None)

Read an existing manifest.

set_os_environ()

Will load any environment variables found in the manifest file into the current process for use by applications.

When apps run in cloud foundry this would happen automatically.

write_manifest(manifest_path=None, encrypted=None)

Write manifest to disk.

Parameters:
  • manifest_path – write to a different location
  • encrypted – write with env data encrypted

Admin App Manifest API

class predix.admin.app.Manifest(*args, **kwargs)

Extends Application Manifest with administrative functions for creating and configuring services.

create_acs(**kwargs)

Creates an instance of the Asset Service.

create_asset(**kwargs)

Creates an instance of the Asset Service.

create_blobstore(**kwargs)

Creates an instance of the BlobStore Service.

create_cache(**kwargs)

Creates an instance of the Cache Service.

create_client(client_id=None, client_secret=None, uaa=None)

Create a client and add it to the manifest.

Parameters:
  • client_id – The client id used to authenticate as a client in UAA.
  • client_secret – The secret password used by a client to authenticate and generate a UAA token.
  • uaa – The UAA to create client with
create_dbaas(**kwargs)
create_eventhub(**kwargs)

todo make it so the client can be customised to publish/subscribe Creates an instance of eventhub service

create_logstash(**kwargs)

Creates an instance of the Logging Service.

create_manifest_from_space()

Populate a manifest file generated from details from the cloud foundry space environment.

create_timeseries(**kwargs)

Creates an instance of the Time Series Service.

create_uaa(admin_secret, **kwargs)

Creates an instance of UAA Service.

Parameters:admin_secret – The secret password for administering the service such as adding clients and users.
create_weather(**kwargs)

Creates an instance of the Asset Service.

get_service_marketplace(available=True, unavailable=False, deprecated=False)

Returns a list of service names. Can return all services, just those supported by PredixPy, or just those not yet supported by PredixPy.

Parameters:
  • available – Return the services that are available in PredixPy. (Defaults to True)
  • unavailable – Return the services that are not yet supported by PredixPy. (Defaults to False)
  • deprecated – Return the services that are supported by PredixPy but no longer available. (True)
lock_to_org_space()

Lock the manifest to the current organization and space regardless of Cloud Foundry target.

User Accounts and Authentication

The User Accounts and Authentication Service, known as UAA, is an OAuth2 implementation common in Cloud Foundry deployments. You can learn more about it from the UAA catalog page and official documentation.

Hint

You will need UAA to work with most Predix services including Asset, Time Series, and ACS.

Example

Here is a simple demo to create a uaa instance, create a client, authenticate as the client, and print out the scopes.

# How-To Create the Service

import predix.admin.app
admin = predix.admin.app.Manifest()
admin.create_uaa('admin-secret')
admin.create_client('my-client', 'my-client-secret')
# How-To Use the Service

import predix.app
app = predix.app.Manifest()
uaa = app.get_uaa()
uaa.authenticate('my-client', 'my-client-secret')
print(uaa.get_scopes())

Find more examples with UAA Recipes.

Authentication

Is the username and password provided correct?

If so, those credentials can be authenticated and a token generated for proving that the identify is verified. This token is used in any subsequent service calls in the header of those requests. The Predix Python SDK takes care of this transparently for you.

The username and password can be provided by an actual end “user”, an application that is a “client”, or the “admin” user managing your cloud foundry space.

Expiration

The token is only valid for a period of time so the Predix Python SDK tries to manage this and only requests a new token if you explicitly logout a session to invalidate a token or if you reach the expiration period.

Authorization

That authenticated token, is it allowed to talk to this other service?

Cloud Foundry and UAA have a sophisticated system of managing scopes and authorities for what a user or client are able to do. Since most services only support coarse grained permissions such as read/write the Predix Python SDK manages the details with a grant_client() method for each service. If any options are meaningful they are generally exposed.

UAA API

class predix.security.uaa.UserAccountAuthentication(uri=None, *args, **kwargs)

The UAA service manages user account authorization and access control for Predix service calls through client credentials captured in a bearer token.

Parameters:uri – URI for the UAA endpoint to interact with, can be derived from environment PREDIX_SECURITY_UAA_URI variable when not specified.

Useful documentation about interacting with API - https://docs.cloudfoundry.org/api/uaa

And more documentation - https://github.com/cloudfoundry/uaa/tree/master/docs

add_client_to_manifest(client_id, client_secret, manifest)

Add the given client / secret to the manifest for use in the application.

assert_has_permission(scope_required)

Warn that the required scope is not found in the scopes granted to the currently authenticated user.

# The admin user should have client admin permissions
uaa.assert_has_permission('admin', 'clients.admin')
authenticate(client_id, client_secret, use_cache=True)

Authenticate the given client against UAA. The resulting token will be cached for reuse.

create_client(client_id, client_secret, manifest=None, client_credentials=True, refresh_token=True, authorization_code=False, redirect_uri=[])

Will create a new client for your application use.

  • client_credentials: allows client to get access token
  • refresh_token: can be used to get new access token when expired without re-authenticating
  • authorization_code: redirection-based flow for user authentication

More details about Grant types: - https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-Security.md - https://tools.ietf.org/html/rfc6749

A redirect_uri is required when using authorization_code. See: https://www.predix.io/support/article/KB0013026

create_user(username, password, family_name, given_name, primary_email, details={})

Creates a new user account with the required details.

create_user('j12y', 'my-secret', 'Delancey', 'Jayson', 'volcano@ge.com')
delete_user(id)

Delete user with given id.

get_authorization_headers()

Returns the authorization headers with the bearer token needed for making calls to Predix Services protected by UAA.

get_client(client_id)

Returns details about a specific client by the client_id.

get_clients()

Returns the clients stored in the instance of UAA.

get_scopes()

Returns the scopes for the authenticated client.

get_token()

Returns the bare access token for the authorized client.

get_user(id)

Returns details about the user for the given id.

Use get_user_by_email() or get_user_by_username() for help identifiying the id.

get_user_by_email(email)

Returns details for user with the given email address.

If there is more than one match will only return the first. Use get_users() for full result set.

get_user_by_username(username)

Returns details for user of the given username.

If there is more than one match will only return the first. Use get_users() for full result set.

get_userinfo()

Retrieve user info for currently authenticated user.

get_users(filter=None, sortBy=None, sortOrder=None, startIndex=None, count=None)

Returns users accounts stored in UAA. See https://docs.cloudfoundry.org/api/uaa/#list63

For filtering help, see: http://www.simplecloud.info/specs/draft-scim-api-01.html#query-resources

grant_client_permissions(client_id, admin=False, write=False, read=False, secret=False)

Grant the given client_id permissions for managing clients.

  • clients.admin: super user scope to create, modify, delete
  • clients.write: scope ot create and modify clients
  • clients.read: scope to read info about clients
  • clients.secret: scope to change password of a client
grant_scim_permissions(client_id, read=False, write=False, create=False, userids=False, zones=False, invite=False, openid=False)

Grant the given client_id permissions for managing users. System for Cross-domain Identity Management (SCIM) are required for accessing /Users and /Groups endpoints of UAA.

  • scim.read: scope for read access to all SCIM endpoints
  • scim.write: scope for write access to all SCIM endpoints
  • scim.create: scope to create/invite users and verify an account only
  • scim.userids: scope for id and username+origin conversion
  • scim.zones: scope for group management of users only
  • scim.invite: scope to participate in invitations
  • openid: scope to access /userinfo
is_admin()

Test whether user is authenticated as the admin.

is_expired_token(client)

For a given client will test whether or not the token has expired.

This is for testing a client object and does not look up from client_id. You can use _get_client_from_cache() to lookup a client from client_id.

logout()

Log currently authenticated user out, invalidating any existing tokens.

update_client_grants(client_id, scope=[], authorities=[], grant_types=[], redirect_uri=[], replace=False)

Will extend the client with additional scopes or authorities. Any existing scopes and authorities will be left as is unless asked to replace entirely.

UAA Administration

class predix.admin.uaa.UserAccountAuthentication(plan_name=None, name=None, *args, **kwargs)

User Account and Authentication Serice (UAA) provides user management for Cloud Foundry.

A few helpful notes: - You must already be logged into a CF target environment - There can only be 10 instances of UAA within an org

add_client_to_manifest(client_id, client_secret, manifest)

Add the client credentials to the specified manifest.

add_to_manifest(manifest)

Add useful details to the manifest about this service so that it can be used in an application.

Parameters:manifest – An predix.admin.app.Manifest object instance that manages reading/writing manifest config for a cloud foundry app.
authenticate()

Authenticate into the UAA instance as the admin user.

create(secret, **kwargs)

Create a new instance of the UAA service. Requires a secret password for the ‘admin’ user account.

create_client(client_id, client_secret)

Create a new client for use by applications.

exists()

Tests whether this given service already exists.

Access Control

The Access Control Service, known as ACS, is a fine-grained access control system common in complex dynamic industrial settings. You can learn more about it from the ACS catalog page and official documentation.

Example

Here is a simple demo to create an acs instance and a basic use example of creating subjects and resources.

# How-To Create the Service
# IMPORTANT: You must have already configured UAA and client

import predix.admin.app
admin = predix.admin.app.Manifest()
admin.create_acs()
# How-To Use the Service

import predix.app
app = predix.app.Manifest()
acs = app.get_acs()
acs.add_subject('/user/j12y', {'username': 'j12y', 'role': 'devangelist'})
acs.add_subject('/user/jflannery', {'username': 'jflannery', 'role': 'ceo'})
acs.add_resource('/asset/12', {'manufacturer': 'GE Digital'})

Find more examples with ACS Recipes.

Authorization

I have lots of data in my system, for any specific piece of data is a given subject allowed to operate on it?

ACS uses attributes assigned to subjects and resources to determine authorization for a resource. It does not handle authentication, only whether access should be granted to read, write, delete, etc. a resource by a given subject.

What is a subject? A subject could be a user or a machine. It has properties and attributes we know about it and can be assigned a unique uri to identify it.

What is a resource? A resource could be a service, a piece of data, or an asset. It too has properties like subjects do and has a unique uri.

If you consider well known commercial systems like Box, Dropbox, or Google Drive – subjects are the users that have logged in and the resources are the shared documents that the subject may be able to read or write.

Policies

ACS maintains its own cache of subject and resource attributes in order to evaluate policies. Policies define a specification for what resources and subjects are impacted and what condition must be met.

The condition is a groovy expression so you can have sophisticated access evaluation criteria if your application needs it.

Where UAA provides coarse-grained policies for whether a service is available to a client at all, ACS helps provide the fine-grained per-data level of flexibility that can be handled in a scalable way for sophistated permission schemes needed in complex organizational structures.

ACS API

class predix.security.acs.AccessControl(uri=None, zone_id=None, *args, **kwargs)

Use the Access Control service to provide a more powerful authorization framework than basic User Account and Authorization (UAA) service.

Access Control service provides app-specific policies without adding overhead to a UAA server that may become the entry point for several apps over time.

Parameters:
  • uri – The URI endpoint for accessing the ACS service instance.
  • zone_id – The Predix-Zone-Id assigned to the tenant for the ACS

service instance.

add_policy(name, action, resource, subject, condition, policy_set_id=None, effect='PERMIT')

Will create a new policy set to enforce the given policy details.

The name is just a helpful descriptor for the policy.

The action maps to a HTTP verb.

Policies are evaluated against resources and subjects. They are identified by matching a uriTemplate or attributes.

Examples:

resource = {
    "uriTemplate": "/asset/{id}"
    }

subject: {
    "attributes": [{
        "issuer": "default",
        "name": "role"
        }]
    }

The condition is expected to be a string that defines a groovy operation that can be evaluated.

Examples:

condition = "match.single(subject.attributes('default', 'role'),
    'admin')
add_resource(resource_id, attributes, parents=[], issuer='default')

Will add the given resource with a given identifier and attribute dictionary.

example/

add_resource(‘/asset/12’, {‘id’: 12, ‘manufacturer’: ‘GE’})
add_subject(subject_id, attributes, parents=[], issuer='default')

Will add the given subject with a given identifier and attribute dictionary.

example/

add_subject(‘/user/j12y’, {‘username’: ‘j12y’})
authenticate_as_client(client_id, client_secret)

Will authenticate for the given client / secret.

delete_policy_set(policy_set_id)

Delete a specific policy set by id. Method is idempotent.

delete_resource(resource_id)

Remove a specific resource by its identifier.

delete_subject(subject_id)

Remove a specific subject by its identifier.

get_policy_sets()

Return all of the policy sets in the ACS service.

get_resource(resource_id)

Returns a specific resource by resource id.

get_resources()

Return all of the resources in the ACS service.

get_subject(subject_id)

Returns a specific subject by subject id.

get_subjects()

Return all of the subjects in the ACS service.

is_alive()

Will test whether the ACS service is up and alive.

is_allowed(subject_id, action, resource_id, policy_sets=[])

Evaluate a policy-set against a subject and resource.

example/

is_allowed(‘/user/j12y’, ‘GET’, ‘/asset/12’)

ACS Administration

class predix.admin.acs.AccessControl(name=None, plan_name=None, uaa=None, *args, **kwargs)

Access Control provides attribute based access control.

add_to_manifest(manifest)

Add useful details to the manifest about this service so that it can be used in an application.

Parameters:manifest – An predix.admin.app.Manifest object instance that manages reading/writing manifest config for a cloud foundry app.
create()

Create an instance of the Access Control Service with the typical starting settings.

exists()

Returns whether or not this service already exists.

grant_client(client_id)

Grant the given client id all the scopes and authorities needed to work with the access control service.

Asset

The Predix Asset Service provides a persistent store for graph data about physical assets, their properties, and relationships. You can learn more about it from the Asset catalog page and official documentation.

Example

Here is a simple demo to create and use the Predix Asset service.

# How-To Create the Service
# IMPORTANT: You must have already configured UAA and client

import predix.admin.app
admin = predix.admin.app.Manifest()
admin.create_asset()
# How-To Use the Service

import predix.app
app = predix.app.Manifest()
asset = app.get_asset()

volcano = {
    'uri': '/volcano/masaya',
    'name': 'Masaya',
    'location': {
        'lat': 11.98531829999,
        'long': -86.1783429000,
    },
    'description': 'Near Masaya, Nicaragua',
}
asset.post_collection('/volcano', [volcano])
print(asset.get_collection('/volcano/masaya'))

Find more examples with Asset Recipes.

Asset Collections

Assets are organized into collections and the Predix Python SDK attempts to help manage collections with an AssetCollections class that acts for doing object relationship mapping to marshall Python Domain objects into the Predix Asset Service.

Asset API

class predix.data.asset.Asset(uri=None, zone_id=None, *args, **kwargs)

Client library for working with the Predix Asset Service. For more details on use of the service please see official docs: https://www.predix.io/services/service.html?id=1171

authenticate_as_client(client_id, client_secret)

Will authenticate for the given client / secret.

create_guid(collection=None)

Returns a new guid for use in posting a new asset to a collection.

delete_collection(collection)

Deletes an existing collection.

The collection being updated is expected to include the id.

get_audit()

Return audit report for asset. Disabled by default.

get_audit_changes()

Return change log for audit. Disabled by default.

get_audit_snapshots()

Return an audit snapshot. Disabled by default.

get_collection(collection, filter=None, fields=None, page_size=None)

Returns a specific collection from the asset service with the given collection endpoint.

Supports passing through parameters such as… - filters such as “name=Vesuvius” following GEL spec - fields such as “uri,description” comma delimited - page_size such as “100” (the default)

get_collections()

Returns a flat list of the names of collections in the asset service.

[‘wind-turbines’, ‘jet-engines’]
get_configs()

Return the configuration for the asset service.

get_messages()

Return any system messages related to asset systems.

get_scripts()

Return any configured scripts for asset service.

get_triggers()

Return configured triggers in the asset system.

patch_collection(collection, changes)

Will make specific updates to a record based on JSON Patch documentation.

the format of changes is something like:

[{
    'op': 'add',
    'path': '/newfield',
    'value': 'just added'
}]
post_collection(collection, body)

Creates a new collection. This is mostly just transport layer and passes collection and body along. It presumes the body already has generated.

The collection is not expected to have the id.

put_collection(collection, body)

Updates an existing collection.

The collection being updated is expected to include the id.

save(collection)

Save an asset collection to the service.

class predix.data.asset.AssetCollection(parent=None, guid=None, *args, **kwargs)

User Defined Domain Objects are the customizable collections to represent data in the Asset Service.

This is experimental to provide a base class for a sort of ORM between domain objects to marshall and unmarshall between Python and the REST endpoints.

validate()

If an asset collection wants any client-side validation the object can override this method and it is called anytime we’re saving.

Asset Administration

class predix.admin.asset.Asset(plan_name=None, name=None, uaa=None, *args, **kwargs)

Asset Service provides asset management functionality.

add_to_manifest(manifest)

Add useful details to the manifest about this service so that it can be used in an application.

Parameters:manifest – An predix.admin.app.Manifest object instance that manages reading/writing manifest config for a cloud foundry app.
create()

Create an instance of the Asset Service with the typical starting settings.

exists()

Returns whether or not this service already exists.

grant_client(client_id)

Grant the given client id all the scopes and authorities needed to work with the asset service.

Time Series

The Time Series Service is a persistent store for a series of data points over time such as sensor data.

You can learn more from the Time Series catalog page and official documentation.

Example

Here is a simple demo to create a time series instance and a basic use example of sending data.

# How-To Create the service
# IMPORTANT: You must have already configured UAA and client

import predix.admin.app
admin = predix.admin.app.Manifest()
admin.create_timeseries()
# How-To Use the Service

import predix.app
app = predix.app.Manifest()
timeseries = app.get_timeseries()
timeseries.send('TEMP', 72)

Find more examples with TimeSeries Recipes.

Tags and Values

The minimum you need for adding data to Predix Time Series is a tag and a value. The value will typically be a numerical value and the tag a simple string label for the type of data.

Predix Time Series also requires

Quality and Attributes

Every data point must also have a quality designation. By default the SDK will assign it as UNCERTAIN and there are constants for the various values.

Attributes are also optional, but any Python dictionary with simple data types will be marshalled into Predix Time Series. You may want to include things like URIs for the assets or sensors being observed.

Time Series API

class predix.data.timeseries.TimeSeries(read=True, write=True, query_uri=None, ingest_uri=None, query_zone_id=None, ingest_zone_id=None, *args, **kwargs)

Client library for working with the Time Series service.

Parameters:
  • query_uri – URI for Time Series endpoint to execute queries, can be derived from environment PREDIX_TIMESERIES_QUERY_URI variable if not passed.
  • ingest_uri – URI for Time Series endpoint to ingest data, can be derived from environment PREDIX_TIMESERIES_INGEST_URI variable if not passed.
  • query_zone_id – Predix-Zone-Id for Query Authorization, can be derived from environment PREDIX_TIMESERIES_QUERY_ZONE_ID.
  • ingest_zone_id – Predix-Zone-Id for Ingest Authorization, can be derived from environment PREDIX_TIMESERIES_INGEST_ZONE_ID.
  • read – Whether we expect to be able to query / read data.
  • write – Whether we expect to be able to ingest / write data.

Learn more about Predix Time Series: https://www.predix.io/services/service.html?id=1177

authenticate_as_client(client_id, client_secret)

Will authenticate for the given client / secret.

get_aggregations()

Returns all of the aggregations that can be used with the Time Series Service.

get_datapoints(tags, start=None, end=None, order=None, limit=None, qualities=None, attributes=None, measurement=None, aggregations=None, post=False)

Returns all of the datapoints that match the given query.

  • tags: list or string identifying the name/tag (ie. “temp”)
  • start: data after this, absolute or relative (ie. ‘1w-ago’ or 1494015972386)
  • end: data before this value
  • order: ascending (asc) or descending (desc)
  • limit: only return a few values (ie. 25)
  • qualities: data quality value (ie. [ts.GOOD, ts.UNCERTAIN])
  • attributes: data attributes (ie. {‘unit’: ‘mph’})
  • measurement: tuple of operation and value (ie. (‘gt’, 30))
  • aggregations: summary statistics on data results (ie. ‘avg’)
  • post: POST query instead of GET (caching implication)
A few additional observations:
  • allow service to do most data validation
  • order is applied before limit so resultset will differ

The returned results match what the service response is so you’ll need to unpack it as appropriate. Oftentimes what you want for a simple single tag query will be:

response[‘tags’][0][‘results’][0][‘values’]
get_latest(tags, post=False)

Similar to get_datapoints() but will only return the very last datapoint ingested for the given tag or tags (if a list).

If given the optional post parameter will make the call as a POST rather than a GET request. The GET can have an advantage of url based response caching and the POST has the advantage of a larger and more complex query.

get_tags()

Returns a list of the tag names in the timeseries service instance.

get_values(*args, **kwargs)

Convenience method that for simple single tag queries will return just the values to be iterated on.

is_bad(quality)

Simple test if data quality value is BAD.

is_good(quality)

Simple test if data quality is GOOD.

queue(name, value, quality=None, timestamp=None, attributes=None)

To reduce network traffic, you can buffer datapoints and then flush() anything in the queue.

Parameters:
  • name – the name / label / tag for sensor data
  • value – the sensor reading or value to record
  • quality – the quality value, use the constants BAD, GOOD, etc. (optional and defaults to UNCERTAIN)
  • timestamp – the time the reading was recorded in epoch milliseconds (optional and defaults to now)
  • attributes – dictionary for any key-value pairs to store with the reading (optional)
send(name=None, value=None, **kwargs)

Can accept a name/tag and value to be queued and then send anything in the queue to the time series service. Optional parameters include setting quality, timestamp, or attributes.

See spec for queue() for complete list of options.

Example of sending a batch of values:

queue(‘temp’, 70.1) queue(‘humidity’, 20.4) send()

Example of sending one and flushing queue immediately

send(‘temp’, 70.3) send(‘temp’, 70.4, quality=ts.GOOD, attributes={‘unit’: ‘F’})

Time Series Administration

class predix.admin.timeseries.TimeSeries(plan_name=None, name=None, uaa=None, *args, **kwargs)

Time Series provides persistence of data values over time.

add_to_manifest(manifest)

Add useful details to the manifest about this service so that it can be used in an application.

Parameters:manifest – An predix.admin.app.Manifest object instance that manages reading/writing manifest config for a cloud foundry app.
create()

Create an instance of the Time Series Service with the typical starting settings.

exists()

Returns whether or not this service already exists.

get_ingest_uri()

Return the uri used for ingesting data into time series

get_ingest_zone_id()

Returns the Predix-Zone-Id used for ingesting data with this service.

get_query_uri()

Return the uri used for queries on time series data.

get_query_zone_id()

Return the Predix-Zone-Id used for queries on data with this service.

grant_client(client_id, read=True, write=True)

Grant the given client id all the scopes and authorities needed to work with the timeseries service.

Blob Store

The Blob Store Service is a persistent store for binary large objects such as files and images. You can learn more from the Blob Store catalog page and official documentation.

Example

Here is a simple demo to create a blob store instance and basic use example of listing files.

# How-To Create the service
# IMPORTANT: You must have already configured UAA and client

import predix.admin.app
admin = predix.admin.app.Manifest()
admin.create_blobstore()
# How-To Use the Service
# IMPORTANT: this must be run in Cloud Foundry so
# this example is using Flask methods

import predix.app
app = predix.app.Manifest()
blobstore = app.get_blobstore()

@api.route('/list')
def list():
    objs = blobstore.list_objects()
    return jsonify(objs)

Find more examples with BlobStore Recipes (including the rest of the code for this example).

Boto 3

For US-WEST on AWS all the functionality of Boto 3 is exposed by referencing blobstore.client. You can find more about those methods directly from the Boto3 Documentation:

https://boto3.readthedocs.io/

Blob Store API

class predix.data.blobstore.BlobStore(host=None, access_key_id=None, secret_access_key=None, bucket_name=None, *args, **kwargs)

The BlobStore is the place to store Binary Large Objects, ie. files that could be images, csv files, cad files, pdf files, etc.

Important

This service will only work from the Predix Cloud – Firewall will block any traffic not originating from within the Predix environment.

Underlying BlobStore is the AWS S3 service so you will need to be familiar with the boto3 library from AWS to learn how to work with buckets. A few methods are provided for common patterns you can use for reference.

Parameters:host – Host address for blob store.
list_buckets(*args, **kwargs)

This method is primarily for illustration and just calls the boto3 client implementation of list_buckets directly but is a common task for first time Predix BlobStore users.

list_objects(bucket_name=None, **kwargs)

This method is primarily for illustration and just calls the boto3 client implementation of list_objects but is a common task for first time Predix BlobStore users.

upload_file(src_filepath, dest_filename=None, bucket_name=None, **kwargs)

This method is primarily for illustration and just calls the boto3 client implementation of upload_file but is a common task for first time Predix BlobStore users.

Blob Store Administration

class predix.admin.blobstore.BlobStore(plan_name=None, name=None, uaa=None, *args, **kwargs)

Blob Store for binary large object storage.

add_to_manifest(manifest)

Add useful details to the manifest about this service so that it can be used in an application.

Parameters:manifest – An predix.admin.app.Manifest object instance that manages reading/writing manifest config for a cloud foundry app.
create(**kwargs)

Create an instance of the Blob Store Service with the typical starting settings.

exists()

Returns whether or not this service already exists.

Predix Cache

The Predix Cache Service provides an instance of Redis, key-value memory store, for use in building applications. You can learn more about it from the Predix Cache catalog page and official documentation.

Hint

You will need to push an app to the Predix Cloud to make use of this service since firewall access is blocked otherwise.

Example

Here is a simple demo to create the service.

# How-To Create the service

import predix.admin.app
admin = predix.admin.app.Manifest()
admin.create_cache()

Find more examples in Predix Cache Recipes.

Predix Cache API

class predix.data.cache.Cache(host=None, port=None, password=None, *args, **kwargs)

A simple Key-Value in memory data store (Redis).

Important

This service will only work from the Predix Cloud – Firewall will block any traffic not originating from within the Predix environment. If you attempt you’ll likely see a ConnectionError Error 60 with Operation timed out.

For more information about Predix Cache see the catalog and official documentation.

https://www.predix.io/services/service.html?id=1215

get(key)

Return the value stored for the given key.

set(key, value)

Set the given key to the given value.

Predix Cache Administration

class predix.admin.cache.Cache(plan_name=None, name=None, uaa=None, *args, **kwargs)

Predix Cache key-value persistent storage.

add_to_manifest(manifest)

Add useful details to the manifest about this service so that it can be used in an application.

Parameters:manifest – A predix.admin.app.Manifest object instance that manages reading/writing manifest config for a cloud foundry app.
create(max_wait=180, **kwargs)

Create an instance of the Predix Cache Service with they typical starting settings.

Parameters:max_wait – service is created asynchronously, so will only wait this number of seconds before giving up.
exists()

Returns whether or not this service already exists.

Predix DBaaS

The Predix Database as a Service provides an instance of PostgreSQL, a relational database management system for persisting data needed in building applications. You can learn more about it from the Predix Database as a Service catalog page and official documentation.

Hint

You will need to push an app to the Predix Cloud to make use of this service since firewall access is blocked otherwise.

Example

Here is a simple demo to create and use the service.

# How-To Create the service

import predix.admin.app
admin = predix.admin.app.Manifest()
admin.create_dbaas()
# How-To Use the service

import predix.data.dbaas
psql = predix.data.dbaas.PostgreSQL()
rs = psql.execute('SELECT * FROM foo')
for row in rs:
    print(str.join(',', row))

Find more examples in Predix DBaaS Recipes.

Predix DBaaS API

class predix.data.dbaas.PostgreSQL(hostname=None, port=None, username=None, password=None, database=None, *args, **kwargs)

A Relational Database Management System on demand (PostgreSQL).

Important

This service will only work from the Predix Cloud – Firewall will block any traffic not originating from within the Predix environment. If you attempt you’ll likely see a ConnectionError Error 60 with Operation timed out.

For more information about Predix Database as a Service see the catalog and official documentation.

https://www.predix.io/services/service.html?id=1178

execute(statement, *args, **kwargs)

This convenience method will execute the query passed in as is. For more complex functionality you may want to use the sqlalchemy engine directly, but this serves as an example implementation.

Parameters:select_query – SQL statement to execute that will identify the resultset of interest.

Predix DBaaS Administration

class predix.admin.dbaas.PostgreSQL(plan_name=None, name=None, uaa=None, *args, **kwargs)

Predix Database as a Service provides a relational database management system (PostgreSQL) for data persistence.

add_to_manifest(manifest)

Add useful details to the manifest about this service so that it can be used in an application.

Parameters:manifest – A predix.admin.app.Manifest object instance that manages reading/writing manifest config for a cloud foundry app.
create(max_wait=300, allocated_storage=None, encryption_at_rest=None, restore_to_time=None, **kwargs)

Create an instance of the PostgreSQL service with the typical starting settings.

Parameters:
  • max_wait – service is created asynchronously, so will only wait this number of seconds before giving up.
  • allocated_storage – int for GBs to be allocated for storage
  • encryption_at_rest – boolean for encrypting data that is stored
  • restore_to_time – UTC date within recovery period for db backup to be used when initiating
exists()

Returns whether or not this service already exists.

Event Hub

Event Hub uses gRPC for publishing and subscribing messages. A full-duplex streaming RPC framework, gRPC uses protocol buffers for wire protocol implemented over HTTP/2 and using header compression, multiplexing TCP connections, and flow control. Protocol Buffers is a binary protocol further suited for IoT devices that publish high-velocity data over networks with low bandwidth.

For more details see the official Event Hub service documentation.

Example

Here is a simple demo to create a service instance.

# How-To Create the service
# IMPORTANT: You must have already configured UAA and client

import predix.admin.app
admin = predix.admin.app.Manifest()
admin.create_eventhub(publish=True, subscribe=True)
# How-To Publish Messages

import predix.app
app = predix.app.Manifest()
eh = app.get_eventhub()

acks = {}
for i in range(10, 0, -1):
    msg_id = str(i)
    msg_body = 'Hello World {}'.format(msg_id)
    eh.publisher.add_message(msg_id, msg_body)

    acks[msg_id] = False

print("Publishing messages.")
eh.publisher.publish_queue()

for response in eh.publisher.ack_generator():
    for ack in response.ack:
        msg_id = ack.id
        print("Message {} acknowledged.".format(msg_id))
        del acks[msg_id]

    if not acks.keys():
        print("All messages delivered.")
        break
# How-To Subscribe Messages

import predix.app
app = predix.app.Manifest()
eh = app.get_eventhub()

for msg in eh.subscriber.subscribe():
    print(msg)

Find more examples Event Hub Recipes.

Event Hub API

Event Hub Administration

class predix.admin.eventhub.EventHub(plan_name=None, name=None, uaa=None, *args, **kwargs)

Event Hub is a publisher/subscriber framework for getting information in, out and around the predix cloud

add_to_manifest(manifest)

Add useful details to the manifest about this service so that it can be used in an application.

Parameters:manifest – An predix.admin.app.Manifest object instance that manages reading/writing manifest config for a cloud foundry app.
create()

Create an instance of the Time Series Service with the typical starting settings.

exists()

Returns whether or not this service already exists.

get_eventhub_host()

returns the publish grpc endpoint for ingestion.

get_publish_wss_uri()

returns the publish grpc endpoint for ingestion.

grant_client(client_id, publish=False, subscribe=False, publish_protocol=None, publish_topics=None, subscribe_topics=None, scope_prefix='predix-event-hub', **kwargs)

Grant the given client id all the scopes and authorities needed to work with the eventhub service.

Logging

The Logging Service is a Cloud Foundry log aggregator and management to aid with application level debugging. It can be used in combination with the ELK stack for good results. You can learn more from the Logging catalog page and official documentation.

Example

Here is a simple demo of creating the service.

# How-To Create the service

import predix.admin.app
admin = predix.admin.app.Manifest()
admin.create_logging()

This should not be confused with Python’s logging library but rather the STDOUT and STDERR emitted by your application captured for later review like you would see from the cf logs command.

Logging Administration

class predix.admin.logstash.Logging(plan_name=None, name=None, *args, **kwargs)

An Elasticsearch ELK distribution to centralize Cloud Foundry log aggregation and analysis.

You need to install the Kibana-Me-Logs application separately to make use of the logging service. https://docs.predix.io/en-US/content/service/operations/logging/

add_to_manifest(manifest)

Add to the manifest to make sure it is bound to the application.

create()

Creates an instance of the logstash pipeline.

exists()

Returns whether or not this service already exists.

Weather

Warning

This service has been deprecated.

Weather API

class predix.data.weather.WeatherForecast(*args, **kwargs)

Weather Forecast Service

Important

Deprecated

get_weather_forecast(latitude, longitude, start, end, frequency=1, reading_type=None)

Return the weather forecast for a given location for specific datetime specified in UTC format.

results = ws.get_weather_forecast(lat, long, start, end)
for w in results['hits']:
    print w['start_datetime_local']
    print w['reading_type'], '=', w['reading_value']

For description of reading types: https://graphical.weather.gov/xml/docs/elementInputNames.php

get_weather_forecast_days(latitude, longitude, days=1, frequency=1, reading_type=None)

Return the weather forecast for a given location.

results = ws.get_weather_forecast_days(lat, long)
for w in results['hits']:
    print w['start_datetime_local']
    print w['reading_type'], w['reading_value']

For description of reading types: https://graphical.weather.gov/xml/docs/elementInputNames.php

Weather Administration

class predix.admin.weather.WeatherForecast(plan_name=None, name=None, uaa=None, *args, **kwargs)

Weather Forecast Service

Important

Deprecated

add_to_manifest(manifest)

Add useful details to the manifest about this service so that it can be used in an application.

Parameters:manifest – An predix.admin.app.Manifest object instance that manages reading/writing manifest config for a cloud foundry app.
create()

Create an instance of the US Weather Forecast Service with typical starting settings.

exists()

Returns whether or not this service already exists.

grant_client(client_id)

Grant the given client with any scopes or authorities needed to use this service.