Windows 기반 Tableau Server 도움말

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 메서드를 사용할 수 있습니다. Tableau Server 2023.3부터 메타데이터 API(링크가 새 창에서 열림)와 함께 사용할 자격 증명 토큰을 생성하는 데 사용되는 JWT에서 이 범위를 지정합니다.

  참고: 사용자 및 그룹과 같은 관리 동작에 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 범주에서 가져오기/나열, 추가, 삭제, 업데이트 동작을 사용할 수 있습니다.
  • tableau:tasks:* 와일드카드 범위를 사용하면 추출 및 구독 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. 다음 방법 중 하나를 사용하여 연결된 앱 만들기
   • 직접 신뢰를 사용하여 연결된 앱 구성
   • OAuth 2.0 신뢰를 사용하여 연결된 앱 구성
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(링크가 새 창에서 열림)에 대해 가질 수 있는 액세스 권한 및 메서드를 정의할 수 있습니다.

참고:

• 아래 표에 나열되지 않은 다른 REST API 기능의 경우 다른 권한 부여 메커니즘을 사용하여 메서드에 액세스할 수 있습니다. 자세한 내용은 Tableau REST API 설명서에서 인증 메서드(링크가 새 창에서 열림)를 참조하십시오.
• 로그인(링크가 새 창에서 열림) 및 로그아웃(링크가 새 창에서 열림) 방법 모두는 JWT 권한 부여로 지원되지만 Tableau Server 2023.3부터는 사용할 범위가 필요하지 않습니다.
• Embedding API v3으로 지원되는 범위는 다음 중 하나를 참조하십시오.
  • 직접 신뢰를 사용하여 연결된 앱 구성
  • OAuth 2.0 신뢰를 사용하여 연결된 앱 구성

와일드카드(*) 범위

와일드카드 범위는 특정 동작 대신 와일드카드 문자(*)를 사용하여 특정 REST API 범주 내에서 지원되는 여러 동작을 사용하도록 설정합니다. 여기에는 다음이 포함됩니다.

교차 범주 범위

교차 범주 범위를 사용하면 여러 REST API 범주에 걸쳐 지원되는 여러 동작을 사용하도록 설정할 수 있습니다. 여기에는 다음이 포함됩니다.

개별 범위

범위 문제 해결

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 메서드 섹션을 참조하십시오.