Aide de Tableau Server sur Windows

Depuis Tableau Server version 2022.3 , à l’aide des applications connectées à Tableau, vous pouvez appeler et accéder par programmation à l’API Tableau REST via votre application personnalisée au nom des utilisateurs de Tableau Server. L’accès à l’API REST est activé par un jeton Web JSON (JWT) défini dans le cadre de la demande de connexion initiale. Le JWT doit contenir des étendues qui définissent les méthodes d’API REST disponibles pour votre application personnalisée et ses utilisateurs via l’application connectée.

Autorisez l’accès à l’API REST à l’aide d’applications connectées pour :

• Renforcer la sécurité : l’utilisation d’un jeton JWT en tant que jeton porteur est intrinsèquement plus sécurisée que le stockage et la gestion des mots de passe des utilisateurs administrateurs via des fichiers .env dans des coffres-forts
• Améliorer l’efficacité : l’utilisation d’un jeton JWT en tant que jeton de support permet un emprunt d’identité simplifié avec une demande au point de terminaison de connexion au lieu de deux demandes
• Étendre et automatiser les intégrations Tableau complexes et les requêtes backend, telles que la récupération de contenu dynamique et le filtrage avancé

Actions d’une étendue

Les applications connectées utilisent des étendues qui accordent l’accès au contenu ou aux actions administratives grâce aux Méthodes d’API REST prenant en charge l’autorisation JWT (ci-dessous). Une étendue est une chaîne séparée par deux-points qui commence par l’espace de noms tableau, suivi de la ressource Tableau à laquelle l’accès est accordé, par exemple datasources, et se termine par l’action autorisée sur la ressource, telle que update .

L’action qu’une étendue peut effectuer inclut :

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

Par exemple, une étendue qui permet à votre application personnalisée d’appeler la méthode Mettre à jour la source de données(Le lien s’ouvre dans une nouvelle fenêtre) ressemble à :

tableau:datasources:update

Types d’étendues

Le type d’étendue que vous utilisez dépend du contenu ou de l’action administrative que vous souhaitez activer. Les étendues appartiennent généralement à l’un des types suivants : lecture de contenu, étendue individuelle, caractère générique et catégories multiples.

• Étendue de lecture de contenu : l’étendue de lecture de contenu, tableau:content:read , active les méthodes GET prises en charge pour le contenu Tableau. Lorsque vous utilisez cette étendue, vous activez des actions dans des catégories d’API REST multiples. Plus précisément, l’utilisation de cette étendue vous permet d’activer les méthodes GET pour les sources de données, les métriques, les vues, les classeurs, les projets et les sites. À partir Tableau Server 2023.3, vous spécifiez également cette étendue dans un JWT qui sera utilisé pour créer un jeton d’informations d’identification à utiliser avec l’API de métadonnées(Le lien s’ouvre dans une nouvelle fenêtre).

  Remarque : pour activer les méthodes GET pour les actions administratives, telles que les utilisateurs et les groupes, vous pouvez utiliser leurs étendues individuelles.

• Étendues individuelles : Pour activer le contenu et les actions administratives pris en charge, vous pouvez utiliser leurs étendues individuelles. Une étendue individuelle est généralement associée à une seule méthode et une seule catégorie d’API REST.

  Exemples :

  • Pour activer la publication ou la mise à jour d’une action de source de données, vous pouvez utiliser l’étendue individuelle tableau:datasources:create ou tableau:datasources:update, respectivement.
  • Pour les actions administratives telles que l’ajout ou la suppression d’utilisateurs, vous pouvez utiliser l’étendue individuelle tableau:users:create ou tableau:users:delete, respectivement.

  Remarque : certaines étendues individuelles peuvent activer des actions dans des catégories d’API REST multiples. Par exemple, tableau:views:download active les actions dans les catégories d’API REST des données de la vue et des classeurs.

• Étendues à caractère générique : pour certaines étendues, vous pouvez remplacer l’action par le caractère générique (*) pour activer les actions prises en charge dans une catégorie d’API REST spécifique.

  Exemples :

  • Vous pouvez utiliser l’étendue à caractère générique tableau:projects:* pour activer les actions de création, de suppression et de mise à jour dans la catégorie d’API REST des projets.
  • Vous pouvez utiliser l’étendue à caractère générique tableau:users:* pour activer les actions d’obtention/énumération, d’ajout, de suppression et de mise à jour dans la catégorie d’API REST des utilisateurs.
  • Vous pouvez utiliser l’étendue à caractère générique tableau:tasks:* pour activer les actions d’obtention/énumération, d’ajout, de suppression, de mise à jour et d’exécution dans les catégories d’API REST des extraits et des abonnements. Cette étendue permet également de mettre à jour la source de données (s’il s’agit d’un extrait) et de mettre à jour le classeur.

• Étendues à catégories multiples : en plus de l’étendue de lecture de contenu, il existe quelques étendues supplémentaires qui, si elles sont utilisées, activent les actions prises en charge dans des catégories d’API REST multiples.

  Exemples :

  • Si vous utilisez l’étendue tableau:tasks:run, vous activez les actions dans les catégories d’API REST des sources de données et des classeurs.
  • Encore une fois, si vous utilisez l’étendue tableau:views:download, vous activez les actions dans les catégories d’API REST des données de la vue et des classeurs.
  • Si vous utilisez des étendues d’autorisations telles que tableau:permissions:update ou tableau:permissions:delete, vous activez les actions dans les catégories d’API REST des sources de données, des classeurs et des projets.

Résumé de la façon d’autoriser l’accès à l’API REST

La liste suivante résume les étapes pour demander l’accès à l’API REST via un JWT :

1. Créez une application connectée à l’aide de l’une des méthodes suivantes :
   • Configurer les applications connectées avec Direct Trust
   • Configurer les applications connectées à l’aide de la confiance Oauth 2.0
2. Générer un JWT valide : au moment de l’exécution, votre application personnalisée génère un JWT valide, configuré avec les étendues que vous avez incluses
3. Faire une demande Connexion(Le lien s’ouvre dans une nouvelle fenêtre) : votre application personnalisée effectue une demande de connexion à l’aide du JWT pour renvoyer un jeton d’accès Tableau et un ID de site (LUID)
4. Utiliser le jeton d’accès Tableau dans les demandes suivantes : dans les appels d’API REST suivants, utilisez 1) le jeton d’accès Tableau comme la valeur d’en-tête X-Tableau-Auth(Le lien s’ouvre dans une nouvelle fenêtre) et 2) l’ID de site (LUID) dans l’URI de la demande

Exemple

Par exemple, supposons que vous créez une application connectée à l’aide de Direct Trust. À l’aide de Direct Trust, votre application personnalisée qui appelle l’API REST génère un JWT valide à l’aide de l’ID client et du secret client générés par l’application connectée.

Étendues dans le JWT

Pour autoriser avec succès l’accès à l’API REST, le JWT doit également contenir les étendues qui définissent les capacités de l’API REST. Par exemple, pour activer diverses méthodes liées à la source de données, vous pouvez inclure les étendues suivantes dans le JWT :

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

Ou

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

Remarque : les valeurs d’étendue doivent être transmises sous forme de type de liste.

URI de demande de connexion

Pour effectuer un appel à l’API REST, votre application personnalisée doit d’abord effectuer une demande de connexion pour générer un jeton d’identifiants Tableau.

POST https://myco/api/3.17/auth/signin

Corps de la requête

Pour autoriser l’accès à l’API REST à l’aide d’un JWT, le corps de la demande de connexion doit contenir le JWT valide, comme dans l’exemple ci-dessous.

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

Corps de réponse

La demande de connexion produit le corps de réponse suivant, qui inclut le jeton d’identification de Tableau.

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

Une fois le jeton d’accès Tableau généré, ajoutez le jeton d’identification de Tableau à l’en-tête de toutes les demandes d’API REST ultérieures.

En-tête

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

Toutes les demandes d’API REST ultérieures utilisant le jeton d’accès Tableau sont alors limitées par les étendues du JWT.

Méthodes d’API REST prenant en charge l’autorisation JWT

Les étendues suivantes peuvent être associées à l’application connectée pour définir l’accès et les méthodes que votre application personnalisée peut avoir à l’API REST(Le lien s’ouvre dans une nouvelle fenêtre) au nom des utilisateurs.

Remarques :

• pour les autres fonctionnalités de l’API REST non répertoriées dans le tableau ci-dessous, vous pouvez utiliser d’autres mécanismes d’autorisation pour accéder aux méthodes. Pour plus d’informations, consultez Méthodes d’authentification(Le lien s’ouvre dans une nouvelle fenêtre) dans l’aide de l’API REST de Tableau.
• Les méthodes Se connecter(Le lien s’ouvre dans une nouvelle fenêtre) et Se déconnecter(Le lien s’ouvre dans une nouvelle fenêtre) sont toutes deux prises en charge par l’autorisation JWT, mais à partir de Tableau Server 2023.3 leur utilisation ne nécessite pas d’étendue.
• Pour les champs d’application pris en charge par l’API d’intégration v3, consultez l’un des éléments suivants :
  • Configurer les applications connectées avec Direct Trust
  • Configurer les applications connectées à l’aide de la confiance Oauth 2.0

Étendues à caractère générique (*)

Les étendues à caractère générique utilisent le caractère générique (*) au lieu d’une action spécifique, pour activer plusieurs actions prises en charge dans une catégorie d’API REST spécifique. Ceux-ci inclus :

Étendues à catégories multiples

Les étendues à catégories multiples activent les multiples actions prises en charge dans différentes catégories d’API REST. Ceux-ci inclus :

Étendues individuelles

Dépanner les étendues

401001 - erreur de connexion

Si vous rencontrez l’erreur 401001, le corps de la réponse Connexion est ajouté avec l’un des codes d’erreur supplémentaires spécifiques aux applications connectées suivants : 16, 10084 ou 10085.

Par exemple, dans le corps de la réponse suivante, « 10084 » est le code d’erreur des applications connectées que vous pouvez utiliser pour résoudre les problèmes de connexion à Tableau Server à l’aide d’un JWT pour l’autorisation de l’API REST.

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

Pour vous aider à résoudre le problème, reportez-vous à la description du code d’erreur applicable et à ses causes potentielles.

• 16 : Impossible de trouver l’utilisateur — cette erreur peut se produire parce que le « sub » (nom d’utilisateur) a été spécifié

• 10084 : Impossible d’analyser le jeton d’accès — cette erreur peut se produire pour les raisons suivantes :

  • JWT n’est pas valide ou il y a eu un problème inattendu
  • « aud » (audience) incorrect spécifié
  • Pour la confiance directe, il y a eu un problème avec la signature du secret

• 10085 : Impossible d’extraire le secret pour vérifier la signature de l’ID client — cette erreur peut se produire pour les raisons suivantes :

  • ID client incorrect dans « iss » spécifié
  • Pour la confiance directe, « kid »(ID secret) incorrect spécifié
  • Pour EAS, impossible de récupérer les clés de JWKSource

401002 - erreur d’accès non autorisé

Si vous rencontrez l’erreur 401002 et avez confirmé que vous disposez des autorisations appropriées pour effectuer la demande, assurez-vous que la portée incluse dans le JWT est correcte et correspond à la demande que vous essayez de faire. Pour obtenir la liste des points de terminaison et des étendues prises en charge, consultez la section Méthodes d’API REST prenant en charge l’autorisation JWT ci-dessus.