# AWS WA Tool のレンズ形式の仕様
レンズは特定の JSON 形式を使用して定義されます。カスタムレンズの作成を開始する際に、テンプレートの JSON ファイルをダウンロードするオプションがあります。このファイルで柱、質問、ベストプラクティス、および改善計画の基本構造を定義するため、これをカスタムレンズの基礎として使用できます。
## [Lens] (レンズ) セクション
このセクションでは、カスタムレンズ自体の属性を定義します。これには、名前と説明が含まれます。
+ `schemaVersion`: 使用するカスタムレンズスキーマのバージョン。テンプレートによって設定されます。変更しないでください。
+ `name`: レンズの名前。名前は最大 128 文字です。
+ `description`: レンズの説明文。このテキストは、ワークロードの作成時に追加するレンズを選択するとき、または後で既存のワークロードに適用するレンズを選択するときに表示されます。説明は最大 2,048 文字です。
```
"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.",
```
## [Pillars] (柱) セクション
このセクションでは、カスタムレンズに関連する柱を定義します。質問を、AWS Well-Architected フレームワークの柱にマッピングしたり、独自の柱を定義したりできます (あるいはその両方)。
カスタムレンズには最大 10 の柱を定義できます。
+ `id`: 柱の ID。ID は 3 ～ 128 文字で、英数字とアンダースコア (「\$1」) のみ使用できます。柱に使用される ID は一意である必要があります。
質問をフレームワークの柱にマッピングするときは、次の ID を使用します。
+ `operationalExcellence`
+ `security`
+ `reliability`
+ `performance`
+ `costOptimization`
+ `sustainability`
+ `name`: 柱の名前。名前は最大 128 文字です。
```
"pillars": [
{
"id": "company_Privacy",
"name": "Privacy Excellence",
.
.
.
},
{
"id": "company_Security",
"name": "Security",
.
.
.
}
]
```
## [Questions] (質問) セクション
このセクションでは、柱に関連する質問を定義します。
カスタムレンズの柱には最大 20 の質問を定義できます。
+ `id`: 質問の ID。ID は 3～128 文字で、英数字とアンダースコア (「\$1」) のみ使用できます。質問に使用される ID は一意である必要があります。
+ `title`: 質問のタイトル。タイトルは最大 128 文字です。
+ `description`: 質問について詳しく説明します。説明は最大 2,048 文字です。
+ `helpfulResource displayText`: オプション。質問に関する有用な情報を提供するテキスト。テキストは最大 2,048 文字です。`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"
},
.
.
.
}
]
```
## [Choice] (選択肢) セクション
このセクションでは、質問に関連付けられている選択肢を定義します。
カスタムレンズの質問には最大 15 の選択肢を定義できます。
+ `id`: 選択肢の ID。ID は 3～128 文字で、英数字とアンダースコア (「\$1」) のみ使用できます。質問の選択肢ごとに固有の ID を指定する必要があります。サフィックスが `_no` の選択肢を追加すると、質問では `None of these` の選択肢として扱われます。
+ `title`: 選択肢のタイトル。タイトルは最大 128 文字です。
+ `helpfulResource displayText`: オプション。選択肢に関する有用な情報を提供するテキスト。テキストは最大 2,048 文字です。`helpfulResource url` を指定する場合は必ず含めます。
+ `helpfulResource url`: オプション。選択肢をより詳細に説明する URL リソース。URL は、`http://` または `https://` で始まる必要があります。
+ `improvementPlan displayText`: 選択肢の改善方法を説明するテキスト。テキストは最大 2,048 文字です。`None of these` の選択肢を除き、各選択肢には `improvementPlan` が必要です。
+ `improvementPlan url`: オプション。改善に役立つ URL リソース。URL は、`http://` または `https://` で始まる必要があります。
+ `additionalResources type`: オプション。追加リソースのタイプ。この値は `HELPFUL_RESOURCE` または `IMPROVEMENT_PLAN` となります。
+ `additionalResources content`: オプション。追加リソースに対して、`displayText` および `url` の値を指定します。選択肢には、役立つ追加リソースを最大 5 つと、追加の改善計画項目を 5 つまで指定できます。
+ `displayText`: オプション。役に立つリソースまたは改善計画を説明するテキスト。テキストは最大 2,048 文字です。`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"
}
}
```
## [Risk Rules] (リスクルール) セクション
このセクションでは、選択した選択肢がリスクレベルを決定する方法を定義します。
質問ごとに最大 3 つのリスクルールを定義できます (リスクレベルごとに 1 つ)。
+ `condition`: 質問のリスクレベルに対応する選択肢のブール式、または `default`。
各質問には、`default` リスクルールが必要です。
+ `risk`: 条件に関連するリスクを示します。有効な値は、`HIGH_RISK`、`MEDIUM_RISK`、`NO_RISK` です。
リスクルールの順序は重要です。`true` に評価された最初の `condition` によって、その質問のリスクが設定されます。リスクルールを実装する一般的なパターンは、まずリスクが最も低い (そして一般的に最も詳細な) ルールから実装し、最後にリスクが最も高い (および最も限定的でない) ルールを実装することです。
例:
```
"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"
}
]
```
質問に 3 つの選択肢がある場合 (`choice_1`、`choice_2`、`choice_3`) の場合、これらのリスクルールは次のように動作します。
+ 3 つの選択肢がすべて選択されている場合、リスクなし。
+ `choice_1` または `choice_2` のいずれかが選択され、**かつ** `choice_3` が選択された場合、中リスク。
+ `choice_1` が選択**されず**、`choice_3` が選択された場合も中リスクとなります。
+ 上記の条件のいずれにも当てはまらない場合、高リスク。