Quick BI allows you to embed reports that are created in group workspaces into other systems. This way, Quick BI can be integrated with other application systems. This facilitates service integration. In Quick BI, reports include dashboards and workbooks. This topic describes how to embed a report into a third-party system.

Step1: Obtain the access token by making an HTTPS API request

In the example described in this topic, a dashboard that is created in a group workspace is used.
  • If your Quick BI account has the developer or analyst permissions on a group workspace, the account can be granted the permissions only on the dashboards that are created by the account in the group workspace.
  • If your Quick BI account has the administrator permissions on a group workspace, the account can be granted the permissions on all dashboards in the group workspace.
  1. Obtain the AccessKey ID and the AccessKey secret of your Quick BI account.
    1. Log on to the Quick BI console.
    2. To obtain the AccessKey ID and the AccessKey secret, perform the steps that are shown in the following figure.
      Obtain the AccessKey information
  2. Obtain the Alibaba Cloud ID.
    • If you are using an Alibaba Cloud account, the Alibaba Cloud ID is displayed in the Account Center. For more information, see Obtain information about your Alibaba Cloud account.

      On the Security Settings page, obtain the value of the Account ID field. This value is used as the Alibaba Cloud ID.

      Account ID
    • If you are using a RAM user, the Alibaba Cloud ID is a combination of the names of the Alibaba Cloud account and the RAM user in the format of Alibaba Cloud account name:RAM user.
      If the Alibaba Cloud account is test and the RAM user is zhangsan@sdf123.onaliyun.com, the Alibaba Cloud ID is test:zhangsan.
      Note You can contact the administrator to obtain the Alibaba Cloud account to which the RAM user belongs.
  3. Obtain an access token.
    Set the accessId, accessKey, and aliyunId parameters in the following request URL to the AccessKey ID, AccessKey secret, and Alibaba Cloud ID that are obtained in the previous steps. Then, send a GET request to obtain an access token.
    https://das.base.shuju.aliyun.com/api/ac3rdservice/token.json?accessId=xxx&accessKey=xxx&aliyunId=xxx&validityTime=60
    If true is returned for success, the access token is obtained. The value of accessToken is the access token. 1
    Note If you send a request to obtain or access a report before the access token expires, the validity period of the access token is automatically extended based on the configured validity period.

    The maximum value for the validityTime parameter is 240. Unit: minutes.

    For example, the first time that the value of the validityTime parameter is obtained and the value is 10 minutes. In this case, if you send the request again within 10 minutes, the validity period of the access token is increased by 10 minutes.
    • If the value of the validityTime parameter is obtained again after the access token expires, a new access token is obtained.
    • If you want to invalidate an access token before it expires, you can send the following POST request. Replace the parameter values based on your business requirements.
      https://das.base.shuju.aliyun.com/api/ac3rdservice/tokenInvalid.json?aliyunId=XXX&accessToken=XXX 

Step2: Embed a dashboard

A dashboard can be embedded only if the dashboard is in the Published state.

  1. On the homepage of the Quick BI console, perform the steps that are shown in the following figure.
    Report Embedding
  2. Click OK.
    Then, you can view the newly embedded dashboard in the report list on the Report Embedding page. 1

Step 3: Create a logon-free URL

  1. In the Quick BI console, click Workspace in the top navigation bar. Then, in the left-side navigation pane, click Dashboards.
  2. On the Dashboards page, find the dashboard that is embedded in Step 2, and then click the 1 icon.
    On the dashboard preview page that appears, you can view the URL that points to the dashboard in the address bar.
    Note You can change the domain name in the preview URL. For example, the domain name in the preview URL is das.base.shuju.aliyun.com. You can change the domain name to bi.aliyun.com.
  3. Add the access token to the URL of the dashboard as the accessToken parameter. This way, users can view the dashboard without the need to log on to Quick BI. For more information about how to obtain the access token, see Step1: Obtain the access token by making an HTTPS API request.
    The following URL provides an example:
    https://das.base.shuju.aliyun.com/token3rd/dashboard/view/pc.htm?pageId=703d6621-7aa0-4716-bcc1-515e3da794c2&accessToken=XXXXX

Manage embedded reports

For reports that are embedded into third-party systems, you can perform the following operations:
  • Query embedded reports. In the search box on the Report Embedding page, enter a report name keyword and click the Query icon to query reports.

    You can select a workspace or a report type to narrow down the query range.

  • View the number of embedded reports. For more information, see View the number of embedded reports.
  • Delete embedded reports. To delete an embedded report, click the Delete icon next to the report. In the message that appears, click OK.

View the number of embedded reports

  1. On the homepage of the Quick BI console, click Open Service in the top navigation bar.
  2. In the left-side navigation pane, click Report Embedding.
    On the Report Embedding page, you can view the number of reports that are embedded into third-party systems. Embed
    Table 1. Number of reports that can be embedded
    Edition Quota for the number of users Number of reports that can be embedded into third-party systems
    Quick BI Pro 5 5
    10 10
    20 20
    50 50
    100 100
    150 150
    200 200
    Quick BI Enterprise Standard 50 100
    100 200
    200 500
    300 1,000

What can I do if the error message "An error occurred during third party authentication" is displayed?

The following figure provides an example of the error message. 1

Solution

Check whether the values of the accessId, accessKey, and aliyunId parameters in the request URL are correct. For more information, see Step1: Obtain the access token by making an HTTPS API request.

What can I do if the error message "access report_tree unauthorized" is displayed?

When you embed a report into a third-party system, the following error message is returned. 1

Possible cause

You do not have the required permissions on the report in the corresponding group workspace.

Solution

You can grant the permissions on the report by performing the steps that are shown in the following figure. Embed a report by using the International site (alibabacloud.com)

How do I configure a Quick BI report that is embedded into a third-party system to automatically adjust the height?

If a Quick BI dashboard is embedded into a third-party system by using an Inline Frame (IFrame), the third-party system cannot obtain the height of the dashboard in the IFrame due to the security limits of the cross-origin resource sharing (CORS) policy of the browser. In this case, users may need to scroll down or up to view the dashboard.

Solution

When Quick BI loads a dashboard, Quick BI uses postMessage to pass the height of the dashboard to external pages. The external pages can obtain the height and page ID of the dashboard by listening to events.

You can use one of the following methods to pass the height of a dashboard:
  • Quick BI passes the height of the IFrame to external pages in an active manner.
    // The URL of the dashboard in Quick BI. Configure the URL based on your business requirements.
    const quickBIURL = ['https://das.base.shuju.aliyun.com', 'https://bi.aliyun.com'];
    
    function messageListener(event) {
      if (quickBIURL.includes(event.origin)) {
        // The height of the dashboard. This height is passed by using postMessage.
        console.log('Quick BI Dashboard Height:', event.data.height);
        // The page ID of the dashboard. This page ID is passed by using postMessage.
        console.log('Quick BI Dashboard Id:', event.data.pageId);
      }
    }
    
    // Listens to events before the dashboard is loaded.
    window.addEventListener('message', messageListener);
  • External pages use postMessage to obtain the height of the dashboard in the IFrame.
    When you use the postMessage method, take note of the following items:
    • Use the IFrame that is used to embed the Quick BI dashboard.
    • The data passed into the message must contain { getDashboardHeight: true }.
    The following code block provides an example:
    // The URL of the dashboard in Quick BI. Configure the URL based on your business requirements.
    const quickBIURL = ['https://das.base.shuju.aliyun.com', 'https://bi.aliyun.com'];
    
    function messageListener(event) {
      if (quickBIURL.includes(event.origin)) {
        // The height of the dashboard. This height is passed by using postMessage.
        console.log('Quick BI Dashboard Height:', event.data.height);
        // The page ID of the dashboard. This page ID is passed by using postMessage.
        console.log('Quick BI Dashboard Id:', event.data.pageId);
      }
    }
    
    // Listens to events before the dashboard is loaded.
    window.addEventListener('message', messageListener);
    
    // Requests the height of the Quick BI dashboard.
    // The IFrame that is used to embed the Quick BI dashboard.
    const iframe = document.querySelector('iframe');
    // The data passed into the message must contain { getDashboardHeight: true }.
    iframe.contentWindow.postMessage({getDashboardHeight: true}, '*');
Note The width of Quick BI dashboards can adapt to the size of outer containers. This prevents a horizontal scroll bar from occurring. You do not need to configure dashboards to automatically adjust the width.
Complete sample code
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    </head>
    <body>
        <iframe 
        class="quickbi-iframe-demo" 
      // <page_Id> specifies the page ID of the dashboard. access_Token specifies the access token that is used to access the dashboard.
      src="https://das.base.shuju.aliyun.com/token3rd/dashboard/view/pc.htm?pageId=<page_Id>&accessToken=<access_Token>
      scrolling="no" 
      frameborder="0" 
      width="100%" 
      height="600">
    </iframe>

        <script>
      // The URL of the dashboard in Quick BI. Configure the URL based on your business requirements.
      const quickBIURL = ['https://das.base.shuju.aliyun.com', 'https://bi.aliyun.com'];

      function messageListener(event) {
        if (quickBIURL.includes(event.origin)) {
          // The height of the dashboard. This height is passed by using postMessage.
          console.log('Quick BI Dashboard Height:', event.data.height);
          // The page ID of the dashboard. This page ID is passed by using postMessage.
          console.log('Quick BI Dashboard Id:', event.data.pageId);
        }
      }

      // Listens to events before the dashboard is loaded.
      window.addEventListener('message', messageListener);

      // The IFrame that is used to embed the Quick BI dashboard.
      const iframe = document.querySelector('iframe');
      
       // Requests the height of the Quick BI dashboard.
      // The data passed into the message must contain { getDashboardHeight: true }.
      iframe.contentWindow.postMessage({getDashboardHeight: true}, '*');

        </script>
    </body>
</html>