Use the Plotly Images REST Service Endpoint
1 Introduction
The Plotly API images endpoint turns a plot into an image of the desired format. A set of body parameters and headers are passed to the endpoint, which returns an image when a request is made.
This how-to teaches you how to do the following:
-
Call Plotly API Images’ REST Endpoint
-
Save images returned from generated by the endpoint
2 Prerequisites
Before starting this how-to, make sure you have completed the following prerequisites:
- Create an account on plot.ly: you can sign up to plot.ly here: https://plot.ly/accounts/login/?action=signup#/
- Retrieve the plotly API key which goes with your account; your API key can be found on the settings page when you are logged in to the site
3 Setting up the Domain Model
To set up the domain model for use with the plotly REST service endpoint, follow these steps:
-
Create two entities: Image and DataSource.
-
Image should be a specialization of the System.Image entity, so set Generalization to System.Image.
-
DataSource should be non-persistable with Data and Layout string attributes.
4 Calling the ‘Plotly API Images’ REST Endpoint
To make a call to Plotly API images REST endpoint, follow these steps:
-
Add a blank page to the existing module.
-
Add a Data view with data source as a microflow that returns a new DataSource object.
-
In the Data view, place input widgets with source attribute as Data and Layout.
-
In the footer of the Data view, add a Call microflow button.
-
Link the button to a new microflow: ACT_Call_REST.
-
Rename the button Call Plotly REST Service.
-
Right click the button, select to Go to on click microflow….
-
Build the microflow as shown below.
-
The Call REST service activity is configured as follows:
-
In the tab General, the Location should be set to https://api.plot.ly/v2/images
-
Select the HTTP Method as POST
-
In the tab HTTP Headers, Enter your plotly user name and API key (more information on plotly authentication can be found here: https://api.plot.ly/v2/#authentication)
Custom HTTP headers ‘Content-Type’ and ‘Plotly-Client-Platform’ must be provided -
In the tab Request, select Custom request template; the request is a ‘JSON’ object with the structure
1 2 3 4 5 6 7 8
{ "figure": { "data": [{"y": [10, 10, 2, 20]}], "layout": {"width": 700} }, "format": "png", "encoded": false }
For more request parameter details, see the documentation here: Plotly REST API, v2.
Whenencoded
is set totrue
, a base64 image url is returned.
In the field Template, escape the opening brace,{
, by using a double opening brace,{
{
. -
In the tab Response, set Response handling to Store in a file document
-
Set Output > Type to the Image entity
-
5 Saving the Image
To save images generated by the REST service, follow these steps:
-
Add a Show page activity to the ACT_Call_REST microflow.
-
Select a new page.
-
Set the generated image object as the Object to pass to the page.
-
Set the layout of the page as a popup.
-
Place a Data view in the page and populate it as shown below:
-
Run the app.
-
In the browser, open the page with the Call Plotly REST Service button.
-
Fill in the Data and Layout fields. An example is shown in the image below.
-
Click the Call Plotly REST Service button.
-
Click the Save button to save the image which is displayed.