Integration (Preview)
Seamlessly Integrate notebook into external services.
Last updated
Was this helpful?
Seamlessly Integrate notebook into external services.
Last updated
Was this helpful?
Prepare API Key and Secret
Open "Workspace settings" and click menu "API Keys".
Click the "New API Key" button and create new API Key.
Make a note of the API Key and API Secret (they will be used later for API calls).
Open the Notebook
Open the notebook you want to share.
Click the "Share" button in the header and select "Integration".
Select Pages
Choose the pages you want to publish.
Publish
Click the "Publish" button.
Configure integration settings.
Add API Key to use in "Permitted API Keys" section.
If you want to overwrite parameter values via the API, configure them in the Externalized Params section
The following API is used to issue a token
The required arguments for calling the API can be found on the "Setup guide" tab.
Perform the API call on the server side to prevent the API Secret from being exposed externally.
Issue a token for each user session, and do not reuse it (it expires after 1 hour).
Embed HTML into your service using the Integration URL
.
You can set display options along with the token. Please check the "Setup guide" in for details.
Create an iframe element with Integration URL
as the src attribute
Wait for a {type: "READY_FOR_TOKEN"}
message from the iframe via postMessage
Send {type: "SET_TOKEN", token: "{{ TOKEN_HERE }}"}
message back to the iframe via postMessage
(Optionally, you can also send displayOptions
)
Append token as a query parameter to the Integration URL
(?token=xxx
)
Optionally, append displayOptions
as a query parameter
(The value should be encodeURIComponent(JSON.stringify(displayOptions))
)
Create an iframe element with the modified URL as the src attribute
Messages can be exchanged using the iframe's postMessage function.
The messages are also output to console.debug()
, so you can check the actual message content there.
For example, this functionality can be used to:
Persist parameter information modified by users.
Share parameters across different integrations or pages.
Below is a list of messages that can be sent and received.
SET_TOKEN
Set the authentication token and start rendering notebook. This message must be sent after receiving the READY_FOR_TOKEN
message.
READY_FOR_TOKEN
Notification that the notebook is ready to receive the token.
PARAM_CHANGED
Sent each time the user modifies a parameter within the notebook.
EXECUTE_SQLS_TRIGGERED
Sent when 'Run all' is executed within the notebook.
API Key. Can be issued from 'Workspace settings > API Keys'
6729a28bc7100424ad4e2e5d
API Secret. Generated when issuing 'API Key'
c711defdff5f4e3e8e53d4f408579b9a
Integration ID. Can be obtained from the notebook integration settings
671ef14b0d08cf6c657df7da
Page ID to be displayed in the notebook. Can be obtained from the notebook integration settings
671ecbbf2990c63fea3b3a26
Specify the user ID within the application where the notebook is embedded. Ensure that the token can uniquely identify the token user for security reason.
Externalized parameter values. Can be configured in the notebook integration settings
Token expiration time in seconds. Default is 3600 seconds (1 hour)
3600
Cache max age in seconds. Default is 86400 (24 hours)
86400