Tableau Cloud-hjälp

Från och med juni 2022 kan du, med hjälp av Tableau-anslutna program, programmatiskt anropa och öppna Tableau REST API via ett anpassat program för Tableau Cloud-användarnas räkning. Åtkomst till REST API möjliggörs av en JSON-webbtoken (JWT) som definieras som en del av den första inloggningsbegäran. JWT måste innehålla omfång som definierar REST API-metoderna som är tillgängliga för ditt anpassade program och dess användare via det anslutna programmet.

Auktorisera åtkomst till REST API med anslutna program för att:

• Förbättra effektiviteten – att använda JWT som bärartoken möjliggör en förenklad impersonering med en förfrågan till inloggningsslutpunkten istället för två förfrågningar
• Utöka och automatisera komplexa Tableau-integrationer och backend-frågor – som dynamisk innehållshämtning och avancerad filtrering

Åtgärdernas omfattning

Anslutna program använder omfattningar som erbjuder åtkomst till innehåll eller administrativa åtgärder genom REST API-metoder som stöder JWT-auktorisering (nedan). Ett omfång är en kolonseparerad sträng som börjar med namnområdet tableau, följt av Tableau-resursen som åtkomst ges till, som t.ex. datasources, och slutar med den åtgärd som är tillåten på resursen, som t.ex. update.

De åtgärder som en omfattning kan vidta inkluderar:

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

Till exempel ser ett omfång som gör att ditt anpassade program kan anropa metoden Uppdatera datakälla(Länken öppnas i ett nytt fönster) ut så här:

tableau:datasources:update

Omfångstyper

Vilken typ av omfattning som används beror på innehållet eller den administrativa åtgärden som ska aktiveras. Omfattningar delas i allmänhet in i en av följande typer: läst innehåll, individuellt, jokertecken och övergripande kategorier.

• Omfattningen läst innehåll: Omfattningen läst innehåll ,tableau:content:read , aktiverar GET-metoder som stöds för Tableau-innehåll. När den här omfattningen använda aktiveras åtgärder över olika REST API-kategorier. Den här omfattningen aktiverar närmare bestämt GET-metoder för datakällor, mätvärden, vyer, arbetsböcker, projekt och platser. Från och med Tableau Cloud oktober 2023 anger du även den här omfattningen i en JSON-webbtoken som sedan används för att skapa en token med inloggningsuppgifter som används med metadata-API:et(Länken öppnas i ett nytt fönster).

  Obs! För att aktivera GET-metoder för administrativa åtgärder, som användare och grupper, kan du använda individuella omfattningar.

• Individuella omfattningar: Om du vill aktivera innehåll och administrativa åtgärder som stöds kan du använda individuella omfattningar. En individuell omfattning är vanligtvis associerad med en enda metod och REST API-kategori.

  Exempel:

  • Om du vill aktivera åtgärden att publicera eller uppdatera en datakälla kan du använda den individuella omfattningen tableau:datasources:create eller tableau:datasources:update.
  • För administrativa åtgärder såsom att lägga till eller ta bort användare kan du använda den individuella omfattningen tableau:users:create ellertableau:users:delete, respektive.

  Obs! Det finns vissa individuella omfattningar som kan aktivera åtgärder över olika REST API-kategorier. Till exempel aktiverar tableau:views:download åtgärder i REST API-kategorierna för vydata och arbetsböcker.

• Omfattningar med jokertecken (*): För vissa omfattningar kan du ersätta åtgärden med ett jokertecken (*) för att aktivera åtgärder som stöds inom en specifik REST API-kategori.

  Exempel:

  • Du kan använda jokerteckenomfattningen tableau:projects:* för att aktivera åtgärderna skapa, ta bort och uppdatera i REST API-kategorin för projekt.
  • Du kan använda jokerteckenomfattningen tableau:users:* för att aktivera åtgärderna hämta/lista, lägg till, ta bort och uppdatera i REST API-kategorin för användare.
  • Du kan använda jokerteckenomfattningen tableau:tasks:* för att aktivera åtgärderna hämta/lista, lägg till, ta bort, uppdatera och kör för REST API-kategorierna för extrakt och prenumerationer. Dessutom kan du använda den här omfattningen för att uppdatera en datakälla (om den är ett extrakt) och för att uppdatera en arbetsbok.

• Omfattningar över flera kategorier: Utöver omfattningen läst innehåll finns det några ytterligare omfattningar som, om de används, aktiverar åtgärder som stöds över olika REST API-kategorier.

  Exempel:

  • Om omfattningen tableau:tasks:run används aktiverar du åtgärder i REST API-kategorierna för datakällor och arbetsböcker.
  • Om omfattningen tableau:views:download används aktiverar du åtgärder i REST API-kategorierna för vydata och arbetsböcker.
  • Om omfattningar med behörighet används såsom tableau:permissions:update eller tableau:permissions:delete aktiveras åtgärder i REST API för kategorierna datakällor, arbetsböcker och projekt.

Sammanfattning av hur du auktoriserar REST API-åtkomst

I följande lista sammanfattas stegen för att begära åtkomst till REST API via en JWT:

1. Skapa ett anslutet program med någon av följande metoder:
   • Konfigurera anslutna program med direkt förtroende (direkt betrodd)
   • Konfigurera anslutna program med OAuth 2.0-förtroende
2. Generera en giltig JWT – vid körning kommer ditt anpassade program att generera en giltig JWT, konfigurerad med de omfång du har inkluderat
3. Gör en inloggningsbegäran(Länken öppnas i ett nytt fönster) – ditt anpassade program gör en inloggningsbegäran med JSON-webbtoken för att returnera en Tableau-token med inloggningsuppgifter och ett plats-ID (LUID)
4. Använd Tableau-åtkomsttoken i efterföljande förfrågningar – i efterföljande REST API-anrop använder du 1) Tableau-token med inloggningsuppgifter som X-Tableau-Auth(Länken öppnas i ett nytt fönster)-rubrikvärdet och 2) plats-ID (LUID) i förfrågans-URI

Exempel

Anta till exempel att du skapar ett anslutet program med hjälp av direkt förtroende (direkt betrodd). Med hjälp av direkt förtroende genererar det anpassade program som anropar REST API en giltig JWT med det klient-ID och den klienthemlighet som genereras av det anslutna programmet.

Omfång i JWT

För att lyckas auktorisera åtkomst till REST API måste JWT också innehålla de omfång som definierar REST API-funktionerna. Till exempel, för att aktivera olika datakällsrelaterade metoder kan du inkludera följande omfång i JWT:

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

Eller

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

Obs! Omfångsvärdena måste skickas som en listtyp.

URI för inloggningsbegäran

För att göra ett anrop till REST API måste ditt anpassade program först göra en inloggningsbegäran för att generera en Tableau-token för inloggningsuppgifterna.

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

Förfråganstext

För att auktorisera REST API-åtkomst med en JSON-webbtoken måste inloggningsbegäran innehålla den giltiga JSON-webbtoken, som i exemplet nedan.

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

Svarstext

Inloggningsbegäran producerar följande svarstext, som inkluderar Tableau-token med inloggningsuppgifter.

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

När Tableau-åtkomsttoken har genererats ska du lägga till Tableau-token med inloggningsuppgifter i rubriken för alla efterföljande REST API-förfrågningar.

Rubrik

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

Alla efterföljande REST API-förfrågningar som använder Tableau-åtkomsttoken begränsas sedan av omfång i JWT.

REST API-metoder som stöder JWT-auktorisering

Följande omfång kan kopplas till det anslutna programmet för att definiera åtkomst och metoder som det anpassade programmet kan ha till REST API(Länken öppnas i ett nytt fönster) för användarnas räkning.

Obs!

• För andra REST API-funktioner som inte är listade i tabellen nedan kan du använda andra auktoriseringsmekanismer för att komma åt metoderna. Mer information finns i Autentiseringsmetoder(Länken öppnas i ett nytt fönster) i Tableau REST API-hjälpen.
• Både Logga in(Länken öppnas i ett nytt fönster) och Logga ut(Länken öppnas i ett nytt fönster) stöds av JWT-auktorisering men behöver inte inkluderas för att kunna användas från och med juni 2023 (Tableau 2023.2).
• För omfattningar som stöds av inbäddnings-API v3 läser du något av följande avsnitt:
  • Konfigurera anslutna program med direkt förtroende (direkt betrodd)
  • Konfigurera anslutna program med OAuth 2.0-förtroende

Jokerteckenomfattningar (*)

Omfattningar med jokertecken använder jokertecken (*) i stället för en specifik åtgärd för att aktivera flera åtgärder som stöds inom en specifik REST API-kategori. Dessa omfattar:

Kategoriövergripande omfattningar

Kategoriövergripande omfattningar aktiverar stöd för att utföra flera åtgärder inom flera REST API-kategorier. Dessa omfattar:

Individuella omfattningar

Felsök omfång

401001 – inloggningsfel

Om du stöter på fel 401001 läggs inloggningssvaret till, med en av följande extra felkoder som är specifika för det anslutna programmet: 16, 10084 eller 10085.

I följande svarstext är till exempel ”10084” felkoden för anslutna program som du kan använda för att felsöka problem med att logga in på Tableau Cloud med en JWT för REST API-auktorisering.

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

Se beskrivningen av tillämplig felkod och dess potentiella orsaker för hjälp med att lösa problemet.

• 16: Kunde inte hitta användaren – det här felet kan uppstå då den felaktiga ”sub” (användarnamn) indikerades

• 10084: Det gick inte att analysera åtkomsttoken – det här felet kan uppstå av följande anledningar:

  • JWT är ogiltigt eller ett oväntat problem uppstod
  • Felaktig ”aud” (publik) indikerades
  • För direkt förtroende var det problem med att signera hemligheten

• 10085: Det gick inte att hämta hemligheten för att verifiera signaturen för klient-ID – det här felet kan uppstå av följande anledningar:

  • Felaktigt klient-ID i ”iss” indikerades
  • För direkt förtroende indikerades felaktigt ”kid” (hemlighets-ID)
  • Det går inte att hämta nycklar från JWKSource för OAuth 2.0 trust

401002 – fel vid obehörig åtkomst

Om fel 401002 uppstår och du har bekräftat att du har rätt behörighet att göra begäran ska du se till att omfattningen som ingår i JWT är korrekt och matchar den begäran som görs. Se avsnittet REST API-metoder som stöder JWT-auktorisering ovan för en lista över slutpunkter och omfattningar som stöds.