Aide de Tableau Server sur Windows

Depuis Tableau Server version 2022.3 , à l’aide des applications connectées à Tableau, vous pouvez appeler par programmation l’API REST Tableau et y accéder via votre application personnalisée pour le compte des utilisateurs 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 jeton JWT doit contenir des portées 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 :

• Améliorer la sécurité : l’utilisation d’un 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 du porteur permet une emprunt d’identité simplifié avec une seule 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é

Portées pour les actions

Les applications connectées utilisent des portées qui accordent l’accès au contenu ou aux actions administratives via les Méthodes d’API REST prenant en charge l’autorisation JWT (ci-dessous). Une portée 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 (par exemple update).

Les actions qu’une portée peut effectuer incluent :

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

Par exemple, une portée 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) se présente comme suit :

tableau:datasources:update

Types de portée

Le type de portée que vous utilisez dépend du contenu ou de l’action administrative que vous souhaitez activer. Les portées appartiennent généralement à l’un des types suivants : contenu lu, individuel, générique et inter-catégorie.

• Portée de lecture de contenu : la portée de lecture du contenu, tableau:content:read, active les méthodes GET prises en charge pour le contenu Tableau. Lorsque vous utilisez cette portée, vous activez des actions dans les catégories d’API REST. Plus précisément, en utilisant cette portée, vous activez les méthodes GET pour les sources de données, les métriques, les vues, les classeurs, les projets et les sites. Depuis Tableau Server2023.3, vous spécifiez également cette portée dans un JWT qui servira à créer un jeton d’informations d’identification à utiliser avec l’API Metadata(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 portées individuelles.

• Portées individuelles : pour activer le contenu et les actions administratives pris en charge, vous pouvez utiliser leurs portées individuelles. Une portée individuelle est généralement associée à une méthode unique et à une 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’action individuelletableau:datasources:create ou la portée tableau:datasources:update, respectivement.
  • Pour les actions administratives telles que l’ajout ou la suppression d’utilisateurs, vous pouvez utiliser l’individutableau:users:create ou la portée tableau:users:delete, respectivement.

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

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

  Exemples :

  • Vous pouvez utiliser la portée avec caractère générique tableau:projects:* pour activer les actions créer, supprimer et mettre à jour dans la catégorie API REST des projets.
  • Vous pouvez utiliser la portée avec caractère générique tableau:users:* pour activer les actions obtenir/répertorier, ajouter, supprimer et mettre à jour dans la catégorie API REST des utilisateurs.
  • Vous pouvez utiliser la portée avec caractère générique tableau:tasks:* pour activer les actions obtenir/répertorier, ajouter, supprimer, mettre à jour et exécuter dans la catégorie API REST d’extraits et d’abonnements. De plus, cette portée permet de mettre à jour la source de données (s’il s’agit d’un extrait) et de mettre à jour le classeur.

• Portées inter-catégories : en plus de la portée de lecture du contenu, il existe quelques portées supplémentaires qui, si elles sont utilisées, activent les actions prises en charge dans différentes catégories d’API REST.

  Exemples :

  • Si vous utilisez la portée 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 la portée tableau:views:download, vous activez les actions dans les catégories d’API REST des données et des classeurs de la vue.
  • Si vous utilisez des portées 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 méthode d’autorisation d’accès à l’API REST

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

1. Créer une application connectée à l’aide de l’une des méthodes suivantes :
   • Configurer les applications connectées avec l’approbation directe
   • Configurer les applications connectées avec la confiance OAuth 2.0
2. Générer un jeton JWT valide : lors de l’exécution, votre application personnalisée génère un JWT valide, configuré avec les portées que vous avez incluses
3. Émettre une demande de Connexion(Le lien s’ouvre dans une nouvelle fenêtre) : votre application personnalisée émettra une demande de connexion à l’aide du jeton 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’identifiant Tableau en tant que valeur d’en-tête X-Tableau-Auth(Le lien s’ouvre dans une nouvelle fenêtre) 2) l’ID de site (LUID) dans l’URI de la demande

Exemple

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

Portées dans le jeton JWT

Pour autoriser avec succès l’accès à l’API REST, le jeton JWT doit également contenir les portées qui définissent les fonctionnalités d’API REST. Par exemple, pour activer diverses méthodes liées à la source de données, vous pouvez inclure les portées suivantes dans le jeton 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 doivent être transmises sous forme de type de liste.

URI de demande de connexion

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

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

Corps de la demande

Pour autoriser l’accès à l’API REST à l’aide d’un jeton 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 la réponse

La demande de connexion produit le corps de réponse suivant, qui inclut le jeton d’identifiant 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’identifiant Tableau à l’en-tête de toutes les demandes d’API REST ultérieures.

En-tête

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

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

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

Les portées 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 d’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 Tableau.
• Les méthodes Connexion(Le lien s’ouvre dans une nouvelle fenêtre) et Déconnexion(Le lien s’ouvre dans une nouvelle fenêtre) sont toutes deux prises en charge par l’autorisation JWT mais ne nécessitent pas l’utilisation de portées à compter de Tableau Server 2023.3.
• 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 l’approbation directe
  • Configurer les applications connectées avec la confiance OAuth 2.0

Portées avec caractère générique (*)

Les portées avec 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. Il peut s’agir des événements suivants :

Portées inter-catégories

Les portées intercatégories permettent plusieurs actions prises en charge dans plusieurs catégories d’API REST, et notamment :

Portées individuelles

Résoudre les problèmes de portée

401001 - erreur de connexion

Si vous rencontrez l’erreur 401001, le corps de la réponse de 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 jeton 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 qu’un paramètre « sub » (nom d’utilisateur) incorrect a été spécifié

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

  • le jeton JWT n’est pas valide ou il y a eu un problème inattendu
  • Un paramètre « aud » (audience) incorrect a été spécifié
  • Pour la confiance directe, un problème est survenu 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 spécifié dans « iss »
  • Pour la confiance directe, un « kid » (ID secret) incorrect a été spécifié
  • Pour EAS, impossible de récupérer les clés depuis JWKSource

401002 - erreur d’accès non autorisé

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