Toegangsbereiken voor verbonden apps

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 de methode Databron bijwerken(Link wordt in een nieuw venster geopend) kan aanroepen, ziet er bijvoorbeeld 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). Vanaf Tableau Cloud februari 2025 geeft u deze scope ook op in een JWT dat wordt gebruikt om een referentietoken te maken voor gebruik met de VizQL Data Service(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:

Verbonden app maken met een van de volgende methoden:
- Verbonden apps configureren met directe vertrouwensrelatie
- Verbonden apps configureren met OAuth 2.0-vertrouwensrelatie
Geldige JWT genereren— tijdens runtime genereert uw aangepaste toepassing een geldige JWT, geconfigureerd met de scopes die u hebt opgenomen
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
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"

"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-referentietoken is gegenereerd, voegt u deze toe aan de koptekst van alle volgende REST API-aanvragen.

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

Scopes voor verbonden apps verlenen uw aangepaste toepassing toegang tot de Tableau REST API-mogelijkheden namens gebruikers.

De vereiste scope voor een JWT-ondersteunde methode vindt u in het eigenschappenblok ervan in de Help voor de Tableau REST API(Link wordt in een nieuw venster geopend). Als een scope niet is opgenomen in het eigenschappenblok van de methode, kan toegang tot die methode niet worden beheerd door een JWT.

Een bereik waarmee u de methode Query uitvoeren op sites(Link wordt in een nieuw venster geopend) in de Tableau REST API kunt aanroepen is bijvoorbeeld tableau:sites:read

Opmerkingen:

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

Over jokerteken (*)-scopes

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

Voorbeelden

Scope	Ingeschakelde methoden
`tableau:datasources:*`	Hiermee kunnen databronmethoden worden gemaakt en bijgewerkt en kan de verbinding worden bijgewerkt.
`tableau:metrics:*`	Hiermee kan een query worden uitgevoerd op acties voor statistieken, en kunnen deze acties worden bijgewerkt en verwijderd.
`tableau:workbooks:*`	Hiermee kunnen acties voor afbeeldingswerkmappen worden gepubliceerd, bijgewerkt, gedownload en vooraf worden bekeken.
`tableau:groups:*`	Hiermee kunnen groepsacties worden gemaakt, bijgewerkt en verwijderd en kan er een query op worden uitgevoerd.
`tableau:projects:*`	Hiermee kunnen projectmethoden worden gemaakt, verwijderd en bijgewerkt.
`tableau:users:*`	Hiermee kunnen gebruikersmethoden worden opgehaald/in een lijst weergegeven, toegevoegd, verwijderd en bijgewerkt.
`tableau:tasks:` Opmerking:* deze scope is ook cross-category.	Hiermee kunnen methoden voor extracten en abonnementstaken worden opgehaald/in een lijst weergegeven, toegevoegd, bijgewerkt en uitgevoerd. Hiermee worden bijwerkingsmethoden voor databronnen voor werkmappen worden bijgewerkt.

Over cross-category scopes

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

Voorbeelden

Scope	Ingeschakelde methoden
`tableau:content:read`	Hiermee kunnen methoden voor Tableau-inhoud worden opgehaald/in een lijst weergegeven, waaronder databronnen, statistieken, weergaven, werkmappen, projecten en sites.
`tableau:tasks:run`	Hiermee kunnen methoden voor databronnen, werkmappen en extracten worden uitgevoerd.
`tableau:views:download`	Hiermee worden downloadmethoden ingeschakeld voor het bekijken van data en werkmappen.
`tableau:tasks:` Opmerking:* deze scope is ook een jokerteken.	Hiermee kunnen methoden voor extracten en abonnementstaken worden opgehaald/in een lijst weergegeven, toegevoegd, bijgewerkt en uitgevoerd. Hiermee worden bijwerkingsmethoden voor databronnen voor werkmappen worden bijgewerkt.

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.

Terug naar boven

Bedankt voor uw feedback.

De feedback is verzonden. Dank u wel.

Help bij Tableau Cloud