Help bij Tableau Cloud

Vanaf juni 2022 kunt u met behulp van met Tableau verbonden apps de Tableau REST API via uw aangepaste toepassing programmatisch aanroepen en openen namens Tableau Cloud-gebruikers. Toegang tot de REST API wordt mogelijk gemaakt door een JSON Web Token (JWT) die is gedefinieerd als onderdeel van de initiële aanmeldingsaanvraag. De JWT moet scopes bevatten die de REST API-methoden definiëren die via de verbonden app beschikbaar zijn voor uw aangepaste toepassing en de gebruikers.

Autoriseer toegang tot de REST API met behulp van verbonden apps om het volgende te doen:

• Efficiëntie verbeteren: het gebruik van een JWT als dragertoken maakt een vereenvoudigde imitatie van identiteit mogelijk met één verzoek aan het aanmeldingseindpunt in plaats van twee verzoeken
• Complexe Tableau-integraties en back-endquery's uitbreiden en automatiseren, zoals het dynamisch ophalen van inhoud en geavanceerde filters

Acties van scopes

Verbonden apps gebruiken scopes die toegang verlenen tot inhoud of beheeracties via de REST API-methoden die JWT-autorisatie ondersteunen (zie onder). Een scope is een door dubbele punten gescheiden tekenreeks die begint met de naamruimte tableau, gevolgd door de Tableau-resource waartoe toegang wordt verleend, zoals datasources, en eindigt met de actie die is toegestaan op de resource, zoals update.

De acties die een scope kan ondernemen zijn onder meer:

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

Een scope waarmee uw aangepaste toepassing bijvoorbeeld de methode Databron bijwerken(Link wordt in een nieuw venster geopend) kan aanroepen, ziet er als volgt uit:

tableau:datasources:update

Typen scopes

Het type scope dat u gebruikt, is afhankelijk van de inhoud of beheeractie die u wilt inschakelen. Scopes vallen over het algemeen onder een van de volgende typen: inhoud lezen, individueel, jokerteken en cross-category.

• Scope Inhoud lezen: Met de scope voor inhoud lezen, tableau:content:read, zijn ondersteunde GET-methoden voor Tableau-inhoud mogelijk. Wanneer u deze scope gebruikt, schakelt u acties in voor alle REST API-categorieën. Met deze scope schakelt u met name GET-methoden in voor databronnen, statistieken, weergaven, werkmappen, projecten en sites. Vanaf Tableau Cloud oktober 2023 geeft u deze scope ook op in een JWT die wordt gebruikt om een referentietoken te maken voor gebruik met de Metadata-API(Link wordt in een nieuw venster geopend).

  Opmerking: als u GET-methoden wilt inschakelen voor beheeracties, zoals gebruikers en groepen, kunt u hun individuele scopes gebruiken.

• Individuele scopes: als u ondersteunde inhoud en beheeracties wilt inschakelen, kunt u hun individuele scopes gebruiken. Een individuele scope is doorgaans gekoppeld aan één methode en REST API-categorie.

  Voorbeelden:

  • Als u het publiceren of bijwerken van een databronactie mogelijk wilt maken, kunt u respectievelijk de individuele tableau:datasources:create of tableau:datasources:update-scope gebruiken.
  • Voor beheeracties zoals het toevoegen of verwijderen van gebruikers kunt respectievelijk de individuele tableau:users:create of tableau:users:delete-scope gebruiken.

  Opmerking: er zijn een paar individuele scopes die acties in REST API-categorieën kunnen inschakelen. Zo maakt tableau:views:download acties mogelijk in de REST API-categorieën voor weergavedata en werkmappen.

• Jokerteken (*)-scopes: voor bepaalde scopes kunt u de actie vervangen door het jokerteken (*) om ondersteunde acties binnen een specifieke REST API-categorie in te schakelen.

  Voorbeelden:

  • U kunt gebruikmaken van de tableau:projects:*-jokertekenscope om de acties voor maken, verwijderen en bijwerken in de REST API-projectcategorie in te schakelen.
  • U kunt gebruikmaken van de tableau:users:*-jokertekenscope om de acties voor ophalen/opsommen, toevoegen, verwijderen en bijwerken in de REST API-gebruikerscategorie in te schakelen.
  • U kunt gebruikmaken van de tableau:tasks:*-jokertekenscope om de acties voor ophalen/opsommen, toevoegen, verwijderen, bijwerken en uitvoeren in de REST API-categorieën voor extraheren en abonnementen in te schakelen. Bovendien maakt deze scope het bijwerken van de databron (indien een extract) en de werkmap mogelijk.

• Cross-category scopes: Naast de scope voor inhoud lezen zijn er nog een paar scopes die, indien gebruikt, ondersteunde acties in verschillende REST API-categorieën mogelijk maken.

  Voorbeelden:

  • Als u gebruikmaakt van de scope tableau:tasks:run, schakelt u acties in de REST API-categorieën van databronnen en werkmappen in.
  • Als u de scope tableau:views:download gebruikt, schakelt u acties in de REST API-categorieën voor weergavedata en werkmappen in.
  • Als u machtigingsscopes gebruikt zoals tableau:permissions:update of tableau:permissions:delete, schakelt u acties in de REST API-categorieën van databronnen, werkmappen en projecten in.

Samenvatting van de autorisatie van REST API-toegang

De volgende lijst is een overzicht van de stappen om toegang tot de REST API aan te vragen via een JWT:

1. Verbonden app maken met een van de volgende methoden:
   • Verbonden apps configureren met directe vertrouwensrelatie
   • Verbonden apps configureren met OAuth 2.0-vertrouwensrelatie
2. Geldige JWT genereren— tijdens runtime genereert uw aangepaste toepassing een geldige JWT, geconfigureerd met de scopes die u hebt opgenomen
3. Aanmeldings(Link wordt in een nieuw venster geopend)verzoek maken—uw aangepaste toepassing verzendt met behulp van de JWT een aanmeldingsverzoek om een Tableau-referentietoken en site-ID (LUID) te retourneren
4. Tableau-toegangstoken bij achtereenvolgende verzoeken gebruiken—gebruik bij achtereenvolgende REST API-aanroepen 1) de Tableau-referentietoken als de headerwaarde X-Tableau-Auth(Link wordt in een nieuw venster geopend) en 2) de site-ID (LUID) in de aanvraag-URI

Voorbeeld

Stel dat u een verbonden app maakt met behulp van een directe vertrouwensrelatie. Met een directe vertrouwensrelatie genereert uw aangepaste toepassing die de REST API aanroept, een geldige JWT met de client-ID en het clientgeheim die door de verbonden app zijn gegenereerd.

Scopes in de JWT

Om toegang tot de REST API succesvol te autoriseren moet de JWT ook de scopes bevatten die de REST API-mogelijkheden definiëren. Als u bijvoorbeeld verschillende databrongerelateerde methoden wilt inschakelen, kunt u de volgende scopes in de JWT opnemen:

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

of

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

Opmerking: scopewaarden moeten worden doorgegeven als lijsttype.

URI voor aanmeldingsverzoek

Om de REST API aan te roepen moet uw aangepaste toepassing eerst een aanmeldingsverzoek verzenden om een Tableau-referentietoken te genereren.

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

Hoofdtekst aanvragen

Om REST API-toegang met een JWT te autoriseren moet de hoofdtekst van het aanmeldingsverzoek de geldige JWT bevatten, zoals in het onderstaande voorbeeld.

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

Tekst van reactie

Het aanmeldingsverzoek levert de volgende hoofdtekst op, die de Tableau-referentietoken bevat.

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

Nadat de Tableau-toegangstoken is gegenereerd, voegt u de Tableau-referentietoken toe aan de header van alle volgende REST API-verzoeken.

Koptekst

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

Alle volgende REST API-verzoeken die gebruik maken van de Tableau-toegangstoken, worden vervolgens begrensd door de scopes in de JWT.

REST API-methoden die JWT-autorisatie ondersteunen

De volgende scopes kunnen aan de verbonden app worden gekoppeld om de toegang en methoden te definiëren die uw aangepaste toepassing namens gebruikers kan hebben ten aanzien van de REST-API(Link wordt in een nieuw venster geopend).

Opmerkingen:

• Voor andere REST API-mogelijkheden die niet in de onderstaande tabel staan, kunt u andere autorisatiemechanismen gebruiken om toegang tot de methoden te krijgen. Zie Verificatiemethoden(Link wordt in een nieuw venster geopend) in de Tableau REST API Help voor meer informatie.
• Zowel de methode Aanmelden(Link wordt in een nieuw venster geopend) als Afmelden(Link wordt in een nieuw venster geopend) worden door JWT-autorisatie ondersteund, maar vereisen vanaf juni 2023 (Tableau 2023.2) geen scope.
• Zie een van de volgende onderwerpen voor scopes die worden ondersteund door de Embedding API v3:
  • Verbonden apps configureren met directe vertrouwensrelatie
  • Verbonden apps configureren met OAuth 2.0-vertrouwensrelatie

Jokerteken (*)-scopes

Jokertekenscopes maken gebruik van het jokerteken (*) in plaats van een specifieke actie om meerdere ondersteunde acties binnen een specifieke REST API-categorie in te schakelen. Deze omvatten:

Cross-category scopes

Met cross-category scopes zijn meerdere ondersteunde acties mogelijk tussen meerdere REST API-categorieën. Deze omvatten:

Individuele scopes

Problemen met scopes oplossen

401001 - aanmeldingsfout

Als u fout 401001 tegenkomt, wordt de antwoordtekst van Aanmelden aangevuld met een van de volgende extra foutcodes die specifiek zijn voor verbonden apps: 16, 10084 of 10085.

In de volgende antwoordtekst is '10084' bijvoorbeeld een foutcode voor verbonden apps die u kunt gebruiken om problemen op te lossen met het aanmelden bij Tableau Cloud aan de hand van een JWT voor REST API-autorisatie.

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

Zie de beschrijving van de toepasselijke foutcode en de mogelijke oorzaken om het probleem op te lossen.

• 16: Kan de gebruiker niet vinden—deze fout kan optreden als een onjuiste sub (gebruikersnaam) is opgegeven

• 10084: Kan de toegangstoken niet parseren—deze fout kan om de volgende redenen optreden:

  • De JWT is ongeldig of er is een onverwacht probleem opgetreden
  • Incorrect aud (publiek) opgegeven
  • Bij een directe vertrouwensrelatie is er een probleem met het ondertekenen met het het geheim

• 10085: Kan het geheim niet ophalen om handtekening voor client-ID te verifiëren—deze fout kan om de volgende redenen optreden:

  • Incorrecte klant-ID in iss opgegeven
  • Bij een directe vertrouwensrelatie is er een incorrecte kid (geheim-ID) opgegeven
  • Bij OAuth 2.0-vertrouwensrelatie kunnen geen sleutels worden opgehaald uit de JWKSource

401002 - Fout: ongeautoriseerde toegang

Als u fout 401002 tegenkomt en hebt bevestigd dat u de juiste machtigingen hebt om het verzoek in te dienen, controleert u of de scope in de JWT correct is en overeenkomt met de aanvraag die u wilt doen. Zie de bovenstaand sectie REST API-methoden die JWT-autorisatie ondersteunen voor een lijst met eindpunten en ondersteunde scopes.