Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

# Incrustar la barra de búsqueda Quick Sight Q de Amazon para usuarios registrados
<a name="embedded-analytics-q-search-bar-for-authenticated-users"></a>


|  | 
| --- |
|  Se aplica a: Enterprise Edition  | 


|  | 
| --- |
|    Público objetivo: desarrolladores de Amazon Quick  | 

**nota**  
La barra de búsqueda integrada de Amazon Quick Sight Q ofrece la clásica experiencia de preguntas y respuestas de Amazon Quick Sight. Amazon Quick Sight se integra con Amazon Q Business para lanzar una nueva experiencia de preguntas y respuestas generativas. Se recomienda a los desarrolladores usar la nueva experiencia de preguntas y respuestas generativas. Para obtener más información sobre la experiencia de preguntas y respuestas generativas integrada, consulte Cómo [integrar Amazon Q en la experiencia de preguntas y respuestas generativas de Amazon Quick Sight](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html).

En las siguientes secciones, encontrará información detallada sobre cómo configurar una barra de búsqueda integrada de Amazon Quick Sight Q para los usuarios registrados de Amazon Quick Sight.

**Topics**
+ [Paso 1: configuración de permisos](#embedded-q-bar-for-authenticated-users-step-1)
+ [Paso 2: generación de la URL con el código de autenticación adjunto](#embedded-q-bar-for-authenticated-users-step-2)
+ [Paso 3: integración de la URL de la barra de búsqueda de Q](#embedded-q-bar-for-authenticated-users-step-3)
+ [Funcionalidades opcionales de incrustación en la barra de búsqueda Quick Sight Q de Amazon](#embedded-q-bar-for-authenticated-users-step-4)

## Paso 1: configuración de permisos
<a name="embedded-q-bar-for-authenticated-users-step-1"></a>

**nota**  
La barra de búsqueda integrada de Amazon Quick Sight Q ofrece la clásica experiencia de preguntas y respuestas de Amazon Quick Sight. Amazon Quick Sight se integra con Amazon Q Business para lanzar una nueva experiencia de preguntas y respuestas generativas. Se recomienda a los desarrolladores usar la nueva experiencia de preguntas y respuestas generativas. Para obtener más información sobre la experiencia de preguntas y respuestas generativas integrada, consulte Cómo [integrar Amazon Q en la experiencia de preguntas y respuestas generativas de Amazon Quick Sight](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html).

En la siguiente sección, puede encontrar información sobre cómo configurar los permisos de la aplicación de backend o del servidor web para integrar la barra de búsqueda de Q. Esta tarea requiere acceso administrativo a (IAM). AWS Identity and Access Management 

Cada usuario que accede a un panel de control asume un rol que le da acceso a Amazon Quick Sight y permisos para acceder al panel. Para que esto sea posible, cree un rol de IAM en su. Cuenta de AWS Asocie una política de IAM al rol para proporcionar permisos a cualquier usuario que lo asuma. El rol de IAM debe proporcionar permisos para recuperar las URL integradas para un grupo de usuarios específico. 

Con la ayuda del carácter comodín *\**, puede conceder los permisos necesarios para generar una URL para todos los usuarios de un espacio de nombres específico. También puede conceder permisos para generar una URL para un subconjunto de usuarios en espacios de nombres específicos. Para ello, añada `quicksight:GenerateEmbedUrlForRegisteredUser`.

Puede crear una condición en su política de IAM que limite los dominios que los desarrolladores pueden incluir en el parámetro `AllowedDomains` de una operación de la API `GenerateEmbedUrlForRegisteredUser`. El parámetro `AllowedDomains` es opcional. Ofrece a los desarrolladores la opción de anular los dominios estáticos que están configurados en el menú **Administrar Amazon Quick Sight** y, en su lugar, enumerar hasta tres dominios o subdominios que pueden acceder a una URL generada. A continuación, esta URL se integra en el sitio web del desarrollador. Solo los dominios que aparecen en el parámetro pueden acceder a la barra de búsqueda de Q. Sin esta condición, los desarrolladores pueden incluir cualquier dominio de Internet en el parámetro `AllowedDomains`. 

Para limitar los dominios que los desarrolladores pueden usar con este parámetro, añada una condición `AllowedEmbeddingDomains` a su política de IAM. Para obtener más información sobre el `AllowedDomains` parámetro, consulte la *referencia [GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html)de la API de Amazon Quick Sight*.

**Prácticas recomendadas de seguridad para los operadores de condiciones de IAM**  
Los operadores de condiciones de IAM configurados incorrectamente pueden permitir el acceso no autorizado a los recursos rápidos integrados mediante variaciones de URL. Cuando utilices la clave de `quicksight:AllowedEmbeddingDomains` condición en tus políticas de IAM, utiliza operadores de condiciones que permitan dominios específicos o denieguen todos los dominios que no estén específicamente permitidos. Para obtener más información sobre los operadores de condiciones de IAM, consulte [Elementos de la política JSON de IAM: operadores de condiciones](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html) en la Guía del usuario de IAM.  
Muchas variaciones de URL diferentes pueden apuntar al mismo recurso. Por ejemplo, todas las siguientes URL tienen el mismo contenido:  
`https://example.com`
`https://example.com/`
`https://Example.com`
Si su política utiliza operadores que no tienen en cuenta estas variaciones de URL, un atacante puede eludir sus restricciones proporcionando variaciones de URL equivalentes.  
Debe comprobar que su política de IAM utiliza los operadores de condiciones adecuados para evitar que se eludan las vulnerabilidades y garantizar que solo los dominios a los que va destinados puedan acceder a los recursos integrados.

La siguiente política de ejemplo ofrece estos permisos.

Además, si vas a crear usuarios primerizos que vayan a ser lectores de Amazon Quick Sight, asegúrate de añadir el `quicksight:RegisterUser` permiso en la política.

El siguiente ejemplo de política proporciona permiso para recuperar una URL incrustada para los usuarios primerizos que vayan a ser lectores de Amazon Quick Sight.

Finalmente, la identidad de IAM de su aplicación debe tener asociada una política de confianza para permitir el acceso al rol que acaba de crear. Esto significa que cuando un usuario accede a su aplicación, esta puede asumir la función en nombre del usuario y aprovisionar al usuario en Amazon Quick Sight. 

En el siguiente ejemplo, se muestra una muestra de política de confianza.

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowLambdaFunctionsToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        },
        {
            "Sid": "AllowEC2InstancesToAssumeThisRole",
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

------

Para obtener más información sobre las políticas de confianza para la autenticación de OpenID Connect o lenguaje de marcado para confirmaciones de seguridad (SAML), consulte las siguientes secciones de la *Guía de usuario de IAM:*
+ [Creación de un rol para identidades web o de OpenID Connect Federation (consola)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
+ [Creación de un rol para una federación SAML 2.0 (consola)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)

## Paso 2: generación de la URL con el código de autenticación adjunto
<a name="embedded-q-bar-for-authenticated-users-step-2"></a>

**nota**  
La barra de búsqueda integrada de Amazon Quick Sight Q ofrece la clásica experiencia de preguntas y respuestas de Amazon Quick Sight. Amazon Quick Sight se integra con Amazon Q Business para lanzar una nueva experiencia de preguntas y respuestas generativas. Se recomienda a los desarrolladores usar la nueva experiencia de preguntas y respuestas generativas. Para obtener más información sobre la experiencia de preguntas y respuestas generativas integrada, consulte Cómo [integrar Amazon Q en la experiencia de preguntas y respuestas generativas de Amazon Quick Sight](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html).

En la siguiente sección, encontrará cómo autenticar a su usuario y obtener la URL del tema de Q integrable en su servidor de aplicaciones. Si planea incrustar la barra Q para los tipos de identidad de IAM o Amazon Quick Sight, comparta el tema Q con los usuarios.

Cuando un usuario accede a su aplicación, esta asume el rol de IAM en nombre del usuario. A continuación, la aplicación añade el usuario a Amazon Quick Sight, si ese usuario aún no existe. A continuación, transfiere un identificador como ID de sesión de rol único. 

Al realizar los pasos descritos, se garantiza que cada espectador del tema Q se aprovisione de forma exclusiva en Amazon Quick Sight. También aplica la configuración por usuario, como la seguridad de nivel de fila y los valores predeterminados dinámicos de los parámetros.

Los siguientes ejemplos realizan la autenticación de IAM en nombre del usuario. Este código se ejecuta en el servidor de aplicaciones.

### Java
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-java"></a>

```
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.GenerateEmbedUrlForRegisteredUserRequest;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserResult;
import com.amazonaws.services.quicksight.model.RegisteredUserEmbeddingExperienceConfiguration;
import com.amazonaws.services.quicksight.model.RegisteredUserQSearchBarEmbeddingConfiguration;

        /**
 * Class to call QuickSight AWS SDK to get url for embedding the Q search bar.
        */
public class RegisteredUserQSearchBarEmbeddingConfiguration {

            private final AmazonQuickSight quickSightClient;

    public RegisteredUserQSearchBarEmbeddingConfiguration() {
        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, // AWS Account ID
            final String topicId, // Topic ID to embed
            final List<String> allowedDomains, // Runtime allowed domain for embedding
            final String userArn // Registered user arn to use for embedding. Refer to Get Embed Url section in developer portal to find how to get user arn for a QuickSight user.
            ) throws Exception {
        final RegisteredUserEmbeddingExperienceConfiguration experienceConfiguration = new RegisteredUserEmbeddingExperienceConfiguration()
                .withQSearchBar(new RegisteredUserQSearchBarEmbeddingConfiguration().withInitialTopicId(topicId));
        final GenerateEmbedUrlForRegisteredUserRequest generateEmbedUrlForRegisteredUserRequest = new GenerateEmbedUrlForRegisteredUserRequest();
        generateEmbedUrlForRegisteredUserRequest.setAwsAccountId(accountId);
        generateEmbedUrlForRegisteredUserRequest.setUserArn(userArn);
        generateEmbedUrlForRegisteredUserRequest.setAllowedDomains(allowedDomains);
        generateEmbedUrlForRegisteredUserRequest.setExperienceConfiguration(QSearchBar);

        final GenerateEmbedUrlForRegisteredUserResult generateEmbedUrlForRegisteredUserResult = quickSightClient.generateEmbedUrlForRegisteredUser(generateEmbedUrlForRegisteredUserRequest);

        return generateEmbedUrlForRegisteredUserResult.getEmbedUrl();
            }
        }
```

### JavaScript
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-js"></a>

```
global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function generateEmbedUrlForRegisteredUser(
    accountId,
    topicId, // Topic ID to embed
    openIdToken, // Cognito-based token
    userArn, // registered user arn
    roleArn, // IAM user role to use for embedding
    sessionName, // Session name for the roleArn assume role
    allowedDomains, // Runtime allowed domain for embedding
    getEmbedUrlCallback, // GetEmbedUrl success callback method
    errorCallback // GetEmbedUrl error callback method
    ) {
    const stsClient = new AWS.STS();
    let stsParams = {
        RoleSessionName: sessionName,
        WebIdentityToken: openIdToken,
        RoleArn: roleArn
        }
    
    stsClient.assumeRoleWithWebIdentity(stsParams, function(err, data) {
        if (err) {
            console.log('Error assuming role');
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const getQSearchBarParams = {
        "AwsAccountId": accountId,
                "ExperienceConfiguration": {
                    "QSearchBar": {
                        "InitialTopicId": topicId
                    }
                },
                "UserArn": userArn,
        "AllowedDomains": allowedDomains,
        "SessionLifetimeInMinutes": 600
    };

            const quicksightGetQSearchBar = new AWS.QuickSight({
        region: process.env.AWS_REGION,
                credentials: {
                    accessKeyId: data.Credentials.AccessKeyId,
                    secretAccessKey: data.Credentials.SecretAccessKey,
                    sessionToken: data.Credentials.SessionToken,
                    expiration: data.Credentials.Expiration
                }
    });

            quicksightGetQSearchBar.generateEmbedUrlForRegisteredUser(getQSearchBarParams, 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
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-python"></a>

```
import json
import boto3
from botocore.exceptions import ClientError

sts = boto3.client('sts')

# Function to generate embedded URL  
# accountId: AWS account ID
# topicId: Topic ID to embed
# userArn: arn of registered user
# allowedDomains: Runtime allowed domain for embedding
# roleArn: IAM user role to use for embedding
# sessionName: session name for the roleArn assume role
def getEmbeddingURL(accountId, topicId, userArn, allowedDomains, roleArn, sessionName):
    try:
        assumedRole = sts.assume_role(
            RoleArn = roleArn,
            RoleSessionName = sessionName,
        )
    except ClientError as e:
        return "Error assuming role: " + str(e)
    else: 
        assumedRoleSession = boto3.Session(
            aws_access_key_id = assumedRole['Credentials']['AccessKeyId'],
            aws_secret_access_key = assumedRole['Credentials']['SecretAccessKey'],
            aws_session_token = assumedRole['Credentials']['SessionToken'],
        )
        try:
            quicksightClient = assumedRoleSession.client('quicksight', region_name='us-west-2')
            response = quicksightClient.generate_embed_url_for_registered_user(
                AwsAccountId=accountId,
                ExperienceConfiguration = {
                    "QSearchBar": {
                        "InitialTopicId": topicId
                    }
                },
                UserArn = userArn,
                AllowedDomains = allowedDomains,
                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:
            return "Error generating embedding url: " + str(e)
```

### Node.js
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-node"></a>

El siguiente ejemplo muestra el JavaScript (Node.js) que puede usar en el servidor de aplicaciones para generar la URL del panel integrado. Puede utilizar esta URL en su sitio web o aplicación para mostrar el panel. 

**Example**  

```
const AWS = require('aws-sdk');
const https = require('https');

var quicksightClient = new AWS.Service({
    apiConfig: require('./quicksight-2018-04-01.min.json'),
    region: 'us-east-1',
});

quicksightClient.generateEmbedUrlForRegisteredUser({
    'AwsAccountId': '111122223333',
    'ExperienceConfiguration': { 
        'QSearchBar': {
            'InitialTopicId': 'U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f'
        }
    },
    'UserArn': 'REGISTERED_USER_ARN',
    'AllowedDomains': allowedDomains,
    'SessionLifetimeInMinutes': 100
}, function(err, data) {
    console.log('Errors: ');
    console.log(err);
    console.log('Response: ');
    console.log(data);
});
```

**Example**  

```
//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://quicksightdomain/embed/12345/dashboards/67890/sheets/12345/visuals/67890...",
        RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' 
    }
```

### .NET/C\#
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-cs"></a>

En el siguiente ejemplo, se muestra el. NET/C\# código que puedes usar en el servidor de aplicaciones para generar la URL de la barra de búsqueda Q incrustada. Puede utilizar esta URL en su sitio web o aplicación para mostrar la barra de búsqueda de Q. 

**Example**  

```
using System;
using Amazon.QuickSight;
using Amazon.QuickSight.Model;

namespace GenerateDashboardEmbedUrlForRegisteredUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                RegisteredUserQSearchBarEmbeddingConfiguration registeredUserQSearchBarEmbeddingConfiguration
                    = new RegisteredUserQSearchBarEmbeddingConfiguration
                    {
                        InitialTopicId = "U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f"
                    };
                RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
                    = new RegisteredUserEmbeddingExperienceConfiguration
                    {
                        QSearchBar = registeredUserQSearchBarEmbeddingConfiguration
                    }; 
                
                Console.WriteLine(
                    quicksightClient.GenerateEmbedUrlForRegisteredUserAsync(new GenerateEmbedUrlForRegisteredUserRequest
                    {
                        AwsAccountId = "111122223333",
                        ExperienceConfiguration = registeredUserEmbeddingExperienceConfiguration,
                        UserArn = "REGISTERED_USER_ARN",
                        AllowedDomains = allowedDomains,
                        SessionLifetimeInMinutes = 100
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
        }
    }
}
```

### AWS CLI
<a name="embedded-q-bar-for-embedded-q-bar-for-authenticated-users-cli"></a>

Para asumir la función, elige una de las siguientes AWS Security Token Service (AWS STS) operaciones de API:
+ [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)— Utilice esta operación cuando utilice una identidad de IAM para asumir la función.
+ [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)— Utilice esta operación cuando utilice un proveedor de identidad web para autenticar al usuario. 
+ [AssumeRoleWithSaml](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)— Utilice esta operación cuando utilice SAML para autenticar a sus usuarios.

En el siguiente ejemplo, se muestra el comando de la CLI para definir el rol de IAM. El rol debe tener los permisos de `quicksight:GenerateEmbedUrlForRegisteredUser` habilitados. Si adopta un enfoque “justo a tiempo” para añadir usuarios cuando utilizan un tema en la barra de búsqueda de Q, el rol también necesita permisos habilitados para `quicksight:RegisterUser`.

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

La operación `assume-role` devuelve tres parámetros de salida: la clave de acceso, la clave secreta y el token de sesión. 

**nota**  
Si se produce un error `ExpiredToken` al llamar a la operación `AssumeRole`, probablemente se debe a que el `SESSION TOKEN` anterior aún se encuentra en las variables de entorno. Para retirarlo, establezca las variables siguientes:  
*AWS\_ACCESS\_KEY\_ID* 
*AWS\_SECRET\_ACCESS\_KEY* 
*AWS\_SESSION\_TOKEN* 

En el siguiente ejemplo, se muestra cómo definir estos tres parámetros en la CLI. En un ordenador con Microsoft Windows, utilice `set` en lugar de `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}}"
```

Al ejecutar estos comandos, se define el ID de sesión del rol del usuario que visita su sitio web como `embedding_quicksight_q_search_bar_role/john.doe@example.com`. El ID de sesión del rol está compuesto por el nombre del rol de `role-arn` y el valor de `role-session-name`. Al utilizar el ID de sesión del rol único para cada usuario, se garantiza que se definan los permisos correspondientes para cada usuario. También evitará la limitación del acceso de los usuarios. *La limitación* es una función de seguridad que impide que el mismo usuario acceda a Amazon Quick Sight desde varios lugares. 

El ID de sesión del rol también se convierte en el nombre de usuario en Amazon Quick Sight. Puede utilizar este patrón para aprovisionar a sus usuarios en Amazon Quick Sight con antelación o para aprovisionarlos la primera vez que accedan a la barra de búsqueda Q. 

En el siguiente ejemplo, se muestra el comando de la CLI que puede utilizar para incluir a un usuario. Para obtener más información sobre [RegisterUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RegisterUser.html)y otras operaciones de la API de Amazon Quick Sight, consulte la [referencia de la API de Amazon Quick Sight](https://docs.aws.amazon.com/quicksight/latest/APIReference/Welcome.html). [DescribeUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_DescribeUser.html)

```
aws quicksight register-user \
    --aws-account-id {{111122223333}} \
    --namespace default \
    --identity-type {{IAM}} \
    --iam-arn "{{arn:aws:iam::111122223333:role/embedding_quicksight_q_search_bar_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}}
```

Si el usuario se ha autenticado a través de Microsoft AD, no es necesario utilizar `RegisterUser` para configurarlo. En su lugar, deberían suscribirse automáticamente la primera vez que accedan a Amazon Quick Sight. En el caso de los usuarios de Microsoft AD, puede utilizar `DescribeUser` para obtener el Nombre de recurso de Amazon (ARN) del usuario.

La primera vez que un usuario accede a Amazon Quick Sight, también puedes añadir este usuario al grupo con el que se comparte el panel. En el siguiente ejemplo, se muestra el comando de la CLI para añadir un usuario a un grupo.

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

Ahora tienes un usuario de tu aplicación que también es usuario de Amazon Quick Sight y que tiene acceso al panel de control. 

Por último, para obtener una URL firmada para el panel, llame a `generate-embed-url-for-registered-user` desde el servidor de aplicaciones. Esta operación devuelve la URL del panel integrable. En el siguiente ejemplo, se muestra cómo generar la URL de un panel integrado mediante una llamada desde el servidor para los usuarios autenticados mediante un inicio de sesión único ( AWS Managed Microsoft AD IAM Identity Center).

```
aws quicksight generate-embed-url-for-registered-user \
--aws-account-id {{111122223333}} \
--session-lifetime-in-minutes {{600}} \
--user-arn {{arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_q_search_bar_role/embeddingsession}}
--allowed-domains '["{{domain1}}","{{domain2}}"]' \
--experience-configuration QSearchBar={InitialTopicId={{U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f}}}
```

Para obtener más información sobre cómo usar esta operación, consulte [https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html). Puede utilizar esta y otras operaciones de la API en su propio código.

## Paso 3: integración de la URL de la barra de búsqueda de Q
<a name="embedded-q-bar-for-authenticated-users-step-3"></a>

**nota**  
La barra de búsqueda integrada de Amazon Quick Sight Q ofrece la clásica experiencia de preguntas y respuestas de Amazon Quick Sight. Amazon Quick Sight se integra con Amazon Q Business para lanzar una nueva experiencia de preguntas y respuestas generativas. Se recomienda a los desarrolladores usar la nueva experiencia de preguntas y respuestas generativas. Para obtener más información sobre la experiencia de preguntas y respuestas generativas integrada, consulte Cómo [integrar Amazon Q en la experiencia de preguntas y respuestas generativas de Amazon Quick Sight](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html).

En la siguiente sección, puede encontrar cómo integrar la URL de la barra de búsqueda Q del paso 3 en su sitio web o página de la aplicación. Esto se hace con el [SDK de incrustación de Amazon Quick Sight](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) (JavaScript). Con el SDK, puede hacer lo siguiente: 
+ Colocar la barra de búsqueda de Q en una página HTML.
+ Pasar los parámetros a la barra de búsqueda de Q.
+ Resolver los estados de error con mensajes que se personalizan en su aplicación.

Llame a la operación de la API `GenerateEmbedUrlForRegisteredUser` para generar la dirección URL que puede integrar en la aplicación. Esta URL es válida durante 5 minutos, y la sesión resultante es válida hasta 10 horas. La operación de la API proporciona la URL con un valor `auth_code` que permite una sesión con inicio único. 

El siguiente es un ejemplo de respuesta de `generate-embed-url-for-registered-user`.

```
//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://{{quicksightdomain}}/embedding/12345/q/search...",
     "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
```

Inserta la barra de búsqueda Q en tu página web mediante el [SDK de incrustación de Amazon Quick Sight](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk) o añadiendo esta URL a un iframe. Si estableces un número fijo de altura y anchura (en píxeles), Amazon Quick Sight los usará y no cambiará la imagen a medida que la ventana cambie de tamaño. Si establece un porcentaje relativo de altura y anchura, Amazon Quick Sight proporciona un diseño adaptable que se modifica a medida que cambia el tamaño de la ventana. 

Para ello, asegúrate de que el dominio que alojará la barra de búsqueda Q integrada esté en la *lista de dominios permitidos*, la lista de dominios aprobados para tu suscripción a Amazon Quick Sight. Este requisito protege los datos impidiendo que dominios no aprobados alojen paneles integrados. Para obtener más información sobre cómo añadir dominios a una barra de búsqueda Q integrada, consulte [Gestión de dominios e incrustación.](https://docs.aws.amazon.com/quicksight/latest/user/manage-qs-domains-and-embedding.html)

Cuando utilizas el SDK de incrustación Quick Sight de Amazon, la barra de búsqueda Q de tu página cambia de tamaño de forma dinámica en función del estado. Al utilizar el SDK de incrustación Quick Sight de Amazon, también puedes controlar los parámetros de la barra de búsqueda Q y recibir llamadas en función de la finalización de la carga de la página y de los errores. 

En el siguiente ejemplo, se muestra cómo utilizar la URL generada. Este código se genera en el servidor de aplicaciones.

### SDK 2.0
<a name="embedded-q-bar-for-authenticated-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>Q Search Bar Embedding Example</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.0.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            const embedQSearchBar = async() => {    
                const {
                    createEmbeddingContext,
                } = QuickSightEmbedding;

                const embeddingContext = await createEmbeddingContext({
                    onChange: (changeEvent, metadata) => {
                        console.log('Context received a change', changeEvent, metadata);
                    },
                });

                const frameOptions = {
                    url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
                    container: '#experience-container',
                    height: "700px",
                    width: "1000px",
                    onChange: (changeEvent, metadata) => {
                        switch (changeEvent.eventName) {
                            case 'FRAME_MOUNTED': {
                                console.log("Do something when the experience frame is mounted.");
                                break;
                            }
                            case 'FRAME_LOADED': {
                                console.log("Do something when the experience frame is loaded.");
                                break;
                            }
                        }
                    },
                };

                const contentOptions = {
                    hideTopicName: false, 
                    theme: '<YOUR_THEME_ID>',
                    allowTopicSelection: true,
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'Q_SEARCH_OPENED': {
                                console.log("Do something when Q Search content expanded");
                                break;
                            }
                            case 'Q_SEARCH_CLOSED': {
                                console.log("Do something when Q Search content collapsed");
                                break;
                            }
                            case 'Q_SEARCH_SIZE_CHANGED': {
                                console.log("Do something when Q Search size changed");
                                break;
                            }
                            case 'CONTENT_LOADED': {
                                console.log("Do something when the Q Search is loaded.");
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Do something when the Q Search fails loading.");
                                break;
                            }
                        }
                    }
                };
                const embeddedDashboardExperience = await embeddingContext.embedQSearchBar(frameOptions, contentOptions);
            };
        </script>
    </head>

    <body onload="embedQSearchBar()">
        <div id="experience-container"></div>
    </body>

</html>
```

### SDK 1.0
<a name="embedded-q-bar-for-authenticated-users-sdkv1"></a>

```
<!DOCTYPE html>
<html>

    <head>
        <title>QuickSight Q Search Bar Embedding</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.18.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            var session

            function onError(payload) {
                console.log("Do something when the session fails loading");
            }

            function onOpen() {
                console.log("Do something when the Q search bar opens");
            }

            function onClose() {
                console.log("Do something when the Q search bar closes");
            }

            function embedQSearchBar() {
                var containerDiv = document.getElementById("embeddingContainer");
                var options = {
                    url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode", // replace this dummy url with the one generated via embedding API
                    container: containerDiv,
                    width: "{{1000px}}",
                    locale: "{{en-US}}",
                    qSearchBarOptions: {
                        expandCallback: onOpen,
                        collapseCallback: onClose,
                        iconDisabled: false,
                        topicNameDisabled: false, 
                        themeId: '{{bdb844d0-0fe9-4d9d-b520-0fe602d93639}}',
                        allowTopicSelection: true
                    }
                };
                session = QuickSightEmbedding.embedQSearchBar(options);
                session.on("error", onError);
            }

            function onCountryChange(obj) {
                session.setParameters({country: obj.value});
            }
        </script>
    </head>

    <body onload="embedQSearchBar()">
        <div id="embeddingContainer"></div>
    </body>

</html>
```

Para que este ejemplo funcione, asegúrese de utilizar el SDK de incrustación de Amazon Quick Sight para cargar el panel integrado en su sitio web utilizando JavaScript. Para obtener su copia, siga uno de estos pasos:
+ Descargue el [SDK de incrustación de Amazon Quick Sight](https://github.com/awslabs/amazon-quicksight-embedding-sdk#step-3-create-the-quicksight-session-object) desde GitHub. Este repositorio lo mantiene un grupo de desarrolladores de Amazon Quick Sight.
+ Descargue la última versión del SDK de incrustación desde [https://www.npmjs.com/package/amazon-quicksight-embedding-sdk](https://www.npmjs.com/package/amazon-quicksight-embedding-sdk).
+ Si lo usas `npm` para JavaScript dependencias, descárgalo e instálalo ejecutando el siguiente comando.

  ```
  npm install amazon-quicksight-embedding-sdk
  ```

## Funcionalidades opcionales de incrustación en la barra de búsqueda Quick Sight Q de Amazon
<a name="embedded-q-bar-for-authenticated-users-step-4"></a>

**nota**  
La barra de búsqueda integrada de Amazon Quick Sight Q ofrece la clásica experiencia de preguntas y respuestas de Amazon Quick Sight. Amazon Quick Sight se integra con Amazon Q Business para lanzar una nueva experiencia de preguntas y respuestas generativas. Se recomienda a los desarrolladores usar la nueva experiencia de preguntas y respuestas generativas. Para obtener más información sobre la experiencia de preguntas y respuestas generativas integrada, consulte Cómo [integrar Amazon Q en la experiencia de preguntas y respuestas generativas de Amazon Quick Sight](https://docs.aws.amazon.com/quicksight/latest/user/embedding-gen-bi.html).

Las siguientes funcionalidades opcionales están disponibles para la barra de búsqueda de Q integrada mediante el SDK de integración. 

### Invocación de las acciones de la barra de búsqueda de Q
<a name="w2aac37c29c21c43c31c15c21b7"></a>

Las siguientes opciones solo son compatibles con la integración de la barra de búsqueda de Q. 
+ Establecer una pregunta en la barra de búsqueda de Q: esta característica envía una pregunta a la barra de búsqueda de Q e inmediatamente la consulta. También abre automáticamente la ventana emergente de Q.

  ```
  qBar.setQBarQuestion('{{show me monthly revenue}}');
  ```
+ Cerrar la ventana emergente de Q: esta característica cierra la ventana emergente de Q y devuelve el iframe al tamaño original de la barra de búsqueda de Q.

  ```
  qBar.closeQPopover();
  ```

Para obtener más información, consulte el [SDK de incrustación de Amazon Quick Sight](https://github.com/awslabs/amazon-quicksight-embedding-sdk).