Creating Streams with the Command Line Interface
The Stream Machine CLI is a command line interface for interacting with it. You can find its source code and binary at github.com/streammachineio/cli
the Stream Machine portal currently provides only limited functionality. You will need to use the CLI. |
The CLI is nothing more than a thin interface to the OpenApi interface. You can actually do all the CLI actions described below via the OpenApi interface. You do need an authentication token though (see below) [1].
Most of the CLI commands provide valid JSON output, so you can use them in command pipes with the excellent jq tool.
Logging in
First create an account at streammachine.io and use the email and password to log in with the CLI.
$ strm auth login
Enter your Stream Machine portal email address [hello@streammachine.io]: ...
Please enter your Stream Machine portal password:
Succesfully logged in as hello@streammachine.io
This creates a file credentials.json
in the application configuration directory [2].
You can use strm auth show
to find the billingId
that has been assigned to you. You need this with the client drivers.
$ strm auth show
Credentials for hello@streammachine.io
Billing id = hello0123456789
Current token valid until = 2021-01-14T16:28:16 UTC
Or if you prefer JSON:
$ strm auth show --json
{
"email": "hello@streammachine.io",
"billingId": "hello0123456789",
"expiresAt": 1610641696,
"idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjVmOTcxMm....",
"refreshToken": "AOvuKvQjJ3VzF12-5qo7crLryG9fz5979Zss...."
}
Note that the CLI has command completion. Add source <(strm --generate-completion bash|zsh|fish)
to your shell configuration file [3]
Listing streams
Streams can be listed and will be shown as JSON formatted.
When listing streams, the clientSecret is not shown. The secret is only shown once, which is upon creation of the stream.
|
$ strm streams list
[
{
"name": "stream-machine",
"tags": [],
"credentials": {
"clientId": "3p5hau1zunkyba0..."
}
}
]
Creating a stream
A stream can be created as follows [4]:
$ strm streams create stream-machine
{
"name": "stream-machine",
"tags": [],
"credentials": {
"clientId": "3p5hau1zunkyba0...",
"clientSecret": "Z^H^s_Xdm!h9W..."
}
}
The billingId
, clientId
and clientSecret
triplet is what identifies your
stream when you send data to Stream Machine. Stream Machine uses the OAuth 2.0
client credentials flow to generate a bearer token that needs to be provided
with each http request. Our drivers have tooling to create and refresh these
tokens, but nothing precludes you from creating the headers by hand (see the chapter about sending via curl
to do this manually).
So with this information, you have enough information to start sending data to in.strm.services/event. With the same credentials you can connect to the egress endpoint with a websocket client to receive the events as you send them.
Creating decrypted streams
If you want to have Stream Machine decrypt data with certain consent levels, you need to create an output stream.
$ strm outputs create --help
Usage: strm outputs create [OPTIONS] name output-name
Create a new output
Options:
-cl, --consent-level INT The consent levels for this
output.
-clt, --consent-level-type [GRANULAR|CUMULATIVE]
-d, --description TEXT Optional description to describe
the purpose of this output.
-t, --tag TEXT Optional tag for this output.
-dn, --decrypter-name TEXT Name for the decrypter that will
produce this output.
-h, --help Show this message and exit
Arguments:
name The name of the stream for which an output is
created.
output-name The name of the output that is created.
decrypter-name currently has no purpose, but it’s reserved for future use. The default value can be used for now.
|
So let’s create one, with two consent levels, and a granular consent level type interpretation.
$ strm outputs create stream-machine level0-1 -cl 0 -cl 1 -clt GRANULAR
{
"linkedStream": "stream-machine",
"name": "level0-1",
"tags": [],
"credentials": {
"clientId": "wvs5pkr6q48...",
"clientSecret": "8IhY!HnK(...#"
},
"consentLevelType": "GRANULAR",
"consentLevels": [ 0, 1 ],
"decrypterName": "default"
}
So this output stream named level0-1
captures data from encrypted stream stream-machine
(for the current billingId
).
It will drop all events that don’t at least have consent levels 0 and 1 in the event.
Another way of defining decrypted streams is with consent level type cumulative.
This means that the decrypted stream has just one consent level, and it will accept all events that have at least that consent level.
It will decrypt PII fields up to and including the decrypted stream consent level.
Using the OpenApi User Interface
If you just try one of the calls on the Swagger page you’ll receive:
{
"error": {
"code": 401,
"status": "Unauthorized",
"message": "The request could not be authorized"
}
}
First ask the CLI for a token: strm auth print-access-token
. Paste the token into the api page.
Now you can have a look at all capabilities of the api.