연결된 앱의 액세스 범위

Tableau Server 버전 2022.3부터 Tableau의 연결된 앱을 사용하여 Tableau Server 사용자 대신 사용자 지정 응용 프로그램을 통해 Tableau REST API를 프로그래밍 방식으로 호출하고 액세스할 수 있습니다. REST API에 대한 액세스는 초기 로그인 요청의 일부로 정의된 JWT(JSON Web Token)로 지원됩니다. JWT에는 사용자 지정 응용 프로그램과 해당 사용자가 연결된 앱을 통해 사용할 수 있는 REST API 메서드를 정의하는 범위가 포함되어야 합니다.

연결된 앱을 사용하여 REST API에 액세스할 수 있는 권한을 부여하면 다음과 같은 이점이 있습니다.

  • 보안 향상 - JWT를 전달자 토큰으로 사용하면 자격 증명 모음에서 .env 파일을 통해 관리자 사용자 비밀번호를 저장하고 관리하는 것보다 본질적으로 더 안전합니다.
  • 효율성 개선 - JWT를 전달자 토큰으로 사용하면 로그인 엔드포인트에 요청을 두 번이 아닌 한 번만 전송하여 가장을 간소화할 수 있음
  • 복잡한 Tableau 통합 및 백엔드 쿼리(예: 동적 콘텐츠 검색 및 고급 필터링)를 확장하고 자동화할 수 있음

범위 동작

연결된 앱은 범위를 사용하여 JWT 권한 부여를 지원하는 REST API 메서드를 통해 콘텐츠 관리 동작에 대한 액세스 권한을 부여합니다(아래 참조). 범위는 콜론으로 구분되는 문자열이며 tableau 네임스페이스로 시작되어 액세스 권한이 부여된 Tableau 리소스(예: datasources)가 뒤에 오고 해당 리소스에서 허용되는 동작(예: update)으로 끝납니다.

범위에 사용될 수 있는 동작은 다음과 같습니다.

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

예를 들어 사용자 지정 응용 프로그램에서 데이터 원본 업데이트(링크가 새 창에서 열림) 메서드를 호출하는 것을 허용하는 범위는 다음과 같습니다.

tableau:datasources:update

범위 유형

사용하는 범위 유형은 사용하려는 콘텐츠 또는 관리 동작에 따라 다릅니다. 범위는 일반적으로 콘텐츠 읽기, 개별, 와일드카드 및 교차 범주 유형 중 하나에 포함됩니다.

  • 콘텐츠 읽기 범위: 콘텐츠 읽기 범위인 tableau:content:read를 사용하면 Tableau 콘텐츠에 지원되는 GET 메서드를 사용할 수 있습니다. 이 범위를 사용할 때는 여러 REST API 범주에 걸쳐 동작이 사용됩니다. 보다 구체적으로 말해 이 범위를 사용하면 데이터 원본, 메트릭, 뷰, 통합 문서, 프로젝트 및 사이트에 GET 메서드를 사용할 수 있습니다.

    참고: 사용자 및 그룹과 같은 관리 동작에 GET 메서드를 사용하려면 해당하는 개별 범위를 사용하면 됩니다.

  • 개별 범위: 지원되는 콘텐츠 및 관리 동작을 사용하려면 해당하는 개별 범위를 사용하면 됩니다. 개별 범위는 일반적으로 단일 메서드 및 REST API 범주와 연결됩니다.

    예:

    • 데이터 원본 게시 또는 업데이트 동작을 사용하려면 개별 tableau:datasources:create 또는 tableau:datasources:update 범위를 각각 사용하면 됩니다.
    • 사용자 추가 또는 제거와 같은 관리 동작의 경우 개별 tableau:users:create 또는 tableau:users:delete 범위를 각각 사용하면 됩니다.

    참고: 일부 개별 범위의 경우 여러 REST API 범주에 걸쳐 동작을 사용할 수 있습니다. 예를 들어 tableau:views:download를 사용하면 뷰 데이터 및 통합 문서 REST API 범주에서 동작을 사용할 수 있습니다.

  • 와일드카드 범위: 특정 범위의 경우 와일드카드 문자(*)로 동작을 대체하여 특정 REST API 범주 내에서 지원되는 동작을 사용할 수 있습니다.

    예:

    • tableau:projects:* 와일드카드 범위를 사용하면 프로젝트 REST API 범주에서 만들기, 삭제, 업데이트 동작을 사용할 수 있습니다.
    • tableau:users:* 와일드카드 범위를 사용자 REST API 범주에서 쿼리, 추가, 삭제, 업데이트 동작을 사용할 수 있습니다.
  • 교차 범주 범위: 콘텐츠 읽기 범위뿐 아니라 몇 가지 추가 범위를 사용하여 여러 REST API 범주에 걸쳐 지원되는 동작을 사용할 수 있습니다.

    예:

    • tableau:tasks:run 범위를 사용하면 데이터 원본 및 통합 문서 REST API 범주에서 동작을 사용할 수 있습니다.
    • 마찬가지로, tableau:views:download 범위를 사용하면 뷰 데이터 및 통합 문서 REST API 범주에서 동작을 사용할 수 있습니다.
    • tableau:permissions:update 또는 tableau:permissions:delete와 같은 사용 권한 범위를 사용하면 데이터 원본, 통합 문서 및 프로젝트 REST API 범주에서 동작을 사용할 수 있습니다.

REST API 액세스 권한 부여 방법 요약

다음 목록은 JWT를 통해 REST API에 대한 액세스 권한을 요청하는 단계를 요약한 것입니다.

  1. 다음 방법 중 하나를 사용하여 연결된 앱 만들기
  2. 유효한 JWT 생성 - 포함된 범위로 구성된 유효한 JWT가 사용자 지정 응용 프로그램을 통해 생성됨
  3. 로그인(링크가 새 창에서 열림) 요청 만들기 - 사용자 지정 응용 프로그램에서 JWT를 사용하여 Tableau 자격 증명 토큰 및 사이트 ID(LUID)를 반환하는 로그인 요청을 생성함
  4. 후속 요청에서 Tableau 액세스 토큰 사용 - 후속 REST API 호출에서 1) Tableau 자격 증명 토큰을 X-Tableau-Auth(링크가 새 창에서 열림) 헤더 값으로 사용하고 2) 사이트 ID(LUID)를 요청 URI에 사용

예를 들어 직접 신뢰를 사용하여 연결된 앱을 만든다고 하겠습니다. 직접 신뢰를 사용하면 REST API를 호출하는 사용자 지정 응용 프로그램에서 연결된 앱을 통해 생성된 클라이언트 ID와 클라이언트 암호를 사용하여 유효한 JWT를 생성합니다.

JWT의 범위

REST API에 대한 액세스 권한을 성공적으로 부여하려면 JWT에 REST API 기능을 정의하는 범위가 포함되어야 합니다. 예를 들어 다양한 데이터 원본 관련 메서드를 사용하려면 JWT에 다음 범위를 포함할 수 있습니다.

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

또는

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

참고: 범위 값을 목록 유형으로 전달해야 합니다.

로그인 요청 URI

REST API를 호출하려면 사용자 지정 응용 프로그램에서 먼저 Tableau 자격 증명 토큰을 생성하기 위한 로그인 요청을 전송해야 합니다.

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

요청 본문

JWT를 사용하여 REST API 액세스 권한을 부여하려면 로그인 요청 본문에 아래 예제와 같은 유효한 JWT를 포함해야 합니다.

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

응답 본문

로그인 요청에서는 Tableau 자격 증명 토큰이 포함된 다음과 같은 응답 본문이 생성됩니다.

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

Tableau 자격 증명 토큰이 생성되면 Tableau 자격 증명 토큰을 모든 후속 REST API 요청의 헤더에 추가합니다.

헤더

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

Tableau 액세스 토큰을 사용하는 모든 후속 REST API 요청은 JWT의 범위로 바인딩됩니다.

JWT 권한 부여를 지원하는 REST API 메서드

다음 범위를 연결된 앱에 연결하여 사용자 지정 응용 프로그램에서 사용자 대신 REST API(링크가 새 창에서 열림)에 대해 가질 수 있는 액세스 권한 및 메서드를 정의할 수 있습니다.

참고:

방법범위설명
범위 없음(범위 없음)JWT에 범위가 정의되지 않은 경우 REST API에 대한 액세스가 거부됩니다.
로그인(범위 없음)Tableau Server의 지정된 사이트에서 사용자로 로그인합니다.
로그아웃(범위 없음)현재 세션에서 로그아웃합니다.
(콘텐츠 읽기 범위)tableau:content:read데이터 원본, 메트릭, 뷰, 통합 문서 및 프로젝트와 같은 Tableau 콘텐츠에 대한 쿼리 동작을 사용합니다.

데이터 원본

  
데이터 원본 게시tableau:datasources:create데이터 원본을 사이트에 게시하거나 데이터를 기존의 게시된 데이터 원본에 추가합니다.
데이터 원본 쿼리tableau:content:read게시된 데이터 원본에 대한 정보를 가져옵니다.

데이터 원본 쿼리

tableau:content:read사이트에 게시된 모든 데이터 원본에 대한 정보를 가져옵니다.
데이터 원본 연결 쿼리tableau:content:read게시된 데이터 원본에 대한 서버 주소, 포트, 사용자 이름 또는 비밀번호 정보를 가져옵니다.
데이터 원본 업데이트tableau:datasources:update데이터 원본의 소유자, 프로젝트 또는 인증 상태를 업데이트합니다.
데이터 원본 연결 업데이트tableau:datasources:update데이터 원본 연결의 서버 주소, 포트, 사용자 이름 또는 비밀번호를 업데이트합니다.
지금 데이터 원본 업데이트tableau:tasks:run추출 새로 고침을 실행합니다.
(데이터 원본 메서드)tableau:datasources:*데이터 원본 게시 및 업데이트 동작을 사용합니다.

흐름

  
흐름 게시tableau:flows:create흐름을 게시합니다.

메트릭

  
메트릭 가져오기tableau:content:read메트릭을 가져옵니다.
메트릭 삭제tableau:metrics:delete메트릭을 삭제합니다.
메트릭 나열tableau:content:read사이트의 메트릭 목록을 가져옵니다.
메트릭 데이터 쿼리tableau:metrics:download메트릭의 기초 데이터를 쉼표로 구분된 값(.csv) 형식으로 가져옵니다.
메트릭 업데이트tableau:metrics:update메트릭의 소유자, 프로젝트, 일시 중단 상태 및 이름을 업데이트합니다.
(메트릭 메서드)tableau:metrics:*메트릭 쿼리, 업데이트 및 삭제 동작을 사용합니다.

  
사용자 지정 뷰 삭제tableau:views:update지정된 사용자 지정 뷰를 삭제합니다.
사용자 지정 뷰 가져오기tableau:content:read지정된 사용자 지정 뷰의 세부 정보를 가져옵니다.
사용자 지정 뷰 이미지 가져오기tableau:views:download지정된 사용자 지정 뷰의 이미지 파일을 .png 형식으로 다운로드합니다.
뷰 가져오기tableau:content:read뷰에 대한 세부 정보를 가져옵니다.
경로별 뷰 가져오기tableau:content:read지정된 이름을 사용하여 사이트의 모든 뷰에 대한 세부 정보를 가져옵니다.
사용자 지정 뷰 나열tableau:content:read사이트의 사용자 지정 뷰 목록을 가져옵니다.
뷰 데이터 쿼리tableau:views:download쉼표로 구분된 값(.csv) 형식으로 렌더링된 뷰를 가져옵니다.
뷰 PDF 쿼리tableau:views:download뷰를 PDF(.pdf) 파일로 가져옵니다.
뷰 이미지 쿼리tableau:views:download뷰를 이미지(.png) 파일로 내보냅니다.
사이트의 뷰 쿼리tableau:content:read사이트의 모든 뷰를 가져옵니다.
사이트의 뷰를 쿼리합니다.tableau:content:read지정된 통합 문서의 모든 뷰를 가져옵니다.
뷰 미리 보기 이미지 쿼리tableau:views:download뷰의 축소판 이미지(.png)를 가져옵니다.
사용자 지정 뷰 업데이트tableau:views:update기존 사용자 지정 뷰의 소유자 또는 이름을 변경합니다.

통합 문서

  
통합 문서 게시tableau:workbooks:create통합 문서를 게시합니다(.twb 또는 .twbx).
통합 문서 쿼리tableau:content:read지정된 통합 문서 및 해당 세부 정보를 가져옵니다.
사이트의 통합 문서 쿼리tableau:content:read사이트에 게시된 통합 문서 목록을 가져옵니다.
통합 문서 미리 보기 이미지 쿼리tableau:workbooks:download통합 문서의 축소판 이미지(.png)를 가져옵니다.
통합 문서 업데이트tableau:workbooks:update기존 통합 문서를 수정합니다.
통합 문서 연결 업데이트tableau:workbooks:update연결 정보를 업데이트합니다.
지금 통합 문서 업데이트tableau:tasks:run예약된 작업 외부에서 통합 문서 새로 고침을 시작합니다.
(통합 문서 메서드)tableau:workbooks:*통합 문서 이미지 게시, 업데이트, 다운로드 및 미리 보기 동작을 사용합니다.

게시

  
파일 업로드에 추가tableau:file_uploads:create데이터 블록을 업로드한 다음 이미 업로드된 데이터에 추가하여 "파일 업로드 시작" 메서드를 사용하여 업로드가 시작된 후 사용합니다.
파일 업로드 시작tableau:file_uploads:create파일의 업로드 프로세스를 시작합니다.

다운로드

  
데이터 원본 다운로드tableau:datasources:download데이터 원본을 다운로드합니다(.tdsx).
뷰 크로스탭 Excel 다운로드tableau:views:download뷰의 크로스탭 데이터가 포함된 Excel(.xlsx) 파일을 다운로드합니다.
통합 문서 다운로드tableau:workbooks:download통합 문서를 다운로드합니다(.twb 또는 .twbx).
통합 문서 수정 버전 다운로드tableau:workbooks:download통합 문서의 특정 버전을 다운로드합니다(.twb 또는 .twbx).
통합 문서 PDF 다운로드tableau:views:download통합 문서의 시트 이미지가 포함된 PDF(.pdf) 파일을 다운로드합니다.
통합 문서 Power Point 다운로드tableau:views:download통합 문서의 시트 슬라이드가 포함된 PowerPoint(.pptx) 파일을 다운로드합니다.

사용자

  
그룹에 사용자 추가tableau:groups:update그룹에 사용자를 추가합니다.
사이트에 사용자 추가tableau:users:create사이트에 사이트를 추가하고 할당합니다.
그룹의 사용자 가져오기tableau:groups:read그룹의 사용자 목록을 가져옵니다.
사이트의 사용자 가져오기tableau:users:read사이트의 모든 사용자를 가져옵니다.
사이트의 사용자 쿼리tableau:users:read사이트의 사용자를 가져옵니다.
그룹에서 사용자 제거tableau:groups:update그룹에서 사용자를 제거합니다.
사이트에서 사용자 제거tableau:users:delete사이트에서 사용자를 제거합니다.
(사용자 메서드)tableau:users:*사용자 추가, 쿼리, 업데이트 및 제거 동작을 사용합니다.

그룹

  
그룹 만들기tableau:groups:create그룹을 만듭니다.
그룹 삭제tableau:groups:delete그룹을 삭제합니다.
사용자의 그룹 가져오기tableau:users:read사용자가 속한 그룹 목록을 가져옵니다.
그룹 쿼리tableau:groups:read사이트의 그룹 목록을 가져옵니다.
그룹 업데이트tableau:groups:update그룹을 업데이트합니다.
(그룹 메서드)tableau:groups:*그룹 만들기, 쿼리, 업데이트 및 삭제 동작을 사용합니다.

프로젝트

  
프로젝트 만들기tableau:projects:create프로젝트를 만듭니다.
프로젝트 삭제tableau:projects:delete프로젝트를 삭제합니다.
프로젝트 쿼리tableau:content:read프로젝트 목록을 가져옵니다.
프로젝트 업데이트tableau:projects:update프로젝트의 이름, 설명 또는 프로젝트 계층 구조를 업데이트합니다.
(프로젝트 메서드)tableau:projects:*프로젝트 만들기, 업데이트 및 삭제 동작을 사용합니다.

사용 권한

  
데이터 원본 사용 권한 추가tableau:permissions:update데이터 원본에 Tableau Server 사용자 또는 그룹에 대한 사용 권한을 추가합니다.
기본 사용 권한 추가tableau:permissions:update프로젝트의 메트릭, 흐름, 통합 문서, 데이터 원본, 데이터 역할 또는 렌즈 리소스에 대한 기본 사용 권한 기능을 사용자 또는 그룹에 추가합니다.
프로젝트 사용 권한 추가tableau:permissions:update프로젝트에 사용자 또는 그룹에 대한 사용 권한 추가
뷰 사용 권한 추가tableau:permissions:update뷰에 사용자 또는 그룹에 대한 사용 권한을 추가합니다.
통합 문서 사용 권한 추가tableau:permissions:update지정된 통합 문서에 사용자 또는 그룹에 대한 사용 권한을 추가합니다.
데이터 원본 사용 권한 삭제tableau:permissions:delete프로젝트의 메트릭, 흐름, 통합 문서, 데이터 원본, 데이터 역할 또는 렌즈 리소스에 대한 사용자 또는 그룹의 기본 사용 권한 기능을 삭제합니다.
기본 사용 권한 삭제tableau:permissions:delete프로젝트의 메트릭, 흐름, 통합 문서, 데이터 원본, 데이터 역할 또는 렌즈 리소스에 대한 사용자 또는 그룹의 기본 사용 권한 기능을 삭제합니다.
프로젝트 사용 권한 삭제tableau:permissions:delete사용자 또는 그룹에 대한 프로젝트 사용 권한을 삭제합니다.
뷰 사용 권한 삭제tableau:permissions:delete사용자 또는 그룹에 대한 뷰 사용 권한을 삭제합니다.
통합 문서 사용 권한 삭제tableau:permissions:delete사용자 또는 그룹에 대한 통합 문서 사용 권한을 삭제합니다.
데이터 원본 사용 권한 쿼리tableau:permissions:read데이터 원본에 대한 사용 권한 목록을 가져옵니다.
기본 사용 권한 쿼리tableau:permissions:read메트릭, 통합 문서 및 데이터 원본에 대한 사용자 및 그룹의 기본 사용 권한 기능을 가져옵니다.
프로젝트 사용 권한 쿼리tableau:permissions:read프로젝트에 대한 사용 권한 목록을 가져옵니다.
뷰 사용 권한 쿼리tableau:permissions:read뷰에 대한 사용 권한 목록을 가져옵니다.
통합 문서 사용 권한 쿼리tableau:permissions:read통합 문서에 대한 사용 권한 목록을 가져옵니다.
(사용 권한 메서드)tableau:permissions:*사용 권한 추가, 쿼리, 업데이트 및 삭제 동작을 사용합니다.

사이트

  
사이트 만들기tableau:sites:createTableau Server에 사이트를 만듭니다.
사이트 삭제tableau:sites:deleteTableau Server의 사이트를 삭제합니다.
최근에 본 사이트 가져오기tableau:content:read로그인한 사용자가 가장 최근에 만들거나 업데이트하거나 액세스한 뷰 및 통합 문서 세부 정보를 가져옵니다.
사이트 쿼리tableau:sites:readTableau Server의 모든 사이트를 나열합니다.
사이트의 뷰 쿼리tableau:content:read사이트의 모든 뷰를 나열합니다.
사이트 업데이트tableau:sites:update사이트를 업데이트합니다.
(사이트 메서드)tableau:sites:*사이트 만들기, 쿼리, 업데이트 및 삭제 동작을 사용합니다.

범위 문제 해결

401001 - 로그인 오류

오류 401001이 발생하면 로그인 응답 본문에 연결된 앱 관련 오류 코드 16, 10084 또는 10085 중 하나가 더 추가됩니다.

예를 들어 다음 응답 본문에서 "10084"는 REST API 권한 부여를 위해 JWT를 사용하여 Tableau Server에 로그인하는 문제를 해결하는 데 사용할 수 있는 연결된 앱 오류 코드입니다.

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

문제를 해결하려면 해당 오류 코드 및 잠재적 원인에 대한 설명을 참조하십시오.

  • 16: 사용자를 찾을 수 없음 - 이 오류는 잘못된 "sub"(사용자 이름)이 지정되었기 때문에 발생할 수 있습니다.

  • 10084: 액세스 토큰을 구문 분석할 수 없음 - 이 오류는 다음과 같은 이유로 발생할 수 있습니다.

    • JWT가 잘못되었거나 예기치 않은 문제가 발생했습니다.
    • 잘못된 "aud"(audience)가 지정되었습니다.
    • 직접 신뢰를 위한 암호 서명에 문제가 있었습니다.
  • 10085: 클라이언트 ID의 서명을 확인하기 위해 암호를 가져올 수 없음 - 이 오류는 다음과 같은 이유로 발생할 수 있습니다.

    • "iss"에 잘못된 클라이언트 ID가 지정됨
    • 직접 신뢰를 위한 "kid"(암호 ID)가 잘못 지정됨
    • EAS에 대한 키를 JWKSource에서 가져올 수 없습니다.

401002 - 무단 액세스 오류

오류 401002가 발생하고 요청을 수행할 수 있는 적절한 사용 권한이 있음을 확인한 경우 JWT에 포함된 범위가 정확하고 수행하려는 요청과 일치하는지 확인하십시오. 끝점 및 지원되는 범위 목록은 위의 JWT 권한 부여를 지원하는 REST API 메서드 섹션을 참조하십시오.

피드백을 제공해 주셔서 감사합니다!