Guida di Tableau Cloud

da giugno 2022, utilizzando le app connesse di Tableau puoi chiamare a livello di codice e accedere all’API REST di Tableau tramite la tua applicazione personalizzata per conto degli utenti di Tableau Cloud. L’accesso all’API REST è abilitato da un token JWT (JSON Web Token), definito come parte della richiesta di accesso iniziale. Il token JWT deve contenere ambiti che definiscono i metodi dell’API REST disponibili per l’applicazione personalizzata e i relativi utenti tramite l’app connessa.

Autorizza l’accesso all’API REST utilizzando le app connesse per:

• Migliorare l’efficienza. L’utilizzo di un JWT come token di trasporto consente una rappresentazione semplificata, con una richiesta all’endpoint di accesso invece di due.
• Estendere e automatizzare le complesse integrazioni di Tableau e le query back-end, come il recupero dinamico dei contenuti e il filtro avanzato.

Azioni di ambito

Le app connesse utilizzano ambiti che concedono l’accesso al contenuto o alle azioni amministrative tramite i Metodi API REST che supportano l’autorizzazione JWT (di seguito). Un ambito è una stringa separata da due punti che inizia con lo spazio dei nomi tableau, seguito dalla risorsa di Tableau a cui viene concesso l’accesso, ad esempio datasources, e termina con l’azione consentita sulla risorsa, ad esempio update.

Le azioni che un ambito può eseguire includono:

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

Ad esempio, un ambito che consente all’applicazione personalizzata di chiamare il metodo Aggiorna origine dati(Il collegamento viene aperto in una nuova finestra) è simile al seguente:

tableau:datasources:update

Tipi di ambito

Il tipo di ambito utilizzato dipende dal contenuto o dall’azione amministrativa che si desidera abilitare. Gli ambiti generalmente rientrano in uno dei seguenti tipi: lettura del contenuto, individuale, carattere jolly e cross-category.

• Ambito di lettura del contenuto: l’ambito di lettura del contenuto, tableau:content:read , abilita i metodi GET supportati per i contenuti di Tableau. Quando si utilizza questo ambito, si abilitano le azioni tra le categorie dell’API REST. In particolare, utilizzando questo ambito si abilitano i metodi GET per origini dati, metriche, viste, cartelle di lavoro, progetti e siti. A partire da Tableau Cloud di ottobre 2023, devi specificare questo ambito anche in un token Web JSON che verrà utilizzato per creare un token di credenziali da utilizzare con l’API dei metadati(Il collegamento viene aperto in una nuova finestra).

  Nota: per abilitare i metodi GET per azioni amministrative, come utenti e gruppi, puoi utilizzare i loro ambiti individuali.

• Ambiti individuali: per abilitare il contenuto supportato e le azioni amministrative, puoi utilizzare i loro ambiti individuali. Un singolo ambito è generalmente associato a un singolo metodo e a una singola categoria dell’API REST.

  Esempi:

  • Per abilitare la pubblicazione o l’aggiornamento di un’azione dell’origine dati, puoi utilizzare l’ambito individuale tableau:datasources:create o tableau:datasources:update, rispettivamente.
  • Per azioni amministrative come aggiungere o rimuovere utenti, puoi utilizzare l’ambito individuale tableau:users:create o tableau:users:delete, rispettivamente.

  Nota: esistono alcuni ambiti individuali che possono abilitare azioni tra le categorie di API REST. Ad esempio, tableau:views:download abilita le azioni nelle categorie Dati vista e Cartelle di lavoro dell’API REST.

• Ambiti con caratteri jolly: per determinati (*) ambiti, è possibile sostituire l’azione con il carattere jolly (*) per abilitare le azioni supportate all’interno di una specifica categoria dell’API REST.

  Esempi:

  • Puoi usare l’ambito con caratteri jolly tableau:projects:* per abilitare le azioni di creazione, eliminazione e aggiornamento nella categoria dell’API REST per i progetti.
  • Puoi usare l’ambito con caratteri jolly tableau:users:* per abilitare le azioni di recupero/elenco, aggiunta, eliminazione e aggiornamento nella categoria dell’API REST per gli utenti.
  • Puoi usare l’ambito con caratteri jolly tableau:tasks:* per abilitare le azioni di recupero/elenco, aggiunta, eliminazione, aggiornamento ed esecuzione nelle categorie dell’API REST per le estrazioni e le sottoscrizioni. Inoltre, questo ambito consente l’aggiornamento dell’origine dati (se si tratta di un’estrazione) e l’aggiornamento della cartella di lavoro.

• Ambiti cross-category: oltre all’ambito di lettura del contenuto, esistono alcuni ambiti aggiuntivi che, se usati, abilitano azioni supportate in diverse categorie dell’API REST.

  Esempi:

  • Se si utilizza l’ambito tableau:tasks:run, si abilitano le azioni nelle categorie origini dati e cartelle di lavoro dell’API REST.
  • Ancora una volta, se si utilizza l’ambito tableau:views:download, si abilitano le azioni nelle categorie Dati vista e Cartella di lavoro dell’API REST.
  • Se si utilizzano ambiti di autorizzazione come tableau:permissions:update o tableau:permissions:delete, si abilitano le azioni nelle categorie origini dati, cartelle di lavoro e progetti dell’API REST.

Riepilogo delle fasi per autorizzare l’accesso all’API REST

Nell’elenco seguente sono riepilogate le fasi per richiedere l’accesso all’API REST tramite un token JWT:

1. Crea un’app connessa utilizzando uno dei seguenti metodi:
   • Configurare le app connesse con un trust diretto
   • Configurare le app connesse con Trust OAuth 2.0
2. Genera un token JWT valido: in fase di esecuzione la tua applicazione personalizzata genererà un token JWT valido, configurato con gli ambiti che hai incluso
3. Effettua una richiesta di accesso(Il collegamento viene aperto in una nuova finestra): la tua applicazione personalizzata eseguirà una richiesta di accesso utilizzando il token JWT per restituire un token di credenziali Tableau e un ID del sito (LUID)
4. Utilizza il token di accesso di Tableau nelle richieste successive: nelle successive chiamate all’API REST, utilizza 1) il token di credenziali Tableau come valore dell’intestazione X-Tableau-Auth(Il collegamento viene aperto in una nuova finestra) e 2) l’ID del sito (LUID) nell’URI della richiesta

Esempio

Supponi ad esempio di creare un’app connessa utilizzando un trust diretto. Utilizzando un trust diretto, l’applicazione personalizzata che chiama l’API REST genera un token JWT valido utilizzando l’ID client e il segreto client generati dall’app connessa.

Ambiti nel token JWT

Per autorizzare correttamente l’accesso all’API REST, il token JWT deve contenere anche gli ambiti che definiscono le funzionalità dell’API REST. Ad esempio, per abilitare vari metodi relativi all’origine dati, potresti includere i seguenti ambiti nel token JWT:

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

Oppure

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

Nota: i valori degli ambiti devono essere passati come tipo di elenco.

URI della richiesta di accesso

Per effettuare una chiamata all’API REST, l’applicazione personalizzata deve prima effettuare una richiesta di accesso per generare un token per le credenziali di Tableau.

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

Corpo della richiesta

Per autorizzare l’accesso all’API REST utilizzando un token JWT, il corpo della richiesta di accesso deve contenere il token JWT valido come nell’esempio seguente.

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

Corpo della risposta

La richiesta di accesso produce il seguente corpo della risposta, che include il token di credenziali Tableau.

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

Dopo aver generato il token di accesso a Tableau, aggiungi il token di credenziali Tableau all’intestazione di tutte le successive richieste API REST.

Intestazione

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

Tutte le successive richieste API REST che utilizzano il token di accesso di Tableau vengono quindi limitate dagli ambiti nel token JWT.

Metodi API REST che supportano l’autorizzazione JWT

Gli ambiti seguenti possono essere associati all’app connessa per definire l’accesso e i metodi che l’applicazione personalizzata può avere per l’API REST(Il collegamento viene aperto in una nuova finestra) per conto degli utenti.

Note:

• Per altre funzionalità dell’API REST non elencate nella tabella seguente, puoi utilizzare altri meccanismi di autorizzazione per accedere ai metodi. Per maggiori informazioni, consulta Metodi di autenticazione(Il collegamento viene aperto in una nuova finestra) nella Guida dell’API REST di Tableau.
• Sia i metodi di accesso(Il collegamento viene aperto in una nuova finestra) che di disconnessione(Il collegamento viene aperto in una nuova finestra) sono supportati dall’autorizzazione JWT, ma non richiedono ambiti per l’utilizzo a partire da giugno 2023 (Tableau 2023.2).
• Per gli ambiti supportati dall’API di incorporamento v3, consulta uno degli articoli seguenti:
  • Configurare le app connesse con un trust diretto
  • Configurare le app connesse con Trust OAuth 2.0

Ambiti con caratteri jolly (*)

Gli ambiti con caratteri jolly utilizzano il carattere jolly (*), invece di un’azione specifica, per abilitare più azioni supportate all’interno di una specifica categoria dell’API REST. Questi includono:

Ambiti cross-category

Gli ambiti cross-category consentono più azioni supportate in più categorie dell’API REST. Questi includono:

Ambiti individuali

Risolvere i problemi relativi agli ambiti

401001 - errore di accesso

Se riscontri l’errore 401001, viene aggiunto il corpo della risposta Accesso con uno dei seguenti codici di errore aggiuntivi specifici per le app connesse: 16, 10084 o 10085.

Ad esempio, nel corpo della risposta seguente, “10084” è il codice di errore delle app connesse che puoi utilizzare per risolvere i problemi relativi all’accesso a Tableau Cloud utilizzando un token JWT per l’autorizzazione dell’API REST.

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

Per agevolare la risoluzione del problema, fai riferimento alla descrizione del codice di errore applicabile e alle sue potenziali cause.

• 16: impossibile trovare l’utente - questo errore può verificarsi perché è stato specificato il valore "sub" (Nome utente) errato

• 10084: impossibile analizzare il token di accesso - questo errore può verificarsi per i seguenti motivi:

  • Il token JWT non è valido o si è verificato un problema imprevisto
  • È stato specificato il valore "aud" (Destinatari) errato
  • Per un trust diretto, si è verificato un problema con la firma del segreto

• 10085: impossibile recuperare il segreto per verificare la firma per l’ID client - questo errore può verificarsi per i seguenti motivi:

  • È stato specificato l’ID client errato in "iss"
  • Per un trust diretto, è stato specificato il valore "kid" (ID del segreto) errato
  • Per un trust OAuth 2.0, è impossibile recuperare le chiavi da JWKSource

401002 - errore di accesso non autorizzato

Se riscontri l’errore 401002 e hai verificato di disporre delle autorizzazioni appropriate per effettuare la richiesta, assicurati che l’ambito incluso nel token JWT sia corretto e corrisponda alla richiesta che stai tentando di eseguire. Per un elenco di endpoint e ambiti supportati, consulta la sezione Metodi API REST che supportano l’autorizzazione JWT più indietro.