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.

# Integración de Amazon Q en la experiencia generativa de preguntas y respuestas de Amazon Quick Sight
<a name="embedding-gen-bi"></a>


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

En las siguientes secciones, puede encontrar información detallada sobre cómo configurar una experiencia de preguntas y respuestas generativas integrada que utilice las capacidades de NLQ mejoradas impulsadas por. LLMs La experiencia de preguntas y respuestas generativas es el sustituto recomendado de la barra de búsqueda Q incrustada y proporciona a los usuarios una experiencia de BI actualizada.

**Topics**
+ [Integración de Amazon Q en Amazon Quick Sight: una experiencia generativa de preguntas y respuestas para usuarios registrados](#embedded-analytics-gen-bi-authenticated-users)
+ [Integración de Amazon Q en la experiencia de preguntas y respuestas de Quick Generative para usuarios anónimos (no registrados)](#embedded-analytics-gen-bi-anonymous-users)

## Integración de Amazon Q en Amazon Quick Sight: una experiencia generativa de preguntas y respuestas para usuarios registrados
<a name="embedded-analytics-gen-bi-authenticated-users"></a>

En las siguientes secciones, encontrará información detallada sobre cómo configurar una experiencia de preguntas y respuestas generativas integrada para los usuarios registrados de Amazon Quick Sight.

**Topics**
+ [Paso 1: configuración de permisos](#embedded-analytics-gen-bi-authenticated-users-step-1)
+ [Paso 2: generación de la URL con el código de autenticación adjunto](#embedded-analytics-gen-bi-authenticated-users-step-2)
+ [Paso 3: incrustación de la URL de la experiencia de preguntas y respuestas generativas](#embedded-analytics-gen-bi-authenticated-users-step-3)
+ [Funcionalidades opcionales de la experiencia de preguntas y respuestas generativas incrustada](#embedded-analytics-gen-bi-authenticated-users-step-4)

### Paso 1: configuración de permisos
<a name="embedded-analytics-gen-bi-authenticated-users-step-1"></a>

En la siguiente sección, encontrará información sobre cómo configurar los permisos de la aplicación de backend o del servidor web para incrustar la experiencia de preguntas y respuestas generativas. Esta tarea requiere acceso administrativo a AWS Identity and Access Management (IAM).

Cada usuario que accede a una experiencia de preguntas y respuestas generativas asume un rol que le otorga acceso y permisos a Amazon Quick Sight. Para ello, 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. La función de IAM debe proporcionar permisos para recuperar la incrustación URLs de un grupo de usuarios específico. 

Con la ayuda del carácter comodín *\$1*, 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 experiencia de preguntas y respuestas generativas. 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, URLs todo lo siguiente tiene 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-analytics-gen-bi-authenticated-users-step-2"></a>

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 integrar la experiencia de preguntas y respuestas generativas 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. La seguridad de filas basada en etiquetas puede utilizarse para la incrustación de usuarios anónimos en la barra de Q.

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-analytics-gen-bi-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.RegisteredUserGenerativeQnAEmbeddingConfiguration;

/**
 * Class to call QuickSight AWS SDK to get url for embedding Generative Q&A experience.
 */
public class RegisteredUserGenerativeQnAEmbeddingSample {

    private final AmazonQuickSight quickSightClient;

    public RegisteredUserGenerativeQnAEmbeddingSample() {
        this.quickSightClient = AmazonQuickSightClientBuilder
                    .standard()
                    .withRegion(Regions.US_EAST_1.getName())
                    .withCredentials(new AWS CredentialsProvider() {
                            @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()
                .withGenerativeQnA(new RegisteredUserGenerativeQnAEmbeddingConfiguration().withInitialTopicId(topicId));
        final GenerateEmbedUrlForRegisteredUserRequest generateEmbedUrlForRegisteredUserRequest = new GenerateEmbedUrlForRegisteredUserRequest();
        generateEmbedUrlForRegisteredUserRequest.setAwsAccountId(accountId);
        generateEmbedUrlForRegisteredUserRequest.setUserArn(userArn);
        generateEmbedUrlForRegisteredUserRequest.setAllowedDomains(allowedDomains);
        generateEmbedUrlForRegisteredUserRequest.setExperienceConfiguration(experienceConfiguration);

        final GenerateEmbedUrlForRegisteredUserResult generateEmbedUrlForRegisteredUserResult = quickSightClient.generateEmbedUrlForRegisteredUser(generateEmbedUrlForRegisteredUserRequest);

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

#### JavaScript
<a name="embedded-analytics-gen-bi-authenticated-users-js"></a>

**nota**  
La generación de URL incrustadas APIs no se puede invocar directamente desde los navegadores. En su lugar, consulte el ejemplo de Node.JS.

#### Python3
<a name="embedded-analytics-gen-bi-authenticated-users-py"></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 = {
                    'GenerativeQnA': {
                        '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-analytics-gen-bi-authenticated-users-node"></a>

El siguiente ejemplo muestra el archivo 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({
    region: 'us-east-1'
});

quicksightClient.generateEmbedUrlForRegisteredUser({
    'AwsAccountId': '111122223333',
    'ExperienceConfiguration': { 
        'GenerativeQnA': {
            '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);
});
```

#### .NET/C\$1
<a name="embedded-analytics-gen-bi-authenticated-users-cs"></a>

En el siguiente ejemplo, se muestra el código .NET/C\$1 que puede usar en el servidor de aplicaciones para generar la URL de la sesión de la barra de búsqueda de Q. 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 GenerateGenerativeQnAEmbedUrlForRegisteredUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                RegisteredUserGenerativeQnAEmbeddingConfiguration registeredUserGenerativeQnAEmbeddingConfiguration
                    = new RegisteredUserGenerativeQnAEmbeddingConfiguration
                    {
                        InitialTopicId = "U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f"
                    };
                RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
                    = new RegisteredUserEmbeddingExperienceConfiguration
                    {
                        GenerativeQnA = registeredUserGenerativeQnAEmbeddingConfiguration
                    }; 
                
                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-analytics-gen-bi-authenticated-users-cli"></a>

Para asumir la función, elija 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 opta por añadir just-in-time usuarios cuando utilizan un tema en la barra de búsqueda de Q, el rol también necesita tener habilitados los permisos. `quicksight:RegisterUser`

```
aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_q_generative_qna_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\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

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 experiencia de preguntas y respuestas generativas. 

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_generative_qna_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_generative_qna_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-anonymous-user \
--aws-account-id 111122223333 \
--namespace default-or-something-else \
--authorized-resource-arns '["topic-arn-topicId1","topic-arn-topicId2"]' \
--allowed-domains '["domain1","domain2"]' \
--experience-configuration 'GenerativeQnA={InitialTopicId="topicId1"}' \
--session-tags '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]' \
--session-lifetime-in-minutes 15
```

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: incrustación de la URL de la experiencia de preguntas y respuestas generativas
<a name="embedded-analytics-gen-bi-authenticated-users-step-3"></a>

En la siguiente sección, encontrará información sobre cómo incrustar la URL de la experiencia de preguntas y respuestas generativas 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 experiencia de preguntas y respuestas generativas en una página HTML.
+ Personalizar el diseño y la apariencia de la experiencia incrustada para adaptarla a las necesidades de su aplicación.
+ 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"
}
```

Incorpore la experiencia de preguntas y respuestas generativas en su 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. 

Asegúrese de que el dominio que alojará la experiencia de preguntas y respuestas generativas integrada esté en la lista de dominios *permitidos, la lista* de dominios aprobados para su 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 agregar dominios para la experiencia de preguntas y respuestas generativas incrustada, consulte [Administrar dominios](manage-domains.md).

Puede utilizar el SDK de incrustación Quick Sight de Amazon para personalizar el diseño y la apariencia de la experiencia de preguntas y respuestas generativas integrada para adaptarla a su aplicación. Use la propiedad `panelType` para configurar el estado inicial de la experiencia de preguntas y respuestas generativas cuando se muestre en su aplicación. Establezca la propiedad `panelType` en `'FULL'` para que represente el panel completo de la experiencia de preguntas y respuestas generativas. Este panel se parece a la experiencia que tienen los usuarios de Amazon Quick Sight en la consola Amazon Quick Sight. La altura del marco del panel no cambia en función de la interacción del usuario y respeta el valor establecido en la propiedad `frameOptions.height`. La siguiente imagen muestra el panel de la experiencia de preguntas y respuestas generativas que se representa cuando se establece el valor `panelType` en `'FULL'`.

Establezca la propiedad `panelType` en `'SEARCH_BAR'` para que represente la experiencia de preguntas y respuestas generativas como una barra de búsqueda. Esta barra de búsqueda se parece a la forma en que se representa la barra de búsqueda de Q cuando está incrustada en una aplicación. La barra de búsqueda preguntas y respuestas generativas se expande hasta convertirse en un panel más grande que muestra las opciones de selección de temas, la lista de sugerencias de preguntas, el panel de respuestas o el tablón de anuncios.

La altura mínima predeterminada de la barra de búsqueda de preguntas y respuestas generativas se representa cuando se carga el recurso incrustado. Se recomienda establecer el valor `frameOptions.height` en `"38px"` para optimizar la experiencia de la barra de búsqueda. Use la propiedad `focusedHeight` para establecer el tamaño óptimo del menú desplegable de selección de temas y de la lista de sugerencias de preguntas. Utilice la propiedad `expandedHeight` para establecer el tamaño óptimo del panel de respuestas y del tablón de anuncios. Si elige la opción `'SEARCH_BAR'`, se recomienda diseñar el contenedor principal con una posición (absoluta) para evitar que contenido no deseado se desplace en la aplicación. La siguiente imagen muestra la barra de búsqueda de la experiencia de preguntas y respuestas generativas que se representa cuando se establece el valor `panelType` en `'SEARCH_BAR'`.

Tras configurar la `panelType` propiedad, utilice el SDK de incrustación de Amazon Quick Sight para personalizar las siguientes propiedades de la experiencia de preguntas y respuestas generativas.
+ El título del panel de preguntas y respuestas generativas (solo se aplica a la opción `panelType: FULL`). 
+ El texto del marcador de posición de la barra de búsqueda.
+ Si se permite la selección de temas.
+ Si se muestran u ocultan los nombres de los temas.
+ Si se muestra u oculta el icono de Amazon Q (solo se aplica a la opción `panelType: FULL`).
+ Si muestra u oculta el tablón de anuncios.
+ Si los usuarios pueden maximizar el panel de preguntas y respuestas generativas a pantalla completa.
+ El tema del panel de preguntas y respuestas generativas. Se puede pasar un ARN de tema personalizado al SDK para cambiar la apariencia del contenido del marco. Los temas de inicio de Amazon Quick Sight no son compatibles con los paneles de BI generativa integrados. Para usar un tema de inicio de Amazon Quick Sight, guárdalo como tema personalizado en Amazon Quick Sight.

Cuando utilizas el SDK de incrustación Quick Sight de Amazon, la experiencia de preguntas y respuestas generativas 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 puede controlar los parámetros de la experiencia de preguntas y respuestas generativas y recibir llamadas en términos de finalización de la carga de la página, cambios de estado y 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="collapsible-gen-bi-embedding-example"></a>

```
<!DOCTYPE html>
<html>
    <head>
        <title>Generative Q&A Embedding Example</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.7.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            const embedGenerativeQnA = 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 = {
                    // Optional panel settings. Default behavior is equivalent to {panelType: 'FULL'}
                    panelOptions: {
                        panelType: 'FULL',
                        title: 'custom title', // Optional
                        showQIcon: false, // Optional, Default: true
                    },
                    // Use SEARCH_BAR panel type for the landing state to be similar to embedQSearchBar
                    // with generative capability enabled topics
                    /*
                    panelOptions: {
                        panelType: 'SEARCH_BAR',
                        focusedHeight: '250px',
                        expandedHeight: '500px',
                    },
                    */
                    showTopicName: false, // Optional, Default: true
                    showPinboard: false, // Optional, Default: true
                    allowTopicSelection: false, // Optional, Default: true
                    allowFullscreen: false, // Optional, Default: true
                    searchPlaceholderText: "custom search placeholder", // Optional
                    themeOptions: { // Optional
                        themeArn: 'arn:aws:quicksight:<Region>:<AWS-Account-ID>:theme/<Theme-ID>'
                    }
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'Q_SEARCH_OPENED': {
                                // called when pinboard is shown / visuals are rendered
                                console.log("Do something when SEARCH_BAR type panel is expanded");
                                break;
                            }
                            case 'Q_SEARCH_FOCUSED': {
                                // called when question suggestions or topic selection dropdown are shown
                                console.log("Do something when SEARCH_BAR type panel is focused");
                                break;
                            }
                            case 'Q_SEARCH_CLOSED': {
                                // called when shrinked to initial bar height
                                console.log("Do something when SEARCH_BAR type panel is collapsed");
                                break;
                            }
                            case 'Q_PANEL_ENTERED_FULLSCREEN': {
                                console.log("Do something when panel enters full screen mode");
                                break;
                            }
                            case 'Q_PANEL_EXITED_FULLSCREEN': {
                                console.log("Do something when panel exits full screen mode");
                                break;
                            }
                            case 'CONTENT_LOADED': {
                                console.log("Do something after experience is loaded");
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Do something when experience fails to load");
                                break;
                            }
                        }
                    }
                };
                const embeddedGenerativeQnExperience = await embeddingContext.embedGenerativeQnA(frameOptions, contentOptions);
            };
        </script>
    </head>

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

</html>
```

Para que este ejemplo funcione, asegúrate de usar el SDK de incrustación de Amazon Quick Sight para cargar la experiencia de preguntas y respuestas generativas integrada en tu sitio web. 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 la experiencia de preguntas y respuestas generativas incrustada
<a name="embedded-analytics-gen-bi-authenticated-users-step-4"></a>

A continuación se detallan las funcionalidades opcionales que están disponibles para la experiencia de preguntas y respuestas generativas con el SDK de incrustación. 

#### Invocación de acciones de la barra de preguntas y respuestas generativas
<a name="w2aac35c27c21c43c29b9c21b5"></a>
+ Establecer una pregunta: esta característica envía una pregunta a la experiencia de preguntas y respuestas generativas y consulta la pregunta de inmediato.

  ```
  embeddedGenerativeQnExperience.setQuestion('show me monthly revenue');
  ```
+ Cerrar el panel de respuestas (se aplica a la opción de la barra de búsqueda preguntas y respuestas generativas): esta característica cierra el panel de respuestas y devuelve el iframe al estado original de la barra de búsqueda.

  ```
  embeddedGenerativeQnExperience.close();
  ```

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

## Integración de Amazon Q en la experiencia de preguntas y respuestas de Quick Generative para usuarios anónimos (no registrados)
<a name="embedded-analytics-gen-bi-anonymous-users"></a>


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

En las secciones siguientes, encontrará información detallada sobre cómo configurar una experiencia de preguntas y respuestas generativas incrustada para usuarios anónimos (no registrados).

**Topics**
+ [Paso 1: configuración de permisos](#embedded-analytics-gen-bi-anonymous-users-step-1)
+ [Paso 2: generación de la URL con el código de autenticación adjunto](#embedded-analytics-gen-bi-anonymous-users-step-2)
+ [Paso 3: incrustación de la URL de la experiencia de preguntas y respuestas generativas](#embedded-analytics-gen-bi-anonymous-users-step-3)
+ [Funcionalidades opcionales de la experiencia de preguntas y respuestas generativas incrustada](#embedded-analytics-gen-bi-anonymous-users-step-4)

### Paso 1: configuración de permisos
<a name="embedded-analytics-gen-bi-anonymous-users-step-1"></a>

En la siguiente sección, encontrará información sobre cómo configurar los permisos de la aplicación de backend o del servidor web para incrustar la experiencia de preguntas y respuestas generativas. Esta tarea requiere acceso administrativo a AWS Identity and Access Management (IAM).

Cada usuario que accede a una experiencia de preguntas y respuestas generativas asume un rol que le otorga acceso y permisos a Amazon Quick Sight. Para ello, 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. La función de IAM debe proporcionar permisos para recuperar la incrustación URLs de un grupo de usuarios específico. 

Con la ayuda del carácter comodín *\$1*, 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:GenerateEmbedUrlForAnonymousUser`.

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 `GenerateEmbedUrlForAnonymousUser`. 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 [GenerateEmbedUrlForAnonymousUser](https://docs.aws.amazon.com//quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.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, URLs todo lo siguiente tiene 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 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 el rol en nombre del usuario para cargar la experiencia de preguntas y respuestas generativas. 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, consulte [Credenciales de seguridad temporales en IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) en la *Guía del usuario de IAM*

### Paso 2: generación de la URL con el código de autenticación adjunto
<a name="embedded-analytics-gen-bi-anonymous-users-step-2"></a>

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.

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. 

#### Java
<a name="embedded-analytics-gen-bi-anonymous-users-java"></a>

```
import java.util.List;
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.quicksight.AmazonQuickSight;
import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.AnonymousUserGenerativeQnAEmbeddingConfiguration;
import com.amazonaws.services.quicksight.model.AnonymousUserEmbeddingExperienceConfiguration;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForAnonymousUserRequest;
import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForAnonymousUserResult;
import com.amazonaws.services.quicksight.model.SessionTag;

/**
* Class to call QuickSight AWS SDK to generate embed url for anonymous user.
*/
public class GenerateEmbedUrlForAnonymousUserExample {

    private final AmazonQuickSight quickSightClient;

    public GenerateEmbedUrlForAnonymousUserExample() {
        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 GenerateEmbedUrlForAnonymousUser(
        final String accountId, // YOUR AWS ACCOUNT ID
        final String initialTopicId, // Q TOPIC ID TO WHICH THE CONSTRUCTED URL POINTS AND EXPERIENCE PREPOPULATES INITIALLY
        final String namespace, // ANONYMOUS EMBEDDING REQUIRES SPECIFYING A VALID NAMESPACE FOR WHICH YOU WANT THE EMBEDDING URL
        final List<String> authorizedResourceArns, // Q TOPIC ARN LIST TO EMBED
        final List<String> allowedDomains, // RUNTIME ALLOWED DOMAINS FOR EMBEDDING
        final List<SessionTag> sessionTags // SESSION TAGS USED FOR ROW-LEVEL SECURITY
    ) throws Exception {
        AnonymousUserEmbeddingExperienceConfiguration experienceConfiguration = new AnonymousUserEmbeddingExperienceConfiguration();
        AnonymousUserGenerativeQnAEmbeddingConfiguration generativeQnAConfiguration = new AnonymousUserGenerativeQnAEmbeddingConfiguration();
        generativeQnAConfiguration.setInitialTopicId(initialTopicId);
        experienceConfiguration.setGenerativeQnA(generativeQnAConfiguration);

        GenerateEmbedUrlForAnonymousUserRequest generateEmbedUrlForAnonymousUserRequest = new GenerateEmbedUrlForAnonymousUserRequest()
            .withAwsAccountId(accountId)
            .withNamespace(namespace)
            .withAuthorizedResourceArns(authorizedResourceArns)
            .withExperienceConfiguration(experienceConfiguration)
            .withSessionTags(sessionTags)
            .withSessionLifetimeInMinutes(600L); // OPTIONAL: VALUE CAN BE [15-600]. DEFAULT: 600
            .withAllowedDomains(allowedDomains);

        GenerateEmbedUrlForAnonymousUserResult result = quickSightClient.generateEmbedUrlForAnonymousUser(generateEmbedUrlForAnonymousUserRequest);

        return result.getEmbedUrl();
    }

}
```

#### JavaScript
<a name="embedded-analytics-gen-bi-anonymous-users-js"></a>

**nota**  
 APIs No se puede acceder directamente a la generación de URL incrustadas desde los navegadores. En su lugar, consulte el ejemplo de Node.JS.

#### Python3
<a name="embedded-analytics-gen-bi-anonymous-users-py"></a>

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

# Create QuickSight and STS clients
quicksightClient = boto3.client('quicksight',region_name='us-west-2')
sts = boto3.client('sts')

# Function to generate embedded URL for anonymous user
# accountId: YOUR AWS ACCOUNT ID
# topicId: Topic ID to embed
# quicksightNamespace: VALID NAMESPACE WHERE YOU WANT TO DO NOAUTH EMBEDDING
# authorizedResourceArns: TOPIC ARN LIST TO EMBED
# allowedDomains: RUNTIME ALLOWED DOMAINS FOR EMBEDDING
# sessionTags: SESSION TAGS USED FOR ROW-LEVEL SECURITY
def generateEmbedUrlForAnonymousUser(accountId, quicksightNamespace, authorizedResourceArns, allowedDomains, sessionTags):
    try:
        response = quicksightClient.generate_embed_url_for_anonymous_user(
            AwsAccountId = accountId,
            Namespace = quicksightNamespace,
            AuthorizedResourceArns = authorizedResourceArns,
            AllowedDomains = allowedDomains,
            ExperienceConfiguration = {
                'GenerativeQnA': {
                        'InitialTopicId': topicId
                    }
            },
            SessionTags = sessionTags,
            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
<a name="embedded-analytics-gen-bi-anonymous-users-node"></a>

El siguiente ejemplo muestra el archivo 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({
    region: 'us-east-1',
});

quicksightClient.generateEmbedUrlForAnonymousUser({
    'AwsAccountId': '111122223333',
    'Namespace': 'DEFAULT'
    'AuthorizedResourceArns': '["topic-arn-topicId1","topic-arn-topicId2"]',
    'AllowedDomains': allowedDomains,
    'ExperienceConfiguration': { 
        'GenerativeQnA': {
            'InitialTopicId': 'U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f'
        }
    },
    'SessionTags': '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]',
    'SessionLifetimeInMinutes': 15
}, function(err, data) {
    console.log('Errors: ');
    console.log(err);
    console.log('Response: ');
    console.log(data);
});
```

#### .NET/C\$1
<a name="embedded-analytics-gen-bi-anonymous-users-cs"></a>

En el siguiente ejemplo, se muestra el código .NET/C\$1 que puede usar en el servidor de aplicaciones para generar la URL de la sesión de la barra de búsqueda de Q. 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 GenerateGenerativeQnAEmbedUrlForAnonymousUser
{
    class Program
    {
        static void Main(string[] args)
        {
            var quicksightClient = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                SessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                AnonymousUserGenerativeQnAEmbeddingConfiguration anonymousUserGenerativeQnAEmbeddingConfiguration
                    = new AnonymousUserGenerativeQnAEmbeddingConfiguration
                    {
                        InitialTopicId = "U4zJMVZ2n2stZflc8Ou3iKySEb3BEV6f"
                    };
                AnonymousUserEmbeddingExperienceConfiguration anonymousUserEmbeddingExperienceConfiguration
                    = new AnonymousUserEmbeddingExperienceConfiguration
                    {
                        GenerativeQnA = anonymousUserGenerativeQnAEmbeddingConfiguration
                    }; 
                
                Console.WriteLine(
                    quicksightClient.GenerateEmbedUrlForAnonymousUserAsync(new GenerateEmbedUrlForAnonymousUserRequest
                    {
                        AwsAccountId = "111122223333",
                        Namespace = "DEFAULT",
                        AuthorizedResourceArns '["topic-arn-topicId1","topic-arn-topicId2"]',
                        AllowedDomains = allowedDomains,
                        ExperienceConfiguration = anonymousUserEmbeddingExperienceConfiguration,
                        SessionTags = '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]',
                        SessionLifetimeInMinutes = 15,
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }
        }
    }
}
```

#### AWS CLI
<a name="embedded-analytics-gen-bi-anonymous-users-cli"></a>

Para asumir la función, elija 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:GenerateEmbedUrlForAnonymousUser` habilitados.

```
aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_generative_qna_role" \
     --role-session-name anonymous caller
```

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\$1ACCESS\$1KEY\$1ID* 
*AWS\$1SECRET\$1ACCESS\$1KEY* 
*AWS\$1SESSION\$1TOKEN* 

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/QuickSightEmbeddingAnonymousPolicy`. 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. Además, mantiene cada sesión separada y distinta. Si utiliza una serie de servidores web, por ejemplo, para equilibrar la carga, y una sesión se vuelve a conectar a un servidor diferente, se inicia una nueva sesión.

Para obtener una URL firmada para el panel, llame a `generate-embed-url-for-anynymous-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 que realizan visitas anónimas a su portal web o aplicación.

```
aws quicksight generate-embed-url-for-anonymous-user \
--aws-account-id 111122223333 \
--namespace default-or-something-else \
--authorized-resource-arns '["topic-arn-topicId","topic-arn-topicId2"]' \
--allowed-domains '["domain1","domain2"]' \
--experience-configuration 'GenerativeQnA={InitialTopicId="topicId1"}' \
--session-tags '["Key": tag-key-1,"Value": tag-value-1,{"Key": tag-key-1,"Value": tag-value-1}]' \
--session-lifetime-in-minutes 15
```

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

### Paso 3: incrustación de la URL de la experiencia de preguntas y respuestas generativas
<a name="embedded-analytics-gen-bi-anonymous-users-step-3"></a>

En la siguiente sección, encontrará información sobre cómo incrustar la URL de la experiencia de preguntas y respuestas generativas 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 experiencia de preguntas y respuestas generativas en una página HTML.
+ Personalizar el diseño y la apariencia de la experiencia incrustada para adaptarla a las necesidades de su aplicación.
+ Resolver los estados de error con mensajes que se personalizan en su aplicación.

Llame a la operación de la API `GenerateEmbedUrlForAnonymousUser` 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-anonymous-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"
}
```

Incorpore la experiencia de preguntas y respuestas generativas en su página web con 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. 

Asegúrese de que el dominio en el que se alojará la experiencia de preguntas y respuestas generativas esté en la lista de dominios *permitidos, la lista* de dominios aprobados para su suscripción a Amazon Quick Sight. Este requisito protege los datos al impedir que dominios no aprobados alojen experiencias de preguntas y respuestas generativas incrustadas. Para obtener más información sobre cómo agregar dominios para la experiencia de preguntas y respuestas generativas incrustada, consulte [Administrar dominios](manage-domains.md).

Puede utilizar el SDK de incrustación Quick Sight de Amazon para personalizar el diseño y la apariencia de la experiencia de preguntas y respuestas generativas integrada para adaptarla a su aplicación. Use la propiedad `panelType` para configurar el estado inicial de la experiencia de preguntas y respuestas generativas cuando se muestre en su aplicación. Establezca la propiedad `panelType` en `'FULL'` para que represente el panel completo de la experiencia de preguntas y respuestas generativas. Este panel se parece a la experiencia que tienen los usuarios de Amazon Quick Sight en la consola Amazon Quick Sight. La altura del marco del panel no cambia en función de la interacción del usuario y respeta el valor establecido en la propiedad `frameOptions.height`. La siguiente imagen muestra el panel de la experiencia de preguntas y respuestas generativas que se representa cuando se establece el valor `panelType` en `'FULL'`.

Establezca la propiedad `panelType` en `'SEARCH_BAR'` para que represente la experiencia de preguntas y respuestas generativas como una barra de búsqueda. Esta barra de búsqueda se parece a la forma en que se representa la barra de búsqueda de Q cuando está incrustada en una aplicación. La barra de búsqueda preguntas y respuestas generativas se expande hasta convertirse en un panel más grande que muestra las opciones de selección de temas, la lista de sugerencias de preguntas, el panel de respuestas o el tablón de anuncios.

La altura mínima predeterminada de la barra de búsqueda de preguntas y respuestas generativas se representa cuando se carga el recurso incrustado. Se recomienda establecer el valor `frameOptions.height` en `"38px"` para optimizar la experiencia de la barra de búsqueda. Use la propiedad `focusedHeight` para establecer el tamaño óptimo del menú desplegable de selección de temas y de la lista de sugerencias de preguntas. Utilice la propiedad `expandedHeight` para establecer el tamaño óptimo del panel de respuestas y del tablón de anuncios. Si elige la opción `'SEARCH_BAR'`, se recomienda diseñar el contenedor principal con una posición (absoluta) para evitar que contenido no deseado se desplace en la aplicación. La siguiente imagen muestra la barra de búsqueda de la experiencia de preguntas y respuestas generativas que se representa cuando se establece el valor `panelType` en `'SEARCH_BAR'`.

Tras configurar la `panelType` propiedad, utilice el SDK de incrustación de Amazon Quick Sight para personalizar las siguientes propiedades de la experiencia de preguntas y respuestas generativas.
+ El título del panel de preguntas y respuestas generativas (solo se aplica a la opción `panelType: FULL`). 
+ El texto del marcador de posición de la barra de búsqueda.
+ Si se permite la selección de temas.
+ Si se muestran u ocultan los nombres de los temas.
+ Si se muestra u oculta el icono de Amazon Q (solo se aplica a la opción `panelType: FULL`).
+ Si muestra u oculta el tablón de anuncios.
+ Si los usuarios pueden maximizar el panel de preguntas y respuestas generativas a pantalla completa.
+ El tema del panel de preguntas y respuestas generativas. Se puede pasar un ARN de tema personalizado al SDK para cambiar la apariencia del contenido del marco. Los temas de inicio de Amazon Quick Sight no son compatibles con los paneles de BI generativa integrados. Para usar un tema de inicio de Amazon Quick Sight, guárdalo como tema personalizado en Amazon Quick Sight.

Cuando utilizas el SDK de incrustación Quick Sight de Amazon, la experiencia de preguntas y respuestas generativas de tu página cambia de tamaño de forma dinámica en función del estado. Con el SDK de incrustación Quick Sight de Amazon, también puede controlar los parámetros de la experiencia de preguntas y respuestas generativas y recibir llamadas en términos de finalización de la carga de la página, cambios de estado y 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-analytics-gen-bi-anonymous-users-sdkv2"></a>

```
<!DOCTYPE html>
<html>
    <head>
        <title>Generative Q&A Embedding Example</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.7.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            const embedGenerativeQnA = 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 = {
                    // Optional panel settings. Default behavior is equivalent to {panelType: 'FULL'}
                    panelOptions: {
                        panelType: 'FULL',
                        title: 'custom title', // Optional
                        showQIcon: false, // Optional, Default: true
                    },
                    // Use SEARCH_BAR panel type for the landing state to be similar to embedQSearchBar
                    // with generative capability enabled topics
                    /*
                    panelOptions: {
                        panelType: 'SEARCH_BAR',
                        focusedHeight: '250px',
                        expandedHeight: '500px',
                    },
                    */
                    showTopicName: false, // Optional, Default: true
                    showPinboard: false, // Optional, Default: true
                    allowTopicSelection: false, // Optional, Default: true
                    allowFullscreen: false, // Optional, Default: true
                    searchPlaceholderText: "custom search placeholder", // Optional
                    themeOptions: { // Optional
                        themeArn: 'arn:aws:quicksight:<Region>:<AWS-Account-ID>:theme/<Theme-ID>'
                    }
                    onMessage: async (messageEvent, experienceMetadata) => {
                        switch (messageEvent.eventName) {
                            case 'Q_SEARCH_OPENED': {
                                // called when pinboard is shown / visuals are rendered
                                console.log("Do something when SEARCH_BAR type panel is expanded");
                                break;
                            }
                            case 'Q_SEARCH_FOCUSED': {
                                // called when question suggestions or topic selection dropdown are shown
                                console.log("Do something when SEARCH_BAR type panel is focused");
                                break;
                            }
                            case 'Q_SEARCH_CLOSED': {
                                // called when shrinked to initial bar height
                                console.log("Do something when SEARCH_BAR type panel is collapsed");
                                break;
                            }
                            case 'Q_PANEL_ENTERED_FULLSCREEN': {
                                console.log("Do something when panel enters full screen mode");
                                break;
                            }
                            case 'Q_PANEL_EXITED_FULLSCREEN': {
                                console.log("Do something when panel exits full screen mode");
                                break;
                            }
                            case 'CONTENT_LOADED': {
                                console.log("Do something after experience is loaded");
                                break;
                            }
                            case 'ERROR_OCCURRED': {
                                console.log("Do something when experience fails to load");
                                break;
                            }
                        }
                    }
                };
                const embeddedGenerativeQnExperience = await embeddingContext.embedGenerativeQnA(frameOptions, contentOptions);
            };
        </script>
    </head>

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

</html>
```

Para que este ejemplo funcione, asegúrate de usar el SDK de incrustación de Amazon Quick Sight para cargar la experiencia de preguntas y respuestas generativas integrada en tu sitio web. 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 la experiencia de preguntas y respuestas generativas incrustada
<a name="embedded-analytics-gen-bi-anonymous-users-step-4"></a>

A continuación se detallan las funcionalidades opcionales que están disponibles para la experiencia de preguntas y respuestas generativas con el SDK de incrustación. 

#### Invocación de acciones de la barra de preguntas y respuestas generativas
<a name="w2aac35c27c21c43c29c13c25b5"></a>
+ Establecer una pregunta: esta característica envía una pregunta a la experiencia de preguntas y respuestas generativas y consulta la pregunta de inmediato.

  ```
  embeddedGenerativeQnExperience.setQuestion('show me monthly revenue');
  ```
+ Cerrar el panel de respuestas (se aplica a la opción de la barra de búsqueda preguntas y respuestas generativas): esta característica cierra el panel de respuestas y devuelve el iframe al estado original de la barra de búsqueda.

  ```
  embeddedGenerativeQnExperience.close();
  ```

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