步驟 2：獲取帶有身分驗證碼的 URL - Amazon Quick Suite

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

步驟 2：獲取帶有身分驗證碼的 URL

重要

Amazon Quick Sight 有用於內嵌分析的新 APIs： GenerateEmbedUrlForAnonymousUser和 GenerateEmbedUrlForRegisteredUser。

您仍然可以使用 GetDashboardEmbedUrl和 GetSessionEmbedUrl APIs 來內嵌儀表板和 Amazon Quick Sight 主控台，但它們不包含最新的內嵌功能。如需up-to-date內嵌體驗，請參閱將 Amazon Quick Sight 分析內嵌至您的應用程式。

在下一章節，您可以了解如何在您的應用程式伺服器上驗證使用者，以及取得可內嵌主控台工作階段的 URL。

當使用者存取您的應用程式時，該應用程式代表使用者擔任 IAM 角色。然後，如果使用者尚未存在，它會將使用者新增至 Amazon Quick Sight。接著，它傳遞識別符當作唯一的角色工作階段 ID。

執行所述的步驟可確保主控台工作階段的每個檢視器在 Amazon Quick Sight 中都是唯一的佈建。它還會強制執行個別使用者設定，例如資料列層級的安全性和參數的動態預設值。

下列範例會代表使用者執行 IAM 身分驗證。此代碼在您的應用程式伺服器上運行。

Java
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.quicksight.AmazonQuickSight;
import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.GetSessionEmbedUrlRequest;
import com.amazonaws.services.quicksight.model.GetSessionEmbedUrlResult;

/**
 * Class to call QuickSight AWS SDK to get url for session embedding.
 */
public class GetSessionEmbedUrlQSAuth {

    private final AmazonQuickSight quickSightClient;

    public GetSessionEmbedUrlQSAuth() {
        this.quickSightClient = AmazonQuickSightClientBuilder
                .standard()
                .withRegion(Regions.US_EAST_1.getName())
                .withCredentials(new AWSCredentialsProvider() {
                                     @Override
                                     public AWSCredentials getCredentials() {
                                         // provide actual IAM access key and secret key here
                                         return new BasicAWSCredentials("access-key", "secret-key");
                                     }

                                     @Override
                                     public void refresh() {}
                                 }
                )
                .build();
    }

    public String getQuicksightEmbedUrl(
            final String accountId, // YOUR AWS ACCOUNT ID
            final String userArn // REGISTERED USER ARN TO USE FOR EMBEDDING. REFER TO GETEMBEDURL SECTION IN DEV PORTAL TO FIND OUT HOW TO GET USER ARN FOR A QUICKSIGHT USER
    ) throws Exception {
        GetSessionEmbedUrlRequest getSessionEmbedUrlRequest = new GetSessionEmbedUrlRequest()
                .withAwsAccountId(accountId)
                .withEntryPoint("/start")
                .withUserArn(userArn);

        GetSessionEmbedUrlResult sessionEmbedUrl = quickSightClient.getSessionEmbedUrl(getSessionEmbedUrlRequest);

        return sessionEmbedUrl.getEmbedUrl();
    }
}
JavaScript
global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function getSessionEmbedURL(
    accountId, // YOUR AWS ACCOUNT ID
    userArn, // REGISTERED USER ARN TO USE FOR EMBEDDING. REFER TO GETEMBEDURL SECTION IN DEV PORTAL TO FIND OUT HOW TO GET USER ARN FOR A QUICKSIGHT USER
    getEmbedUrlCallback, // GETEMBEDURL SUCCESS CALLBACK METHOD
    errorCallback // GETEMBEDURL ERROR CALLBACK METHOD
    ) {
    const getSessionParams = {
        AwsAccountId: accountId,
        EntryPoint: "/start",
        UserArn: userArn,
        SessionLifetimeInMinutes: 600,
    };

    const quicksightGetSession = new AWS.QuickSight({
        region: process.env.AWS_REGION,
    });

    quicksightGetSession.getSessionEmbedUrl(getSessionParams, function(err, data) {
        if (err) {
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const result = {
                "statusCode": 200,
                "headers": {
                    "Access-Control-Allow-Origin": "*", // USE YOUR WEBSITE DOMAIN TO SECURE ACCESS TO GETEMBEDURL API
                    "Access-Control-Allow-Headers": "Content-Type"
                },
                "body": JSON.stringify(data),
                "isBase64Encoded": false
            }
            getEmbedUrlCallback(result);
        }
    });
}
Python3
import json
import boto3
from botocore.exceptions import ClientError
import time

# Create QuickSight and STS clients
qs = boto3.client('quicksight',region_name='us-east-1')
sts = boto3.client('sts')

# Function to generate embedded URL
# accountId: YOUR AWS ACCOUNT ID
# userArn: REGISTERED USER ARN TO USE FOR EMBEDDING. REFER TO GETEMBEDURL SECTION IN DEV PORTAL TO FIND OUT HOW TO GET USER ARN FOR A QUICKSIGHT USER
def getSessionEmbedURL(accountId, userArn):
    try:
        response = qs.get_session_embed_url(
            AwsAccountId = accountId,
            EntryPoint = "/start",
            UserArn = userArn,
            SessionLifetimeInMinutes = 600
        )
            
        return {
            'statusCode': 200,
            'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
            'body': json.dumps(response),
            'isBase64Encoded':  bool('false')
        }
    except ClientError as e:
        print(e)
        return "Error generating embeddedURL: " + str(e)
Node.js

以下範例顯示的 JavaScript (Node.js) 可在應用程式伺服器上用來獲得內嵌主控台工作階段的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示主控台工作階段。

const AWS = require('aws-sdk');
            const https = require('https');
            
            var quicksight = new AWS.Service({
                apiConfig: require('./quicksight-2018-04-01.min.json'),
                region: 'us-east-1',
            });
            
            quicksight.GetSessionEmbedUrl({
                'AwsAccountId': '111122223333',
                'EntryPoint': 'https://url-for-console-page-to-open',
                'SessionLifetimeInMinutes': 600,
                'UserArn': 'USER_ARN'
            
            }, function(err, data) {
                console.log('Errors: ');
                console.log(err);
                console.log('Response: ');
                console.log(data);
            });
//The URL returned is over 900 characters. For this example, we've shortened the string for
            //readability and added ellipsis to indicate that it's incomplete.
                                { Status: 200,
              EmbedUrl: 'https://dashboards.example.com/embed/620bef10822743fab329fb3751187d2d…
              RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' }
.NET/C#

以下範例顯示的 .NET/C# 程式碼可在應用程式伺服器上用來產生內嵌主控台工作階段的 URL。您可以在您的網站或應用程式中使用此 URL 來顯示主控台。


            var client = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                sessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                Console.WriteLine(
                    client.GetSessionEmbedUrlAsync(new GetSessionEmbedUrlRequest
                    {
                'AwsAccountId': '111122223333',
                'EntryPoint': 'https://url-for-console-page-to-open',
                'SessionLifetimeInMinutes': 600,
                'UserArn': 'USER_ARN'
                        AwsAccountId = 111122223333,
                        EntryPoint = https://url-for-console-page-to-open,
                        SessionLifetimeInMinutes = 600,
                        UserArn = 'USER_ARN'
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
AWS CLI

若要擔任角色，請選擇下列其中一個 AWS Security Token Service (AWS STS) API 操作：

  • AssumeRole – 在使用 IAM 身分擔任角色的情況下使用此操作。

  • AssumeRoleWithWebIdentity – 在使用 Web 身分提供者驗證您的使用者時，請使用此操作。

  • AssumeRoleWithSaml –在您使用 SAML 驗證使用者時，請使用此操作。

以下範例顯示用來設定 IAM 角色的 CLI 命令。角色需要啟用 quicksight:GetSessionEmbedUrl 的許可。如果您在第一次開啟 Amazon Quick Sight 時採取just-in-time方法來新增使用者，該角色也需要為 啟用許可quicksight:RegisterUser。

aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
     --role-session-name john.doe@example.com

assume-role 操作會傳回三個輸出參數：存取金鑰、私密金鑰和工作階段字符。

注意

若您呼叫 AssumeRole 操作時收到 ExpiredToken 錯誤，原因可能是先前的 SESSION TOKEN 仍在環境變數中。設定以下變數便可清除此錯誤：

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

  • AWS_SESSION_TOKEN

以下範例說明如何在 CLI 中設定這三個參數。如果您使用 Microsoft Windows 電腦，請使用 set，不要使用 export。

export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
export AWS_SESSION_TOKEN     = "session_token_from_assume_role"

對於瀏覽您網站的使用者，執行這些命令可將其角色工作階段 ID 設為 embedding_quicksight_console_session_role/john.doe@example.com。角色工作階段 ID 由來自 role-arn 和 role-session-name 值的角色名稱所組成。對每個使用者使用唯一的角色工作階段 ID，可確保為每個使用者設定適當的許可。還能避免對使用者存取進行任何調節。調節是一項安全功能，可防止相同的使用者從多個位置存取 Amazon Quick Sight。

角色工作階段 ID 也會成為 Amazon Quick Sight 中的使用者名稱。您可以使用此模式提前在 Amazon Quick Sight 中佈建使用者，或在他們第一次存取主控台工作階段時佈建使用者。

以下範例顯示可用來佈建使用者的 CLI 命令。如需 RegisterUser、DescribeUser 和其他 Amazon Quick Sight API 操作的詳細資訊，請參閱 Amazon Quick Sight API 參考。

aws quicksight register-user \
     --aws-account-id 111122223333 \
     --namespace default \
     --identity-type IAM \
     --iam-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
     --user-role READER \
     --user-name jhnd \
     --session-name "john.doe@example.com" \
     --email john.doe@example.com \
     --region us-east-1 \
     --custom-permissions-name TeamA1

如果使用者是透過 Microsoft AD 進行身分驗證，您就不需要使用 RegisterUser 設定他們。相反地，他們應在第一次存取 Amazon Quick Sight 時自動訂閱。若是 Microsoft AD 使用者，您可以使用 DescribeUser 取得使用者的 ARN。

使用者第一次存取 Amazon Quick Sight 時，您也可以將此使用者新增至適當的群組。以下範例顯示用於將使用者新增至群組的 CLI 命令。

aws quicksight create-group-membership \
     --aws-account-id=111122223333 \
     --namespace=default \
     --group-name=financeusers \
     --member-name="embedding_quicksight_dashboard_role/john.doe@example.com"

您現在擁有的應用程式使用者，同時也是 Amazon Quick Sight 的使用者，以及可存取 Amazon Quick Sight 主控台工作階段的使用者。

最後，為了取得主控台工作階段的簽章 URL，請從應用程式伺服器呼叫 get-session-embed-url。這將返回可嵌入的主控台工作階段 URL。下列範例示範如何使用伺服器端呼叫，為透過 AWS Managed Microsoft AD 或單一登入 (IAM Identity Center) 驗證的使用者取得內嵌主控台工作階段的 URL。

aws quicksight get-dashboard-embed-url \
     --aws-account-id 111122223333 \
     --entry-point the-url-for--the-console-session \
     --session-lifetime-in-minutes 600 \
     --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_dashboard_role/embeddingsession

如需有關使用此操作的詳細資訊，請參閱 GetSessionEmbedUrl。您可以在您自己的程式碼中使用這個和其他 API 操作。