기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# Amazon Quick Sight 임베디드 대시보드 및 시각적 객체의 모양과 느낌 사용자 지정
<a name="embedding-runtime-theming"></a>

Amazon Quick Sight 임베딩 SDK(버전 2.5.0 이상)를 사용하여 런타임 시 임베디드 Amazon Quick Sight 대시보드 및 시각적 객체의 테마를 변경할 수 있습니다. 런타임 테마를 사용하면 서비스형 소프트웨어(SaaS) 애플리케이션을 Amazon Quick Sight 임베디드 자산과 더 쉽게 통합할 수 있습니다. 런타임 테마를 사용하면 임베디드 콘텐츠의 테마를 Amazon Quick Sight 자산이 임베디드되는 상위 애플리케이션의 테마와 동기화할 수 있습니다. 런타임 테마 지정을 사용하여 독자에 대한 사용자 지정 옵션을 추가할 수도 있습니다. 테마 지정 변경 사항은 초기화 시 또는 임베디드 대시보드 또는 시각적 객체의 수명 기간 동안 임베디드 자산에 적용할 수 있습니다.

테마에 대한 자세한 정보는 [Amazon Quick Sight에서 테마 사용](themes-in-quicksight.md) 섹션을 참조하세요. Amazon Quick Sight 임베딩 SDK 사용에 대한 자세한 내용은 GitHub의 [amazon-quicksight-embedding-sdk](https://github.com/awslabs/amazon-quicksight-embedding-sdk)를 참조하세요.

**사전 조건**

시작하기 전에 다음 사전 조건을 충족하는지 확인합니다.
+ Amazon Quick Sight 임베딩 SDK 버전 2.5.0 이상을 사용하고 있습니다.
+ 작업하려는 테마에 액세스할 수 있는 권한입니다. Amazon Quick Sight의 테마에 권한을 부여하려면 `UpdateThemePermissions` API를 호출하거나 Amazon Quick Sight 콘솔의 분석 편집기에서 테마 옆에 있는 **공유** 아이콘을 사용합니다.

## 용어 및 개념
<a name="runtime-theming-terminology"></a>

다음 용어는 임베디드 런타임 지정을 작업할 때 유용할 수 있습니다.
+ *테마* - 콘텐츠 표시 방식을 변경하는 여러 분석 및 대시보드에 적용할 수 있는 설정 모음입니다.
+ *ThemeConfiguration* – 이 구성 객체에는 테마의 모든 표시 속성이 포함됩니다.
+ *테마 재정의* - 콘텐츠 표시 방법의 일부 또는 모든 측면을 재정의하기 위해 활성 테마에 적용되는 `ThemeConfiguration` 객체입니다.
+ *테마 ARN * - Amazon Quick Sight 테마를 식별하는 Amazon 리소스 이름(ARN)입니다. 다음은 사용자 지정 테마 ARN의 예제입니다.

  `arn:aws:quicksight:region:account-id:theme/theme-id`

  Amazon Quick Sight에서 제공하는 스타터 테마에는 테마 ARN에 리전이 없습니다. 다음은 시작 테마 ARN의 예제입니다.

  `arn:aws:quicksight::aws:theme/CLASSIC`

## 설정
<a name="runtime-theming-setup"></a>

런타임 테마 지정 작업을 시작할 수 있도록 다음 정보가 준비되어 있는지 확인합니다.
+ 사용하려는 테마의 테마 ARN입니다. 기존 테마를 선택하거나 새로 만들 수 있습니다. Amazon Quick Sight 계정의 모든 테마 및 테마 ARNs 목록을 가져오려면 [ListThemes](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_ListThemes.html) API 작업을 호출합니다. 사전 설정된 Amazon Quick Sight 테마에 대한 자세한 내용은 섹션을 참조하세요[Amazon Quick APIs를 사용한 Amazon Quick 분석의 기본 테마 설정](customizing-quicksight-default-theme.md).
+ 등록된 사용자 임베딩을 사용하는 경우 사용자가 사용하려는 테마에 액세스할 수 있는지 확인합니다.

  익명 사용자 임베딩을 사용하는 경우 테마 ARN 목록을 `GenerateEmbedUrlForAnonymousUser` API의 `AuthorizedResourceArns` 파라미터에 전달합니다. 익명 사용자에게는 `AuthorizedResourceArns` 파라미터에 나열된 모든 테마에 대한 액세스 권한이 부여됩니다.

## SDK 메서드 인터페이스
<a name="runtime-theming-sdk-interface"></a>

**Setter 메서드**

다음 테이블에서는 개발자가 테마 지정에 사용할 수 있는 다양한 setter 메서드를 설명합니다.


| 방법 | 설명 | 
| --- | --- | 
|  `setTheme(themeArn: string)`  |  대시보드 또는 시각적 객체의 활성 테마를 다른 테마로 바꿉니다. 적용된 경우 테마 재정의가 제거됩니다. 테마에 액세스할 수 없거나 테마가 없는 경우 오류가 반환됩니다.  | 
|  `setThemeOverride(themeOverride: ThemeConfiguration)`  |  현재 활성 테마를 재정의하도록 동적 `ThemeConfiguration`을 설정합니다. 이는 이전에 설정한 테마 재정의를 대체합니다. 새 `ThemeConfiguration`에 제공되지 않은 모든 값은 현재 활성 테마의 값으로 기본 설정됩니다. 제공한 `ThemeConfiguration`이 유효하지 않은 경우 오류가 반환됩니다.  | 

## 테마로 임베디드 콘텐츠 초기화
<a name="runtime-theming-sdk-initialize"></a>

기본값이 아닌 테마로 임베디드 대시보드 또는 시각적 객체를 초기화하려면 `DashboardContentOptions` 또는 `VisualContentOptions` 파라미터에 `themeOptions` 객체를 정의하고 `themeOptions` 내에 `themeArn` 속성을 원하는 테마 ARN으로 설정합니다.

다음 예제에서는 `MIDNIGHT` 테마로 임베디드 대시보드를 초기화합니다.

```
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';

const embeddingContext = await createEmbeddingContext();

const {
    embedDashboard,
} = embeddingContext;

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#experience-container',
};
const contentOptions = {
    themeOptions: {
        themeArn: "arn:aws:quicksight::aws:theme/MIDNIGHT"
    }
};

// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);
```

## 테마 재정의로 임베디드 콘텐츠 초기화
<a name="runtime-theming-runtime-initialize-override"></a>

개발자는 테마 재정의를 사용하여 런타임 시 임베디드 대시보드 또는 시각적 객체의 테마를 정의할 수 있습니다. 이렇게 하면 Amazon Quick Sight 내에서 테마를 사전 구성할 필요 없이 대시보드 또는 시각적 객체가 타사 애플리케이션에서 테마를 상속할 수 있습니다. 테마 재정의로 임베디드 대시보드 또는 시각적 객체를 초기화하려면 `DashboardContentOptions` 또는 `VisualContentOptions` 파라미터에서 `themeOptions` 내에 `themeOverride` 속성을 설정합니다. 다음 예제에서는 대시보드 테마의 글꼴을 기본 글꼴에서 `Amazon Ember`로 재정의합니다.

```
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';

const embeddingContext = await createEmbeddingContext();

const {
    embedDashboard,
} = embeddingContext;

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#experience-container',
};
const contentOptions = {
    themeOptions: {
        "themeOverride":{"Typography":{"FontFamilies":[{"FontFamily":"Comic Neue"}]}}
    }
};

// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);
```

## 사전 로드된 테마로 임베디드 콘텐츠 초기화
<a name="runtime-theming-runtime-initialize-preloaded"></a>

개발자는 초기화 시 사전 로드되도록 대시보드 테마 세트를 구성할 수 있습니다. 이는 어두운 모드와 밝은 모드와 같은 다양한 뷰 간에 빠르게 전환할 때 가장 유용합니다. 임베디드 대시보드 또는 시각적 객체는 최대 5개의 사전 로드된 테마로 초기화할 수 있습니다. 사전 로드된 테마를 사용하려면 `DashboardContentOptions` 또는 `VisualContentOptions`에서 `preloadThemes` 속성을 최대 5개의 `themeArns` 배열로 설정합니다. 다음 예제에서는 `Midnight` 및 `Rainier` 시작 테마를 대시보드에 사전 로드합니다.

```
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';

const embeddingContext = await createEmbeddingContext();

const {
    embedDashboard,
} = embeddingContext;

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#experience-container',
};
const contentOptions = {
    themeOptions: {
        "preloadThemes": ["arn:aws:quicksight::aws:theme/RAINIER", "arn:aws:quicksight::aws:theme/MIDNIGHT"]
    }
};

// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);
```