Escopos de acesso para aplicativos conectados

A partir do Tableau Server versão 2022.3 , ao usar aplicativos conectados ao Tableau, você pode chamar e acessar programaticamente a API REST do Tableau por meio de seu aplicativo personalizado em nome dos usuários do Tableau Server. O acesso à API REST é habilitado por um JSON Web Token (JWT) definido como parte da solicitação inicial de login. O JWT deve conter escopos que definam os métodos da API REST que estão disponíveis para seu aplicativo personalizado e seus usuários por meio do aplicativo conectado.

Autorize o acesso à API REST usando aplicativos conectados para:

  • Aprimore a segurança — usar um JWT como token de portador é inerentemente mais seguro do que armazenar e gerenciar senhas de usuários administrativos por meio de arquivos .env em cofres
  • Aumente a eficiência — usar um JWT como token de portador permite uma representação simplificada com uma solicitação para o endpoint de login em vez de duas solicitações
  • Estenda e automatize integrações complexas do Tableau e consultas de back-end, como recuperação dinâmica de conteúdo e filtragem avançada

Ações de escopo

Os aplicativos conectados usam escopos que concedem acesso a ações de conteúdo ou administrativas por meio dos Métodos da API REST que dão suporte à autorização JWT (abaixo). Um escopo é uma cadeia de caracteres separada por dois pontos que começa com o namespace tableau, seguido pelo recurso do Tableau ao qual o acesso está sendo concedido, comodatasources e termina com a ação permitida no recurso, comoupdate.

As ações que um escopo pode realizar incluem:

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

Por exemplo, um escopo que permite que seu aplicativo personalizado chame o método Atualizar fonte de dados(O link abre em nova janela) se parece com:

tableau:datasources:update

Tipos de escopo

O tipo de escopo que você usa depende do conteúdo ou da ação administrativa que deseja habilitar. Os escopos geralmente se enquadram em um dos seguintes tipos: leitura de conteúdo, individual, curinga e categoria cruzada.

  • Escopo de leitura de conteúdo: o escopo de leitura de conteúdo, tableau:content:read, habilita métodos GET compatíveis para conteúdo do Tableau. Ao usar esse escopo, você habilita ações nas categorias da API REST. Mais especificamente, usando esse escopo, você habilita métodos GET para fontes de dados, métricas, exibições, pastas de trabalho, projetos e sites. A partir de Tableau Server 2023.3, você também especifica esse escopo em um JWT que será usado para criar um token de credenciais para uso com a API de metadados(O link abre em nova janela).

    Observação: para habilitar métodos GET para ações administrativas, como usuários e grupos, você pode usar seus escopos individuais.

  • Escopos individuais: para habilitar conteúdo suportado e ações administrativas, você pode usar seus escopos individuais. Um escopo individual geralmente é associado a um único método e categoria da API REST.

    Exemplos:

    • Para permitir publicar ou atualizar uma ação de fonte de dados, você pode usar o escopo individual tableau:datasources:create outableau:datasources:update, respectivamente.
    • Para ações administrativas como adicionar ou remover usuários, você pode usar o escopo individual tableau:users:create ou tableau:users:delete, respectivamente.

    Observação: existem alguns escopos individuais que podem permitir ações nas categorias da API REST. Por exemplo, tableau:views:download permite ações nas categorias de API REST de exibição de dados e pastas de trabalho.

  • Escopos curinga: para determinados escopos, você pode substituir a ação pelo caractere curinga (*) para habilitar ações com suporte em uma categoria de API REST específica.

    Exemplos:

    • Você pode usar o escopo curinga tableau:projects:* para habilitar as ações de criação, exclusão e atualização na categoria API REST de projetos.
    • Você pode usar o escopo curinga tableau:users:* para habilitar as ações de obter lista, adição, exclusão e atualização na categoria API REST de usuários.
    • Você pode usar o escopo curinga tableau:tasks:* para habilitar as ações de obter/listar, adicionar, excluir, atualizar e executar ações de categorias de API REST de extração e assinaturas. Além disso, esse escopo permite atualizar a fonte de dados (se for uma extração) e atualizar a pasta de trabalho.
  • Escopos de categoria cruzada: além do escopo de leitura de conteúdo, há alguns escopos adicionais que, se usados, habilitam ações com suporte em diferentes categorias de API REST.

    Exemplos:

    • Se estiver usando o escopo tableau:tasks:run, você habilitará ações nas fontes de dados e categorias de API REST de pastas de trabalho.
    • Novamente, se estiver usando o escopo tableau:views:download, habilite ações nas categorias API REST de exibição de dados e pasta de trabalho.
    • Se estiver usando escopos de permissões como tableau:permissions:update outableau:permissions:delete, você ativa ações nas fontes de dados, pastas de trabalho e categorias de API REST de projetos.

Resumo de como autorizar o acesso à API REST

A lista a seguir resume as etapas para solicitar acesso à API REST por meio de um JWT:

  1. Crie um aplicativo conectado usando um dos seguintes métodos:
  2. Gere um JWT válido — em tempo de execução, seu aplicativo personalizado gerará um JWT válido, configurado com os escopos que você incluiu
  3. Faça uma solicitação de login(O link abre em nova janela) — seu aplicativo personalizado fará uma solicitação de login usando o JWT para retornar um token de credenciais do Tableau e um ID do site (LUID)
  4. Use o token de acesso do Tableau em solicitações subsequentes — em chamadas subsequentes da API REST, use 1) o token de credenciais do Tableau como o valor de cabeçalho X-Tableau-Auth(O link abre em nova janela) e 2) o ID do site (LUID) no URI de solicitação

Exemplo

Por exemplo, suponha que você crie um aplicativo conectado usando confiança direta. Usando confiança direta, seu aplicativo personalizado que chama a API REST gera um JWT válido usando o ID do cliente e o segredo do cliente gerados pelo aplicativo conectado.

Escopos no JWT

Para autorizar com êxito o acesso à API REST, o JWT também deve conter os escopos que definem os recursos da API REST. Por exemplo, para habilitar vários métodos relacionados à fonte de dados, você pode incluir os seguintes escopos no 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"

Observação: os valores devem ser passados como um tipo de lista.

URI de solicitação de logon

Para fazer uma chamada para a API REST, seu aplicativo personalizado deve primeiro fazer uma solicitação de logon para gerar um token de credenciais do Tableau.

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

Corpo da solicitação

Para autorizar o acesso à API REST usando um JWT, o corpo da solicitação de logon deve conter o JWT válido, como no exemplo abaixo.

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

Corpo de resposta

A solicitação de logon produz o seguinte corpo de resposta, que inclui o token de credenciais do Tableau.

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

Depois que o token de acesso do Tableau for gerado, adicione as credenciais de acesso do Tableau ao cabeçalho de todas as solicitações de API REST subsequentes.

Cabeçalho

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

Todas as solicitações subsequentes da API REST usando o token de acesso do Tableau são delimitadas pelos escopos no JWT.

Métodos da API REST que dão suporte à autorização JWT

Os escopos a seguir podem ser associados ao aplicativo conectado para definir o acesso e os métodos que seu aplicativo personalizado pode ter à API REST(O link abre em nova janela) em nome dos usuários.

Observações:

Escopos curinga (*)

Os escopos curinga usam o caractere curinga (*) em vez de uma ação específica, para ativar diversas ações suportadas em uma categoria específica da API REST. Esses incluem:

EscopoMétodos ativados
tableau:datasources:*Permite criar, atualizar e atualizar métodos de fonte de dados de conexão.
tableau:metrics:*Habilita ações de consulta, atualização e exclusão de métricas.
tableau:workbooks:*Permite publicar, atualizar, baixar e visualizar as ações da pasta de trabalho da imagem.
tableau:groups:*Permite criar, consultar, atualizar e excluir ações de grupos.
tableau:projects:*Permite criar, excluir e atualizar métodos de projetos.
tableau:users:*Permite obter/listar, adicionar, excluir e atualizar métodos de usuários.
tableau:tasks:*

Observação: este escopo também é de categoria cruzada.

Permite obter/listar, adicionar, excluir, atualizar e executar métodos para extrações e tarefas de assinatura.

Habilita métodos de atualização para fontes de dados de pastas de trabalho.

Escopos entre categorias

Os escopos entre categorias permitem diversas ações com suporte em diversas categorias da API REST. Esses incluem:

EscopoMétodos ativados
tableau:content:readPermite métodos de leitura/lista para conteúdo do Tableau, incluindo fontes de dados, métricas, visualizações, pastas de trabalho, projetos e sites.
tableau:tasks:runPermite executar métodos para fontes de dados, pastas de trabalho e extrações.
tableau:views:downloadPermite métodos de download para visualizar dados e pastas de trabalho.
tableau:tasks:*

Observação: este escopo também é curinga.

Permite obter/listar, adicionar, excluir, atualizar e executar métodos para extrações e tarefas de assinatura.

Habilita métodos de atualização para fontes de dados de pastas de trabalho.

Escopos individuais

MétodoEscopoDescrição
(Métodos sem escopos)(Nenhum)Quando nenhum escopo é definido no JWT, o acesso à API REST é negado.
Fazer logon(Não é necessário escopo)Conecta você como usuário no o site especificado no Tableau Server.
Sair(Não é necessário escopo)Desconecta você da sessão atual.
(Escopo de leitura do conteúdo)tableau:content:readHabilita ações de leitura/listagem para conteúdo do Tableau: fontes de dados, métricas, exibições, pastas de trabalho e projetos.

Fontes de dados

  
(Todos os métodos tableau:datasources:)tableau:datasources:*Permite criar fontes de dados, atualizar fontes de dados e atualizar métodos de conexão de fontes de dados.
Fonte de dados publicadastableau:datasources:createPublicar uma fonte de dados em um site ou anexar dados a uma fonte de dados publicada existente.
Consultar fonte de dadostableau:content:readObter informações sobre uma fonte de dados publicada.
Consultar fontes de dadostableau:content:readObter informações sobre todas as fontes de dados publicadas em um site.
Consultar conexões de fonte de dadostableau:content:readObter o endereço do servidor, porta, nome de usuário ou informações de senha sobre uma fonte de dados publicada.
Atualizar fonte de dadostableau:datasources:updateAtualizar o status do proprietário, projeto ou certificação da fonte de dados.
Atualizar conexão de fonte de dadostableau:datasources:updateAtualizar o endereço do servidor, porta, nome de usuário ou senha da conexão da fonte de dados.
Atualizar fonte de dados agoratableau:tasks:runExecutar extração manual.

Extrações

  
(Todos os métodos tableau:tasks:)tableau:tasks:*Permite criar, excluir, obter, listar, executar e atualizar ações de atualização para extrações, assinaturas, atualizar fontes de dados (para fontes de dados com extrações) e atualizar métodos de pasta de trabalho.
Listar tarefas de atualização de extração no sitetableau:tasks:readListe as tarefas de atualização de extração configuradas em um site.
Executar tarefa de atualização de extraçãotableau:tasks:runExecuta Tarefa de atualização de extração na nuvem.

Fluxos

  
Publicar fluxostableau:flows:createPublicar um fluxo.

Métricas

Descontinuação do recurso de métricas herdado

O recurso de métricas herdado do Tableau será descontinuado no Tableau Cloud em fevereiro de 2024 e no Tableau Server versão 2024.2. Em outubro de 2023, o Tableau retirou a habilidade de inserir métricas herdadas no Tableau Cloud e no Tableau Server versão 2023.3. Com o Tableau Pulse, desenvolvemos uma experiência aprimorada para monitorar métricas e fazer perguntas sobre seus dados. Para obter mais informações, veja Criar métricas com o Tableau Pulse para conhecer a nova experiência e Criar e solucionar problemas de métricas (descontinuado) para o recurso descontinuado.

(Todos os métodos tableau:metrics:)tableau:metrics:*Habilita ações de consulta, atualização e exclusão de métricas.
Obter métricatableau:content:readObter uma métrica.
Excluir métricatableau:metrics:deleteExcluir uma métrica.
Listar métricastableau:content:readObter lista de métricas para um site.
Consultar dados de métricastableau:metrics:downloadObter dados subjacentes de uma métrica no formato de valor separado por vírgula (.csv).
Atualizar métricatableau:metrics:updateAtualizar proprietário, projeto, status de suspensão e nome da métrica.

Assinaturas

  
(Todos os métodos tableau:tasks:)tableau:tasks:*Permite criar, excluir, obter, listar, executar e atualizar ações de atualização para extrações, assinaturas, atualizar fontes de dados (para fontes de dados com extrações) e atualizar métodos de pasta de trabalho.
Criar assinaturatableau:tasks:createCria uma assinatura.
Excluir assinaturatableau:tasks:deleteExclua uma assinatura.
Obter assinaturatableau:tasks:readObtém os detalhes de uma assinatura.
Listar assinaturastableau:tasks:readLista assinaturas em um site.
Atualiza a assinaturatableau:tasks:updateAtualiza uma assinatura.

Exibições

  
Excluir exibição personalizadatableau:views:updateExclua a exibição personalizada especificada.
Obtenha a exibição personalizadatableau:content:readObtenha os detalhes de uma exibição personalizada especificada.
Obter imagem de exibição personalizadatableau:views:downloadBaixe um arquivo de imagem em formato .png de uma exibição personalizada especificada.
Obter exibiçãotableau:content:readObter detalhes sobre uma visualização.
Obter visualização por caminhotableau:content:readObter detalhes de todas as visualizações em um site usando o nome especificado.
Listar exibições personalizadastableau:content:readObter uma lista de exibições personalizadas em um site.
Consultar dados de exibiçãotableau:views:downloadObter uma exibição renderizada no formato de valor separado por vírgula (.csv).
Consultar PDF de exibiçãotableau:views:downloadObter uma exibição como um arquivo PDF (.pdf).
Consultar imagem da exibiçãotableau:views:downloadObter uma exibição como um arquivo de imagem (.png).
Consultar exibições do sitetableau:content:readObter todas as exibições de um site.
Consultar exibições da pasta de trabalhotableau:content:readObter todas as exibições da pasta de trabalho especificada.
Consultar imagem de visualização da exibiçãotableau:views:downloadObter a imagem em miniatura (.png) da exibição.
Atualizar a exibição personalizadatableau:views:updateAltere o proprietário ou o nome de uma exibição personalizada existente.

Pastas de trabalho

  
(Todos os métodos tableau:workbooks:)tableau:workbooks:*Permite publicar, atualizar, baixar e visualizar as ações da pasta de trabalho da imagem.
Publicar uma pasta de trabalhotableau:workbooks:createPublicar uma pasta de trabalho (.twb ou .twbx).
Consultar pasta de trabalhotableau:content:readObter uma pasta de trabalho especificada e seus detalhes.
Consultar pasta de trabalho para o sitetableau:content:readObter uma lista de pastas de trabalho publicadas em um site.
Consultar imagem de visualização da pasta de trabalhotableau:workbooks:downloadObter a imagem em miniatura (.png) da pasta de trabalho.
Atualizar pasta de trabalhotableau:workbooks:updateModificar uma pasta de trabalho existente.
Atualizar conexão da pasta de trabalhotableau:workbooks:updateAtualize as informações de conexão.
Atualizar pasta de trabalho agoratableau:tasks:runIniciar uma atualização de pasta de trabalho fora de uma tarefa agendada.

Publicar

  
Anexar ao upload do arquivotableau:file_uploads:createCarregar um bloco de dados e anexe-o aos dados que já foram carregados - para ser usado após o início de um upload usando o método "iniciar upload de arquivo".
Iniciar upload de arquivotableau:file_uploads:createIniciar o processo de upload de um arquivo.

Baixar

  
Baixar fonte de dadostableau:datasources:downloadBaixar a fonte de dados (.tdsx).
Baixar Excel da tabela de referência cruzada da exibiçãotableau:views:downloadFazer download de um arquivo Excel (.xlsx) contendo dados de tabela de referência cruzada da exibição.
Baixar pastas de trabalhotableau:workbooks:downloadBaixar uma pasta de trabalho (.twb ou .twbx).
Baixar revisão da pasta de trabalhotableau:workbooks:downloadBaixar uma versão específica da pasta de trabalho (.twb ou .twbx).
Baixar PDF da pasta de trabalhotableau:views:downloadBaixar um arquivo PDF (.pdf) contendo imagens das planilhas na pasta de trabalho.
Baixar o Power Point da pasta de trabalhotableau:views:downloadBaixar um arquivo Power Point (.pptx) contendo os slides das planilhas na pasta de trabalho.

Usuários

  
(Todos os métodos tableau:users)tableau:users:*Permite adicionar, consultar, atualizar e remover ações de usuários.
Adicionar usuário ao grupotableau:groups:updateAdicionar um usuário a um grupo.
Adicionar usuário ao sitetableau:users:createAdicionar um usuário e atribuir o usuário a um site.
Obter usuários no grupotableau:groups:readObter uma lista de usuários em um grupo.
Obter usuários no sitetableau:users:readObter todos os usuários de um site.
Consultar usuário no sitetableau:users:readObter um usuário em um site.
Remover usuários do grupotableau:groups:updateRemover um usuário de um grupo.
Remover usuário do sitetableau:users:deleteRemover o usuário de um site.

Grupos

  
(Todos os métodos tableau:groups:)tableau:groups:*Permite criar, consultar, atualizar e excluir ações de grupos.
Criar grupotableau:groups:createCriar um grupo.
Excluir grupotableau:groups:deleteExcluir um grupo.
Obter grupos para o usuáriotableau:users:readObter uma lista de grupos aos quais um usuário pertence.
Consultar grupostableau:groups:readObter uma lista de grupos em um site.
Atualizar grupotableau:groups:updateAtualizar um grupo.

Projetos

  
(Todos os métodos tableau:projects:)tableau:projects:*Permite criar, atualizar e excluir ações de projetos.
Criar projetotableau:projects:createCriar um projeto.
Excluir projetotableau:projects:deleteExcluir um projeto.
Consultar projetotableau:content:readObter uma lista de projetos.
Atualizar projetotableau:projects:updateAtualizar o nome, a descrição ou a hierarquia do projeto.

Permissões

  
(Todos os métodos tableau:permissions:)tableau:permissions:*Permite adicionar, consultar, atualizar, excluir ações de permissões.
Adicionar permissões de fonte de dadostableau:permissions:updateAdicionar permissões a uma fonte de dados para um usuário ou grupo do Tableau Server.
Adicionar permissões padrãotableau:permissions:updateAdicionar recursos de permissão padrão a um usuário ou grupo, para métrica, fluxo, pasta de trabalho, fonte de dados, função de dados ou recursos de ampliação em um projeto.
Adicionar permissões do projetotableau:permissions:updateAdicionar permissões a um projeto para um usuário ou grupo
Adicionar permissões da exibiçãotableau:permissions:updateAdicionar permissões a uma exibição para um usuário ou grupo.
Adicionar permissões da pasta de trabalhotableau:permissions:updateAdicionar permissões a uma pasta de trabalho especificada para um usuário ou grupo.
Excluir permissões de fonte de dadostableau:permissions:deleteExcluir recursos de permissão padrão de um usuário ou grupo, para métrica, fluxo, pasta de trabalho, fonte de dados, função de dados ou recursos de ampliação em um projeto.
Excluir permissões padrãotableau:permissions:deleteExcluir recursos de permissão padrão de um usuário ou grupo, para métrica, fluxo, pasta de trabalho, fonte de dados, função de dados ou recursos de ampliação em um projeto.
Excluir permissões do projetotableau:permissions:deleteExcluir a permissão do projeto para um usuário ou grupo.
Excluir permissões da exibiçãotableau:permissions:deleteExcluir a permissão da exibição de um usuário ou grupo.
Excluir permissões da pasta de trabalhotableau:permissions:deleteExcluir a permissão da pasta de trabalho para um usuário ou grupo.
Consultar permissões de fonte de dadostableau:permissions:readObter uma lista de permissões para a fonte de dados.
Consultar permissões padrãotableau:permissions:readObtenha recursos de permissão padrão de usuários e grupos para métricas, pastas de trabalho e fontes de dados.
Consultar permissões do projetotableau:permissions:readObter uma lista de permissões para o projeto.
Consultar permissões de exibiçãotableau:permissions:readObter uma lista de permissões para a exibição.
Consultar permissões de pasta de trabalhotableau:permissions:readObter uma lista de permissões para a pasta de trabalho.

Site

  
(Todos os métodos tableau:sites:)tableau:sites:*Permite criar, consultar, atualizar e excluir ações de sites.
Criar sitetableau:sites:createCriar um site no Tableau Server.
Excluir sitetableau:sites:deleteExcluir um site no Tableau Server.
Obter site visualizado recentementetableau:content:readObter exibições e detalhes de pastas de trabalho sobre as mais recentemente criadas, atualizadas ou acessadas pelo usuário conectado.
Consultar sitestableau:sites:readListar todos os sites no Tableau Server.
Consultar exibições do sitetableau:content:readListar todas as exibições em um site.
Atualizar sitetableau:sites:updateAtualizar um site.

Solucionar problemas de escopos

401001 - erro de login

Se você encontrar o erro 401001, o corpo da resposta de login será anexado com um dos seguintes códigos de erro adicionais específicos de aplicativos conectados: 16, 10084 ou 10085.

Por exemplo, no corpo da resposta a seguir, "10084" é o código de erro dos aplicativos conectados que você pode usar para ajudar a solucionar problemas ao fazer login no Tableau Server usando um JWT para autorização de API REST.

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

Para ajudar a resolver o problema, consulte a descrição do código de erro aplicável e suas possíveis causas.

  • 16: Não foi possível encontrar o usuário — esse erro pode ocorrer porque o "sub" (nome de usuário) foi especificado

  • 10084: Não foi possível analisar o token de acesso — esse erro pode ocorrer pelos seguintes motivos:

    • O JWT é inválido ou ocorreu um problema inesperado
    • O "aud " (público) incorreto foi especificado
    • Para confiança direta, houve um problema ao assinar o segredo
  • 10085: Não foi possível buscar o segredo para verificar a assinatura do ID do cliente — esse erro pode ocorrer pelos seguintes motivos:

    • ID de cliente incorreto em "iss " especificada
    • Para confiança direta, "kid " (ID secreta) incorreta foi especificada
    • Para EAS, não foi possível recuperar as chaves do JWKSource

401002 - erro de acesso não autorizado

Se você encontrar o erro 401002 e tiver confirmado que possui as permissões apropriadas para fazer a solicitação, certifique-se de que o escopo incluído no JWT esteja correto e corresponda à solicitação que você está tentando fazer. Para obter uma lista de endpoints e escopos com suporte, consulte a seção Métodos da API REST que dão suporte à autorização JWT acima.

Agradecemos seu feedback!Seu feedback foi enviado. Obrigado!