# AWS WA Tool의 렌즈 형식 사양
렌즈는 특정 JSON 형식을 사용하여 정의됩니다. 사용자 지정 렌즈를 생성하기 시작하면 템플릿 JSON 파일을 다운로드할 수 있습니다. 이 파일은 원칙의 기본 구조, 질문, 모범 사례, 개선 계획을 정의하므로 사용자 지정 렌즈의 기반으로 사용할 수 있습니다.
## 렌즈 섹션
이 섹션에서는 사용자 지정 렌즈 자체의 속성을 정의합니다. 다음은 속성의 이름과 설명입니다.
+ `schemaVersion`: 사용할 사용자 지정 렌즈 스키마의 버전입니다. 템플릿에 의해 설정되므로 변경하지 마세요.
+ `name`: 렌즈의 이름입니다. 이름은 최대 128자까지 지정할 수 있습니다.
+ `description`: 렌즈에 대한 텍스트 설명입니다. 이 텍스트는 워크로드 생성 중에 추가할 렌즈를 선택하거나 나중에 기존 워크로드에 적용할 렌즈를 선택할 때 표시됩니다. 설명은 최대 2048자까지 작성할 수 있습니다.
```
"schemaVersion": "2021-11-01",
"name": "Company Policy ABC",
"description": "This lens provides a set of specific questions to assess compliance with company policy ABC-2021 as revised on 2021/09/01.",
```
## 원칙 섹션
이 섹션에서는 사용자 지정 렌즈와 관련된 원칙을 정의합니다. 질문을 AWS Well-Architected Framework의 원칙에 매핑하거나, 자체 원칙을 정의하거나, 두 작업을 모두 수행할 수 있습니다.
사용자 지정 렌즈 하나에는 최대 10개의 원칙을 정의할 수 있습니다.
+ `id`: 원칙의 ID입니다. ID에는 3\$1128자까지 사용 가능하며 영숫자 및 밑줄('\$1') 문자만 포함할 수 있습니다. 원칙에 사용되는 ID는 고유해야 합니다.
질문을 Framework의 원칙에 매핑할 때는 다음 ID를 사용하세요.
+ `operationalExcellence`
+ `security`
+ `reliability`
+ `performance`
+ `costOptimization`
+ `sustainability`
+ `name`: 원칙의 이름입니다. 이름은 최대 128자까지 지정할 수 있습니다.
```
"pillars": [
{
"id": "company_Privacy",
"name": "Privacy Excellence",
.
.
.
},
{
"id": "company_Security",
"name": "Security",
.
.
.
}
]
```
## 질문 섹션
이 섹션에서는 원칙과 관련된 질문을 정의합니다.
사용자 지정 렌즈에서는 원칙에 최대 20개의 질문을 정의할 수 있습니다.
+ `id`: 질문의 ID입니다. ID에는 3\$1128자까지 사용 가능하며 영숫자 및 밑줄('\$1') 문자만 포함할 수 있습니다. 질문에 사용되는 ID는 고유해야 합니다.
+ `title`: 질문의 제목입니다. 제목은 최대 128자까지 지정할 수 있습니다.
+ `description`: 질문을 더 자세히 설명합니다. 설명은 최대 2048자까지 작성할 수 있습니다.
+ `helpfulResource displayText`: 선택 사항입니다. 질문에 대한 유용한 정보를 제공하는 텍스트입니다. 텍스트는 최대 2048자까지 작성할 수 있습니다. `helpfulResource url`을 지정하는 경우 이 텍스트도 지정해야 합니다.
+ `helpfulResource url`: 선택 사항입니다. 질문을 더 자세히 설명하는 URL 리소스입니다. URL은 `http://` 또는 `https://`로 시작해야 합니다.
**참고**
사용자 지정 렌즈 워크로드를 Jira와 동기화할 때 질문에는 질문의 "id"와 "title"이 모두 표시됩니다.
Jira 티켓에 사용된 형식은 `[ QuestionID ] QuestionTitle`입니다.
```
"questions": [
{
"id": "privacy01",
"title": "How do you ensure HR conversations are private?",
"description": "Career and benefits discussions should occur on secure channels only and be audited regularly for compliance.",
"helpfulResource": {
"displayText": "This is helpful text for the first question",
"url": "https://example.com/poptquest01_help.html"
},
.
.
.
},
{
"id": "privacy02",
"title": "Is your team following the company privacy policy?",
"description": "Our company requires customers to opt-in to data use and does not disclose customer data to third parties either individually or in aggregate.",
"helpfulResource": {
"displayText": "This is helpful text for the second question",
"url": "https://example.com/poptquest02_help.html"
},
.
.
.
}
]
```
## 선택 항목 섹션
이 섹션에서는 질문과 관련된 선택 항목을 정의합니다.
사용자 지정 렌즈에서는 질문에 최대 15개의 선택 항목을 정의할 수 있습니다.
+ `id`: 선택 항목의 ID입니다. ID에는 3\$1128자까지 사용 가능하며 영숫자 및 밑줄('\$1') 문자만 포함할 수 있습니다. 질문의 각 선택 항목에 대해 고유한 ID를 지정해야 합니다. 접미사가 `_no`인 선택 항목을 추가하면 질문에 대한 `None of these` 선택 항목으로 작동합니다.
+ `title`: 선택 항목의 제목입니다. 제목은 최대 128자까지 지정할 수 있습니다.
+ `helpfulResource displayText`: 선택 사항입니다. 선택 항목에 대한 유용한 정보를 제공하는 텍스트입니다. 텍스트는 최대 2048자까지 작성할 수 있습니다. `helpfulResource url`이 지정된 경우 텍스트를 포함해야 합니다.
+ `helpfulResource url`: 선택 사항입니다. 선택 항목을 더 자세히 설명하는 URL 리소스입니다. URL은 `http://` 또는 `https://`로 시작해야 합니다.
+ `improvementPlan displayText`: 선택 항목을 개선할 수 있는 방법을 설명하는 텍스트입니다. 텍스트는 최대 2048자까지 작성할 수 있습니다. `None of these` 선택 항목을 제외한 각 선택 항목에는 `improvementPlan`이 필요합니다.
+ `improvementPlan url`: 선택 사항입니다. 개선에 도움이 될 수 있는 URL 리소스입니다. URL은 `http://` 또는 `https://`로 시작해야 합니다.
+ `additionalResources type`: 선택 사항입니다. 추가 리소스 유형입니다. 이때 값은 `HELPFUL_RESOURCE` 또는 `IMPROVEMENT_PLAN`이 될 수 있습니다.
+ `additionalResources content`: 선택 사항입니다. 추가 리소스의 `displayText` 및 `url` 값을 지정합니다. 선택 항목에 최대 5개의 유용한 추가 리소스와 최대 5개의 추가 개선 계획 항목을 지정할 수 있습니다.
+ `displayText`: 선택 사항입니다. 유용한 리소스 또는 개선 계획을 설명하는 텍스트입니다. 텍스트는 최대 2048자까지 작성할 수 있습니다. `url`이 지정된 경우 텍스트를 포함해야 합니다.
+ `url`: 선택 사항입니다. 유용한 리소스 또는 개선 계획을 위한 URL 리소스입니다. URL은 `http://` 또는 `https://`로 시작해야 합니다.
**참고**
사용자 지정 렌즈 워크로드를 Jira와 동기화할 때 선택 항목에는 질문 및 선택 항목의 "id"와 선택 항목의 "title"이 표시됩니다.
사용된 형식은 `[ QuestionID | ChoiceID ] ChoiceTitle`입니다.
```
"choices": [
{
"id": "choice_1",
"title": "Option 1",
"helpfulResource": {
"displayText": "This is helpful text for the first choice",
"url": "https://example.com/popt01_help.html"
},
"improvementPlan": {
"displayText": "This is text that will be shown for improvement of this choice.",
"url": "https://example.com/popt01_iplan.html"
}
},
{
"id": "choice_2",
"title": "Option 2",
"helpfulResource": {
"displayText": "This is helpful text for the second choice",
"url": "https://example.com/hr_manual_CORP_1.pdf"
},
"improvementPlan": {
"displayText": "This is text that will be shown for improvement of this choice.",
"url": "https://example.com/popt02_iplan_01.html"
},
"additionalResources":[
{
"type": "HELPFUL_RESOURCE",
"content": [
{
"displayText": "This is the second set of helpful text for this choice.",
"url": "https://example.com/hr_manual_country.html"
},
{
"displayText": "This is the third set of helpful text for this choice.",
"url": "https://example.com/hr_manual_city.html"
}
]
},
{
"type": "IMPROVEMENT_PLAN",
"content": [
{
"displayText": "This is additional text that will be shown for improvement of this choice.",
"url": "https://example.com/popt02_iplan_02.html"
},
{
"displayText": "This is the third piece of improvement plan text.",
"url": "https://example.com/popt02_iplan_03.html"
}
{
"displayText": "This is the fourth piece of improvement plan text.",
"url": "https://example.com/popt02_iplan_04.html"
}
]
}
]
},
{
"id": "option_no",
"title": "None of these",
"helpfulResource": {
"displayText": "Choose this if your workload does not follow these best practices.",
"url": "https://example.com/popt02_iplan_none.html"
}
}
```
## 위험 규칙 섹션
이 섹션에서는 선택한 선택 항목이 위험 수준을 결정하는 방법을 정의합니다.
각 위험 수준에 하나씩, 질문당 최대 3개의 위험 규칙을 정의할 수 있습니다.
+ `condition`: 질문의 위험 수준에 매핑되는 선택 항목의 부울 표현식으로, 해당 사항이 없는 경우 `default` 값이 지정됩니다.
각 질문에는 `default` 위험 규칙이 있어야 합니다.
+ `risk`: 조건과 관련된 위험을 나타냅니다. 유효한 값은 `HIGH_RISK`, `MEDIUM_RISK`, `NO_RISK`입니다.
위험 규칙의 순서는 중요합니다. 첫 번째 `condition`은 `true`로 평가되며 질문에 대한 위험 수준을 설정합니다. 위험 규칙을 구현하는 일반적인 패턴은 위험이 가장 적은(일반적으로 가장 세분화된) 규칙에서 시작하여 가장 위험한(가장 구체적이지 않은) 규칙 순서로 적용하는 것입니다.
예시:
```
"riskRules": [
{
"condition": "choice_1 && choice_2 && choice_3",
"risk": "NO_RISK"
},
{
"condition": "((choice_1 || choice_2) && choice_3) || (!choice_1 && choice_3)",
"risk": "MEDIUM_RISK"
},
{
"condition": "default",
"risk": "HIGH_RISK"
}
]
```
질문에 세 가지 선택 항목(`choice_1`,`choice_2`, `choice_3`)이 있는 경우 이러한 위험 규칙의 결과는 다음과 같습니다.
+ 세 가지 선택 항목을 모두 선택해도 위험은 없습니다.
+ `choice_1` 또는 `choice_2` 중 하나가 선택된 **상태에서** `choice_3`이 선택된 경우 위험 수준은 중간입니다.
+ `choice_1`이 선택되지 **않은** 상태에서 `choice_3`이 선택된 경우 역시 위험 수준이 중간입니다.
+ 위 조건 중 어느 것에도 해당하지 않으면 높은 위험입니다.