Ayuda de Tableau Cloud

A partir de junio de 2022, con las aplicaciones conectadas de Tableau, puede llamar y acceder mediante programación a la API de REST de Tableau a través de su aplicación personalizada en nombre de los usuarios de Tableau Cloud. El acceso a la API de REST está habilitado por un JSON Web Token (JWT) definido como parte de la solicitud de inicio de sesión inicial. El JWT debe contener alcances que definan los métodos de la API de REST que están disponibles para su aplicación personalizada y sus usuarios a través de la aplicación conectada.

Autorice el acceso a la API de REST usando aplicaciones conectadas para:

• Mejorar la eficiencia: el uso de un JWT como token de portador permite una suplantación simplificada con una solicitud al punto final de inicio de sesión en lugar de dos solicitudes
• Extiender y automatizar integraciones complejas de Tableau y consultas de back-end, como la recuperación de contenido dinámico y el filtrado avanzado.

Acciones de ámbito

Las aplicaciones conectadas usan alcances que otorgan acceso al contenido o acciones administrativas a través de los Métodos de la API de REST que admiten la autorización JWT (a continuación). Un alcance es una cadena separada por dos puntos que comienza con el espacio de nombrestableau, seguido del recurso de Tableau al que se otorga acceso, como datasources y finaliza con la acción que está permitida en el recurso, comoupdate.

Las acciones que un alcance puede tomar incluyen:

• create
• read
• run
• update
• download
• delete

Por ejemplo, un alcance que permite que su aplicación personalizada llame al método Actualizar fuente de datos(El enlace se abre en una ventana nueva) se ve así: tableau:datasources:update

Tipos de alcance

El tipo de ámbito que utilice depende del contenido o la acción administrativa que desee habilitar. Los ámbitos generalmente se dividen en uno de los siguientes tipos: lectura de contenido, individual, comodín y categoría cruzada.

• Ámbito de lectura de contenido: el ámbito de lectura de contenido, tableau:content:read, habilita los métodos GET admitidos para el contenido de Tableau. Cuando usa este ámbito, habilita acciones en las categorías de API de REST. Más específicamente, al usar este ámbito, habilita métodos GET para fuentes de datos, métricas, vistas, libros de trabajo, proyectos y sitios. A partir de Tableau Cloud octubre de 2023, también especificará este alcance en un JWT que se usará para crear un token de credenciales para usar con la API de metadatos(El enlace se abre en una ventana nueva). A partir de Tableau Cloud de febrero de 2025, también especificará este alcance en un JWT que se usará para crear un token de credenciales para usar con VizQL Data Service(El enlace se abre en una ventana nueva).

  Nota: Para habilitar métodos GET para acciones administrativas, como usuarios y grupos, puede usar sus ámbitos individuales.

• Ámbitos individuales: para habilitar el contenido compatible y las acciones administrativas, puede utilizar sus ámbitos individuales. Un ámbito individual generalmente se asocia con un solo método y categoría de API de REST.

  Ejemplos:

  • Para habilitar la acción de publicar o actualizar una fuente de datos, puede usar el ámbito individual tableau:datasources:create o tableau:datasources:update, respectivamente.
  • Para acciones administrativas como agregar o eliminar usuarios, puede usar los ámbitos tableau:users:create o tableau:users:delete, respectivamente.

  Nota: Hay algunos ámbitos individuales que pueden habilitar acciones en las categorías de API de REST. Por ejemplo, tableau:views:download habilita acciones en las categorías de API de REST de ver datos y libros de trabajo.

• Ámbitos comodín (*): para ciertos ámbitos, puede reemplazar la acción con el carácter comodín (*) para habilitar las acciones admitidas dentro de una categoría de API de REST específica.

  Ejemplos:

  • Puedes usar el ámbito comodín tableau:projects:* para habilitar las acciones de creación, eliminación y actualización en la categoría de API de REST de proyectos.
  • Puede usar el ámbito comodín tableau:users:* para habilitar las acciones de get/list, add, delete y update en la categoría de la API de REST de los usuarios.
  • Puede usar el ámbito comodín tableau:tasks:* para habilitar las acciones get/list, add, delete, update y run en la categoría de la API de REST de los usuarios. Además, este ámbito permite actualizar la fuente de datos (si es una extracción) y actualizar el libro de trabajo.

• Ámbitos de categorías cruzadas: además del ámbito de lectura de contenido, existen algunos ámbitos adicionales que, si se utilizan, habilitan acciones admitidas en diferentes categorías de API de REST.

  Ejemplos:

  • Si usa el ámbito tableau:tasks:run, habilita acciones en las fuentes de datos y las categorías de API de REST de libros de trabajo.
  • Nuevamente, si usa el ámbito tableau:views:download, habilita acciones en las categorías de la API de REST de los datos de vista y del libro de trabajo.
  • Si usa ámbitos de permisos como tableau:permissions:update o tableau:permissions:delete, habilita acciones en las fuentes de datos, libros de trabajo y categorías de API de REST de proyectos.

Resumen de cómo autorizar el acceso a la API de REST

La siguiente lista resume los pasos para solicitar acceso a la API de REST a través de un JWT:

1. Cree una aplicación conectada usando uno de los siguientes métodos:
   • Configurar aplicaciones conectadas con confianza directa
   • Configurar aplicaciones conectadas con confianza de OAuth 2.0
2. Genere un JWT válido: en el momento de la ejecución, su aplicación personalizada generará un JWT válido, configurado con los ámbitos que ha incluido
3. Realizar una solicitud de inicio de sesión(El enlace se abre en una ventana nueva): su aplicación personalizada realizará una solicitud de inicio de sesión mediante el JWT para devolver un token de credenciales de Tableau y un ID de sitio (LUID)
4. Utilice el token de acceso de Tableau en las solicitudes posteriores: en las llamadas posteriores a la API de REST, utilice 1) el token de credenciales de Tableau como el valor de encabezado X-Tableau-Auth(El enlace se abre en una ventana nueva) y 2) el ID del sitio (LUID) en el URI de la solicitud

Ejemplo

Por ejemplo, suponga que crea una aplicación conectada mediante confianza directa. Al usar la confianza directa, su aplicación personalizada que llama a la API de REST genera un JWT válido usando la identificación del cliente y el secreto del cliente generado por la aplicación conectada.

Alcances en el JWT

Para autorizar correctamente el acceso a la API de REST, el JWT también debe contener los ámbitos que definen las capacidades de la API de REST. Por ejemplo, para habilitar varios métodos relacionados con la fuente de datos, puede incluir los siguientes ámbitos en el JWT:

"tableau:content:read","tableau:datasources:create","tableau:datasources:update","tableau:datasources:download","tableau:tasks:run"

O

"tableau:content:read","tableau:datasources:*","tableau:tasks:run"

Nota: Los valores de alcance deben pasarse como un tipo de lista.

URI de solicitud de inicio de sesión

Para realizar una llamada a la API de REST, su aplicación personalizada primero debe realizar una solicitud de inicio de sesión para generar un token de credenciales de Tableau.

POST https://us-west-2b.online.tableau.com/api/3.16/auth/signin

Cuerpo de la solicitud

Para autorizar el acceso a la API de REST mediante un JWT, el cuerpo de la solicitud de inicio de sesión debe contener el JWT válido, como en el ejemplo siguiente.

<tsRequest>
   <credentials jwt="eyJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJhbGciOiJIUzI1NiIsImtpZCI6ImIwMTE1YmY5LTNhNGItNGM5MS1iMDA5LWNmMGMxNzBiMWE1NiJ9.eyJhdWQiOiJ0YWJsZWF1Iiwic3ViIjoicm1vaGFuQHRhYmxlYXUuY29tIiwic2NwIjpbInRhYmxlYXU6c2l0ZXM6cmVhZCJdLCJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJleHAiOjE2NDg2Njg0MzksImp0aSI6IjY1ZWFmMmYxLTNmZTgtNDc5Ny1hZmRiLTMyODMzZDVmZGJkYSJ9.mUv2o4gtBTrMVLEXY5XTpzDQTGvfE2LGi-3O2vdGfT8">
    <site contentUrl="mycodotcom"/>
   </credentials>
</tsRequest>

Cuerpo de respuesta

La solicitud de inicio de sesión produce el siguiente cuerpo de respuesta, que incluye el token de credenciales de Tableau.

<tsResponse>
   <credentials token="12ab34cd56ef78ab90cd12ef34ab56cd">
    <site id="9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" contentUrl=""/>
    <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
   </credentials>
</tsResponse>

Después de generar el token de credenciales de Tableau, debe agregarlo al encabezado de todas las solicitudes posteriores de la API de REST.

Encabezado

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

Todas las solicitudes posteriores de la API de REST que usan el token de acceso de Tableau quedan delimitadas por los ámbitos en el JWT.

Métodos de la API de REST que admiten la autorización JWT

Alcances de las aplicaciones conectadas otorga a su aplicación personalizada acceso a las capacidades de la API de REST de Tableau en nombre de los usuarios

Puede encontrar el alcance requerido para un método compatible con JWT en su bloque de propiedades en la ayuda de la API de REST de Tableau(El enlace se abre en una ventana nueva). Si un alcance no aparece en el bloque de propiedades del método, el acceso a ese método no puede ser controlado por un JWT.

Por ejemplo, un ámbito que le permite llamar al método Query Site(El enlace se abre en una ventana nueva) en la API de REST de Tableau es tableau:sites:read

Notas:

• Los métodos Iniciar sesión(El enlace se abre en una ventana nueva) y Cerrar sesión(El enlace se abre en una ventana nueva) son compatibles con la autorización JWT, pero no requieren alcances para su uso a partir de junio de 2023 (Tableau 2023.2).
• Para los alcances compatibles con la API de inserción v3, consulte uno de los siguientes:
  • Configurar aplicaciones conectadas con confianza directa
  • Configurar aplicaciones conectadas con confianza de OAuth 2.0

Acerca de los ámbitos comodín (*)

Los ámbitos comodín utilizan el carácter comodín (*) en lugar de una acción específica, para habilitar múltiples acciones admitidas dentro de una categoría de API de REST de Tableau específica.

Ejemplos

Acerca de los ámbitos entre categorías

Los ámbitos entre categorías permiten múltiples acciones admitidas en múltiples categorías de API de REST de Tableau.

Ejemplos

Solucionar problemas de alcances

401001: error de inicio de sesión

Si encuentra el error 401001, el cuerpo de la respuesta de inicio de sesión se adjunta con uno de los siguientes códigos de error adicionales específicos de las aplicaciones conectadas: 16, 10084 o 10085.

Por ejemplo, en el siguiente cuerpo de respuesta, "10084" es el código de error de las aplicaciones conectadas que puede usar para ayudar a solucionar problemas al iniciar sesión en Tableau Cloud utilizando un JWT para la autorización de la API de REST.

<error code="401001">  
  "summary": "Signin Error",
  "detail": "Error signing in to Tableau Cloud (10084)"
</error>

Para ayudar a resolver el problema, consulte la descripción del código de error aplicable y sus posibles causas.

• 16: No se pudo encontrar el usuario. Este error puede ocurrir porque se ha indicado un valor de "sub " (nombre de usuario) incorrecto

• 10084: No se pudo analizar el token de acceso. Este error puede ocurrir por las siguientes razones:

  • El JWT no es válido o se produjo un problema inesperado
  • Se ha especificado un valor de "aud "(audiencia) incorrecto
  • Para la confianza directa, se produjo un problema con la firma del secreto.

• 10085: No se pudo obtener el secreto para verificar la firma del ID del cliente. Este error puede ocurrir por las siguientes razones:

  • Se ha especificado un ID de cliente incorrecto en "iss"
  • Por confianza directa, se ha especificado un valor de "kid" (ID secreto) incorrecto
  • Para la confianza OAuth 2.0 , no se pueden obtener claves de JWKSource

401002: error de acceso no autorizado

Si encuentra el error 401002 y ha confirmado que tiene los permisos adecuados para realizar la solicitud, asegúrese de que el alcance incluido en el JWT sea correcto y coincida con la solicitud que está intentando realizar. Para obtener una lista de puntos finales y alcances admitidos, consulte la sección anterior Métodos de la API de REST que admiten la autorización JWT.