Amazon CodeCatalyst 不再向新客戶開放。現有客戶可以繼續正常使用該服務。如需詳細資訊，請參閱[如何從 CodeCatalyst 遷移](migration.md)。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 開發符合專案需求的自訂藍圖
<a name="develop-bp"></a>

在發佈自訂藍圖之前，您可以開發藍圖以符合特定需求。您可以在預覽時建立專案，以開發自訂藍圖並測試藍圖。您可以開發自訂藍圖來包含專案元件，例如特定的原始碼、帳戶連線、工作流程、問題，或可在 CodeCatalyst 中建立的任何其他元件。

**重要**  
如果您想要使用外部來源的藍圖套件，請考慮這些套件可能帶來的風險。您需為您新增至空間的自訂藍圖及其產生的程式碼負責。

**重要**  
若要在 CodeCatalyst 空間中開發自訂藍圖，您必須使用空間中具有 **Space 管理員**或 **Power 使用者**角色的帳戶登入。

**開發或更新自訂藍圖**

1. 繼續開發環境。如需詳細資訊，請參閱[恢復開發環境](devenvironment-resume.md)。

   如果您沒有開發環境，您必須先建立一個。如需詳細資訊，請參閱[建立開發環境](devenvironment-create.md)。

1. 在開發環境中開啟工作終端機。

1. 如果您在建立藍圖時選擇加入發行工作流程，則會自動發佈最新的藍圖版本。提取變更，以確保`package.json`檔案具有遞增版本。使用下列命令：

   ```
   git pull
   ```

1. 在 `src/blueprint.ts`檔案中，編輯自訂藍圖的選項。`Options` 界面由 CodeCatalyst 精靈動態解譯，以產生選擇使用者介面 (UI)。您可以透過新增元件和支援的標籤來開發自訂藍圖。如需詳細資訊，請參閱 [使用前端精靈修改藍圖功能](wizard-bp.md)、[將環境元件新增至藍圖](comp-env-bp.md)、[將區域元件新增至藍圖](region-comp-bp.md)、[將儲存庫和原始程式碼元件新增至藍圖](comp-repo-source-bp.md)、[將工作流程元件新增至藍圖](comp-workflow-bp.md)、[將開發環境元件新增至藍圖](comp-dev-env-bp.md)。

   您也可以檢視藍圖 SDK 和範例藍圖，以便在開發自訂藍圖時獲得其他支援。如需詳細資訊，請參閱[開放原始碼 GitHub 儲存庫](https://github.com/aws/codecatalyst-blueprints)。

自訂藍圖成功合成後，提供預覽套件。專案套件代表專案中的原始碼、組態和資源，且 CodeCatalyst 部署 API 操作會使用它來部署至專案。如果您想要繼續開發自訂藍圖，請重新執行藍圖合成程序。如需詳細資訊，請參閱[自訂藍圖概念](custom-bp-concepts.md)。

# 使用前端精靈修改藍圖功能
<a name="wizard-bp"></a>

CodeCatalyst 上的藍圖選擇精靈是由 `blueprint.ts` 檔案中的`Options`界面自動產生。前端精靈支援`Options`使用 [JSDOC 樣式註解和標籤的藍圖修改和](https://jsdoc.app/about-getting-started.html)功能。您可以使用 JSDOC 樣式註解和標籤來執行任務。例如，您可以選取選項上方顯示的文字、啟用輸入驗證等功能，或使選項可折疊。精靈的運作方式是解譯從`Options`界面的 TypeScript 類型產生的抽象語法樹 (AST)。精靈會自動將自己設定為盡可能最佳描述的類型。不支援所有類型。其他支援的類型包括區域選擇器和環境選擇器。

以下是使用 JSDOC 註解和標籤搭配藍圖 的精靈範例`Options`：

```
export interface Options {
  /**
   * What do you want to call your new blueprint?
   * @validationRegex /^[a-zA-Z0-9_]+$/
   * @validationMessage Must contain only upper and lowercase letters, numbers and underscores
   */
  blueprintName: string;

  /**
   * Add a description for your new blueprint.
   */
   description?: string;

   /**
    * Tags for your Blueprint:
    * @collapsed true
    */
  tags?: string[];
}
```

根據`camelCase`預設，`Options`界面的每個選項的顯示名稱會出現在 中。JSDOC 樣式註解中的純文字會在精靈中的 選項上方顯示為文字。

**Topics**
+ [支援的標籤](#supported-tags-bp)
+ [支援的 TypeScript 類型](#supported-typescript-bp)
+ [在合成期間與使用者通訊](#communication-mid-synthesis)

## 支援的標籤
<a name="supported-tags-bp"></a>

前端精靈`Options`中的自訂藍圖支援下列 JSDOC 標籤。

### @inlinePolicy ./path/to/policy/file.json
<a name="inline-policy-tag"></a>
+ **需要** - 選項為類型 `Role`。
+ **用量** - 可讓您傳達角色所需的內嵌政策。`policy.json` 路徑預期位於原始程式碼下。當您需要角色的自訂政策時，請使用此標籤。
+ **相依性** - `blueprint-cli 0.1.12` 及更高版本
+ **範例** - `@inlinePolicy ./deployment-policy.json`

```
environment: EnvironmentDefinition{
    awsAccountConnection: AccountConnection{
      /**
       * @inlinePolicy ./path/to/deployment-policy.json
       */
      cdkRole: Role[];
    };
   };
```

### @trustPolicy ./path/to/policy/file.json
<a name="trust-policy-tag"></a>
+ **需要** - 選項為類型 `Role`。
+ **用量** - 可讓您傳達角色所需的信任政策。`policy.json` 路徑預期位於原始程式碼下。當您需要角色的自訂政策時，請使用此標籤。
+ **相依性** - `blueprint-cli 0.1.12` 及更高版本
+ **範例** - `@trustPolicy ./trust-policy.json`

```
environment: EnvironmentDefinition{
    awsAccountConnection: AccountConnection{
      /**
       * @trustPolicy ./path/to/trust-policy.json
       */
      cdkRole: Role[];
    };
   };
```

### @validationRegex Regex 表達式
<a name="validation-regex-tag"></a>
+ **需要** - 選項為字串。
+ **用量** - 使用指定的 regex 表達式對 選項執行輸入驗證，並顯示 `@validationMessage`。
+ **範例** - `@validationRegex /^[a-zA-Z0-9_]+$/`
+ **建議** - 與 搭配使用`@validationMessage`。驗證訊息預設為空白。

### @validationMessage 字串
<a name="validation-message-tag"></a>
+ **需要** - `@validationRegex`或其他錯誤才能檢閱用量。
+ **用量** - 顯示`@validation*`失敗時的驗證訊息。
+ **範例** - `@validationMessage Must contain only upper and lowercase letters, numbers, and underscores`。
+ **建議** - 與 搭配使用`@validationMessage`。驗證訊息預設為空白。

### @collapsed 布林值 （選用）
<a name="collapsed-boolean-tag"></a>
+ **需要** - 不適用
+ **用量** - 允許可折疊子選項的布林值。如果有折疊的註釋，則其預設值為 true。將 值設定為 會`@collapsed false`建立最初開啟的可摺疊區段。
+ **範例** - `@collapsed true`

### @displayName 字串
<a name="display-name-tag"></a>
+ **需要** - 不適用
+ **Usage** - 變更選項顯示名稱。允許顯示名稱使用 camelCase 以外的格式。
+ **範例** - `@displayName Blueprint Name`

### @displayName 字串
<a name="display-name-tag"></a>
+ **需要** - 不適用
+ **用量** - 變更選項顯示名稱。允許顯示名稱使用 [camelCase](https://en.wikipedia.org/wiki/Camel_case) 以外的格式。
+ **範例** - `@displayName Blueprint Name`

### @defaultEntropy 號碼
<a name="default-entropy-tag"></a>
+ **需要** - 選項為字串。
+ **用量** - 將指定長度的隨機英數字串附加到 選項。
+ **範例** - `@defaultEntropy 5`

### @placeholder 字串 （選用）
<a name="placeholder-tag"></a>
+ **需要** - 不適用
+ **用量** - 變更預設文字欄位預留位置。
+ **範例** - `@placeholder type project name here`

### @textArea 號碼 （選用）
<a name="text-area-tag"></a>
+ **需要** - 不適用
+ **用量** - 將字串輸入轉換為文字區域元件，以用於較大的文字區段。新增數字可定義列數。預設為五列。
+ **範例** - `@textArea 10`

### @hidden 布林值 （選用）
<a name="hidden-tag"></a>
+ **需要** - 不適用
+ **用量** - 除非驗證檢查失敗，否則隱藏使用者的檔案。預設值為 true。
+ **範例** - `@hidden`

### @button 布林值 （選用）
<a name="button-tag"></a>
+ **需要** - 不適用
+ **用量** - 註釋必須位於布林值屬性上。新增選擇時將合成為 true 的按鈕。不是切換。
+ **範例** - `buttonExample: boolean;`

  ```
  /**
    * @button
    */
  buttonExample: boolean;
  ```

### @showName 布林值 （選用）
<a name="show-name-tag"></a>
+ **需要** - 不適用
+ **用量** - 只能用於 帳戶連線類型。顯示隱藏的名稱輸入。預設為 `default_environment`。
+ **範例** - `@showName true`

  ```
  /**
    * @showName true
    */
  accountConnection: AccountConnection<{
      ...
  }>;
  ```

### @showEnvironmentType 布林值 （選用）
<a name="show-environment-tag"></a>
+ **需要** - 不適用
+ **用量** - 只能用於 帳戶連線類型。顯示隱藏的環境類型下拉式選單。所有連線預設為 `production`。選項為**非生產**或**生產**。
+ **範例** - `@showEnvironmentType true`

  ```
  /**
    * @showEnvironmentType true
    */
  accountConnection: AccountConnection<{
      ...
  }>;
  ```

### @forceDefault 布林值 （選用）
<a name="force-default-tag"></a>
+ **需要** - 不適用
+ **用量** - 使用藍圖作者提供的預設值，而不是使用者先前使用的值。
+ **範例** - `forceDeafultExample: any;`

  ```
  /**
    * @forceDefault
    */
  forceDeafultExample: any;
  ```

### @requires blueprintName
<a name="requires-tag"></a>
+ **需要** - 註釋`Options`界面。
+ **用量** - 警告使用者將指定的 新增至`blueprintName`專案，作為目前藍圖的需求。
+ **範例** - `@requires '@amazon-codecatalyst/blueprints.blueprint-builder'`

  ```
  /*
   * @requires '@amazon-codecatalyst/blueprints.blueprint-builder'
   */
  export interface Options extends ParentOptions {
  ...
  ```

### @filter regex
<a name="filter-regex-tag"></a>
+ **需要** - 註釋 `Selector`或 `MultiSelect` 界面。
+ **用量** - 篩選精靈中的下拉式清單，使其選項符合指定的 regex。
+ **範例** - `@filter /blueprintPackageName/`

  ```
   /**
       * @filter /myPackageName/
       */
      blueprintInstantiation?: Selector<BlueprintInstantiation>;
  ...
  ```

## 支援的 TypeScript 類型
<a name="supported-typescript-bp"></a>

前端精靈`Options`中的自訂藍圖支援下列 TypeScript 類型。

### Number
<a name="number-ts-tag"></a>
+ **需要** - 選項為類型 `number`。
+ **用量** - 產生數字輸入欄位。
+ **範例** - `age: number`

```
{
  age: number
  ...
}
```

### 字串
<a name="string-ts-tag"></a>
+ **需要** - 選項為類型 `string`。
+ **用量** - 產生字串輸入欄位。
+ **範例** - `name: string`

```
{
  age: string
  ...
}
```

### 字串清單
<a name="string-list-ts-tag"></a>
+ **需要** - 選項為類型 的陣列`string`。
+ **用量** - 產生字串清單輸入。
+ **範例** - `isProduction: boolean`

```
{
  isProduction: boolean
  ...
}
```

### Checkbox
<a name="checkbox-ts-tag"></a>
+ **需要** - 選項為 `boolean`。
+ **用量** - 產生核取方塊。
+ **範例** - `isProduction: boolean`

```
{
  isProduction: boolean
  ...
}
```

### 無線電
<a name="radio-ts-tag"></a>
+ **需要** - 選項為三個或更少字串的聯集。
+ **用量** - 產生選取的無線電。
**注意**  
有四個或更多項目時，此類型會轉譯為下拉式清單。
+ **範例** - `color: 'red' | 'blue' | 'green'`

```
{
  color: 'red' | 'blue' | 'green'
  ...
}
```

### 下拉式清單
<a name="dropdown-ts-tag"></a>
+ **需要** - 選項為四個或更多字串的聯集。
+ **用量** - 產生下拉式清單。
+ **範例** - `runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'`

```
{
  runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'
  ...
}
```

### 可擴展區段
<a name="expandable-ts-tag"></a>
+ **需要** - 選項為物件。
+ **用量** - 產生可擴展的區段。物件中的選項將巢狀在精靈的可擴展區段內。
+ **範例** - 

```
{
     expandableSectionTitle: {
         nestedString: string;
         nestedNumber: number;
     }
}
```

### 雙組
<a name="tuple-ts-tag"></a>
+ **需要** - 類型為 的選項`Tuple`。
+ **用量** - 產生鍵值付費輸入。
+ **範例** - `tuple: Tuple[string, string]>`

```
{
    tuple: Tuple[string, string]>;
    ...
}
```

### 組合清單
<a name="tuple-list-ts-tag"></a>
+ **需要** - 選項為類型 的陣列`Tuple`。
+ **用量** - 產生元組清單輸入。
+ **範例** - `tupleList: Tuple[string, string]>[]`

```
{
  tupleList: Tuple[string, string]>[];
  ...
}
```

### 選擇器
<a name="selector-ts-tag"></a>
+ **需要** - 類型為 的選項`Selector`。
+ **用量** - 產生套用至專案的來源儲存庫或藍圖下拉式清單。
+ **範例** - `sourceRepo: Selector<SourceRepository>`

```
{
    sourceRepo: Selector<SourceRepository>;
    sourceRepoOrAdd: Selector<SourceRepository | string>;
    blueprintInstantiation: Selector<BlueprintInstantiation>;
  ...
}
```

### 多選
<a name="multiselect-ts-tag"></a>
+ **需要** - 類型為 的選項`Selector`。
+ **用量** - 產生多選輸入。
+ **範例** - `multiselect: MultiSelect['A' | 'B' | 'C' | 'D' | 'E']>`

```
{
  multiselect: MultiSelect['A' | 'B' | 'C' | 'D' | 'E']>;
  ...
}
```

## 在合成期間與使用者通訊
<a name="communication-mid-synthesis"></a>

身為藍圖作者，您可以僅與驗證訊息以外的使用者進行通訊。例如，空間成員可能會檢視產生不清楚藍圖的選項組合。自訂藍圖支援透過叫用合成，將錯誤訊息傳回給使用者的能力。基本藍圖會實作預期出現明確錯誤訊息的`throwSynthesisError(...)`函數。您可以使用下列方式叫用訊息：

```
//blueprint.ts
this.throwSynthesisError({
   name: BlueprintSynthesisErrorTypes.BlueprintSynthesisError,
   message: 'hello from the blueprint! This is a custom error communicated to the user.'
})
```

# 產生輸入並重新轉譯前端精靈元素
<a name="comp-dynamic-input-bp"></a>

您可以使用 DynamicKVInput 產生精靈輸入，並為您的自訂藍圖動態建立前端精靈元素。

**Topics**
+ [建立開發環境](#dynamickvinput-bp)
+ [動態建立精靈元素](#create-wizard-elements-bp)

## 建立開發環境
<a name="dynamickvinput-bp"></a>

DynamicKVInput 類型可用來產生使用自訂 bluerpint 預設值的前端精靈輸入。若要檢視up-to-date結構描述，請參閱 [DynamicKVInput 定義](https://github.com/aws/codecatalyst-blueprints/blob/main/packages/blueprints/blueprint/src/ui-selectors/dynamic-kv-input.ts)。

下列範例示範如何使用 `Options`來塑造物件：

```
import { DynamicKVInput } from '@amazon-codecatalyst/blueprints.blueprint';

export interface Options extends ParentOptions {

  parameters: DynamicKVInput[];

}
```

下列範例示範如何設定具有數個屬性的預設參數：

```
{ 
"parameters": [
        {
            "key": "AWS_REGION",
            "value": "us-west-2",
            "displayType": "region",
            "possibleValues": [
                "us-west-1",
                "us-west-2",
                "us-east-1",
                "us-east-2"
            ],
            "displayName": "AWS Region",
            "description": "AWS Region to deploy the solution to."
        },
        {
            "key": "SchedulingActive",
            "value": "Yes",
            "displayType": "dropdown",
            "possibleValues": [
                "Yes",
                "No"
            ],
            "displayName": "Scheduling Active",
            "description": "Activate or deactivate scheduling."
        },
        {
            "key": "ScheduledServices",
            "value": "Both",
            "displayType": "dropdown",
            "possibleValues": [
                "EC2",
                "RDS",
                "Both"
            ],
            "displayName": "Scheduled Services",
            "description": "Services to schedule."
        },
        {
            "key": "ScheduleRdsClusters",
            "value": "No",
            "displayType": "dropdown",
            "possibleValues": [
                "Yes",
                "No"
            ],
            "displayName": "Schedule RDS Clusters",
            "description": "Enable scheduling of Aurora clusters for RDS service."
        },
        {
            "key": "CreateRdsSnapshot",
            "value": "No",
            "displayType": "dropdown",
            "possibleValues": [
                "Yes",
                "No"
            ],
            "displayName": "Create RDS Snapshot",
            "description": "Create snapshot before stopping RDS instances (does not apply to Aurora Clusters)."
        },
        {
            "key": "MemorySize",
            "value": "128",
            "displayType": "dropdown",
            "possibleValues": [
                "128",
                "384",
                "512",
                "640",
                "768",
                "896",
                "1024",
                "1152",
                "1280",
                "1408",
                "1536"
            ],
            "displayName": "Memory Size",
            "description": "Size of the Lambda function running the scheduler, increase size when processing large numbers of instances."
        },
        {
            "key": "UseCloudWatchMetrics",
            "value": "No",
            "displayType": "dropdown",
            "possibleValues": [
                "Yes",
                "No"
            ],
            "displayName": "Use CloudWatch Metrics",
            "description": "Collect instance scheduling data using CloudWatch metrics."
        },
        {
            "key": "LogRetentionDays",
            "value": "30",
            "displayType": "dropdown",
            "possibleValues": [
                "1",
                "3",
                "5",
                "7",
                "14",
                "30",
                "60",
                "90",
                "120",
                "150",
                "180",
                "365",
                "400",
                "545",
                "731",
                "1827",
                "3653"
            ],
            "displayName": "Log Retention Days",
            "description": "Retention days for scheduler logs."
        },
        {
            "key": "Trace",
            "value": "No",
            "displayType": "dropdown",
            "possibleValues": [
                "Yes",
                "No"
            ],
            "displayName": "Trace",
            "description": "Enable debug-level logging in CloudWatch logs."
        },
        {
            "key": "EnableSSMMaintenanceWindows",
            "value": "No",
            "displayType": "dropdown",
            "possibleValues": [
                "Yes",
                "No"
            ],
            "displayName": "Enable SSM Maintenance Windows",
            "description": "Enable the solution to load SSM Maintenance Windows, so that they can be used for EC2 instance Scheduling."
        },
        {
            "key": "DefaultTimezone",
            "value": "UTC",
            "displayType": "string",
            "displayName": "Default Timezone",
            "description": "Default timezone to use for scheduling."
        },
        {
            "key": "Regions",
            "value": "us-west-2",
            "displayType": "string",
            "displayName": "Regions",
            "description": "List of regions in which instances should be scheduled, leave blank for current region only."
        },
        {
            "key": "UsingAWSOrganizations",
            "value": "No",
            "displayType": "dropdown",
            "possibleValues": [
                "Yes",
                "No"
            ],
            "displayName": "Using AWS Organizations",
            "description": "Use AWS Organizations to automate spoke account registration."
        },
        {
            "key": "Principals",
            "displayType": "string",
			      "optional": false,
            "displayName": "Principals",
            "description": "(Required) If using AWS Organizations, provide the Organization ID. Eg. o-xxxxyyy. Else, provide a comma separated list of spoke account ids to schedule. Eg.: 1111111111, 2222222222 or {param: ssm-param-name}"
        },
        {
            "key": "Namespace",
            "value": "Default",
            "displayType": "string",
            "displayName": "Namespace",
            "description": "Provide unique identifier to differentiate between multiple solution deployments (No Spaces). Example: Dev"
        },
        {
            "key": "SchedulerFrequency",
            "value": 5,
            "displayType": "number",
            "displayName": "Scheduler Frequency",
            "description": "Scheduler running frequency in minutes."
        }
    ]
}
```

## 動態建立精靈元素
<a name="create-wizard-elements-bp"></a>

與建立精靈輸入相同的結構描述，可用於在合成期間動態重新轉譯精靈。這可用於在必要時解決使用者的後續問題。

```
//blueprint.ts

export interface Options extends ParentOptions {
...
 dynamicOptions: OptionsSchemaDefinition<'optionsIdentifier', KVSchema>;
}
```

然後，可以使用 `Options`元件在合成期間設定精靈。

```
import {
  OptionsSchemaDefinition,
  OptionsSchema,
} from '@amazon-codecatalyst/blueprints.blueprint';

...

  // dynamically renders a number in the place where 'optionsIdentifier' was set in the original options type.
  new OptionsSchema<KVSchema>(this, 'optionsIdentifier', [
    {
            "key": "SchedulerFrequency",
            "value": 5,
            "displayType": "number",
            "displayName": "Scheduler Frequency",
            "description": "Scheduler running frequency in minutes."
    }
   ]);
```

# 將環境元件新增至藍圖
<a name="comp-env-bp"></a>

自訂藍圖精靈會從透過精靈公開的`Options`界面動態產生。藍圖支援從公開的類型產生使用者介面 (UI) 元件。

**匯入 Amazon CodeCatalyst 藍圖環境元件**

在您的 `blueprint.ts`檔案中，新增下列項目：

```
import {...} from '@amazon-codecatalyst/codecatalyst-environments'
```

**Topics**
+ [建立開發環境](#create-dev-env-bp)
+ [環境清單](#list-env-bp)
+ [模擬界面範例](#examples-comp-env-bp)

## 建立開發環境
<a name="create-dev-env-bp"></a>

下列範例示範如何將應用程式部署至雲端：

```
export interface Options extends ParentOptions {
        ...
        myNewEnvironment:  EnvironmentDefinition{
            thisIsMyFirstAccountConnection: AccountConnection{
                thisIsARole: Role['lambda', 's3', 'dynamo'];
             };
        };
    }
```

介面會產生 UI 元件，要求具有單一帳戶連線 (`myNewEnvironment`) 的新環境 ()`thisIsMyFirstAccountConnection`。 帳戶連線 (`thisIsARole`) 上的角色也會與 產生，`['lambda', 's3', 'dynamo']`做為最低必要角色功能。並非所有使用者都有帳戶連線，因此您應該檢查使用者未連線帳戶或未將帳戶與角色連線的情況。角色也可以使用 標註`@inlinePolicies`。如需詳細資訊，請參閱[@inlinePolicy ./path/to/policy/file.json](wizard-bp.md#inline-policy-tag)。

環境元件需要 `name`和 `environmentType`。下列程式碼是所需的最低預設形狀：

```
{
  ...
  "myNewEnvironment": {
    "name": "myProductionEnvironment",
    "environmentType": "PRODUCTION"
  },
}
```

然後，UI 元件會提示您輸入各種欄位。當您填寫欄位時，藍圖會得到完全展開的形狀。將完整的模擬檔包含在 `defaults.json` 檔案中，以用於測試和開發目的，對您很有幫助。

## 環境清單
<a name="list-env-bp"></a>

指定 類型的陣列`EnvironmentDefinition`會在精靈 UI 中產生環境清單。

```
export interface Options extends ParentOptions {
    ...
   /**
     @showName readOnly
   */
    myEnvironments:  EnvironmentDefinition<{
        thisIsMyFirstAccountConnection: AccountConnection<{
            thisIsARole: Role<['lambda', 's3', 'dynamo']>;
        }>;
    }>[];

}
```

下列範例顯示環境清單的預設值：

```
{
  ...
  "myEnvironments": [
  {
    "name": "myProductionEnvironment",
    "environmentType": "PRODUCTION"
  },
  {
    "name": "myDevelopmentEnvironment",
    "environmentType": "DEVELOPMENT"
  },
  ]
}
```

## 模擬界面範例
<a name="examples-comp-env-bp"></a>

### 簡單模擬界面
<a name="simple-comp-env-bp"></a>

```
{
    ...
    "thisIsMyEnvironment": {
        "name": "myProductionEnvironment",
        "environmentType": "PRODUCTION",
        "thisIsMySecondAccountConnection": {
            "id": "12345678910",
            "name": "my-account-connection-name",
            "secondAdminRole": {
                "arn": "arn:aws:iam::12345678910:role/ConnectedQuokkaRole",
                "name": "ConnectedQuokkaRole",
                "capabilities": [
                    "lambda",
                    "s3",
                    "dynamo"
                ]
            }
        }
    }
}
```

### 複雜模擬界面
<a name="complex-comp-env-bp"></a>

```
export interface Options extends ParentOptions {
  /**
   * The name of an environment
   * @displayName This is a Environment Name
   * @collapsed
   */
  thisIsMyEnvironment: EnvironmentDefinition{
    /**
     * comments about the account that is being deployed into
     * @displayName This account connection has an overriden name
     * @collapsed
     */
    thisIsMyFirstAccountConnection: AccountConnection{
      /**
       * Blah blah some information about the role that I expect
       * e.g. here's a copy-pastable policy: [to a link]
       * @displayName This role has an overriden name
       */
      adminRole: Role['admin', 'lambda', 's3', 'cloudfront'];
      /**
       * Blah blah some information about the second role that I expect
       * e.g. here's a copy-pastable policy: [to a link]
       */
      lambdaRole: Role['lambda', 's3'];
    };
    /**
     * comments about the account that is being deployed into
     */
    thisIsMySecondAccountConnection: AccountConnection{
      /**
         * Blah blah some information about the role that I expect
         * e.g. here's a copy-pastable policy: [to a link]
         */
      secondAdminRole: Role['admin', 'lambda', 's3', 'cloudfront'];
      /**
         * Blah blah some information about the second role that I expect
         * e.g. here's a copy-pastable policy: [to a link]
         */
      secondLambdaRole: Role['lambda', 's3'];
    };
  };
}
```

### 完整模擬界面
<a name="complete-comp-env-bp"></a>

```
{
  ...
  "thisIsMyEnvironment": {
    "name": "my-production-environment",
    "environmentType": "PRODUCTION",
    "thisIsMySecondAccountConnection": {
      "id": "12345678910",
      "name": "my-connected-account",
      "secondAdminRole": {
        "name": "LambdaQuokkaRole",
        "arn": "arn:aws:iam::12345678910:role/LambdaQuokkaRole",
        "capabilities": [
          "admin",
          "lambda",
          "s3",
          "cloudfront"
        ]
      },
      "secondLambdaRole": {
        "name": "LambdaQuokkaRole",
        "arn": "arn:aws:iam::12345678910:role/LambdaQuokkaRole",
        "capabilities": [
          "lambda",
          "s3"
        ]
      }
    },
    "thisIsMyFirstAccountConnection": {
      "id": "12345678910",
      "name": "my-connected-account",
      "adminRole": {
        "name": "LambdaQuokkaRole",
        "arn": "arn:aws:iam::12345678910:role/LambdaQuokkaRole",
        "capabilities": [
          "admin",
          "lambda",
          "s3",
          "cloudfront"
        ]
      },
      "lambdaRole": {
        "name": "LambdaQuokkaRole",
        "arn": "arn:aws:iam::12345678910:role/LambdaQuokkaRole",
        "capabilities": [
          "lambda",
          "s3"
        ]
      }
    }
  },
}
```

# 將秘密元件新增至藍圖
<a name="secrets-comp-bp"></a>

CodeCatalyst 中可以使用秘密來存放可在工作流程中參考的敏感資料。您可以將秘密新增至自訂藍圖，並在工作流程中參考它。如需詳細資訊，請參閱[使用秘密遮罩資料](workflows-secrets.md)。

**匯入 Amazon CodeCatalyst 藍圖區域類型**

在您的 `blueprint.ts`檔案中，新增下列項目：

```
import { Secret, SecretDefinition } from '@amazon-codecatalyst/blueprint-component.secrets'
```

**Topics**
+ [建立秘密](#comp-create-secrets-bp)
+ [在工作流程中參考秘密](#comp-reference-secrets-bp)

## 建立秘密
<a name="comp-create-secrets-bp"></a>

下列範例會建立 UI 元件，提示使用者輸入秘密值和選用描述：

```
export interface Options extends ParentOptions {
    ...
    mySecret: SecretDefinition;
}


export class Blueprint extends ParentBlueprint {
  constructor(options_: Options) {
    new Secret(this, options.secret);
}
```

秘密元件需要 `name`。下列程式碼是所需的最低預設形狀：

```
{
    ...
    "secret": {
        "name": "secretName"
    },

}
```

## 在工作流程中參考秘密
<a name="comp-reference-secrets-bp"></a>

下列範例藍圖會建立秘密和參考秘密值的工作流程。如需詳細資訊，請參閱[在工作流程中參考秘密](workflows-secrets.using.md#workflows-using-secrets.using-identifier)。

```
export interface Options extends ParentOptions {
    ...
/**
*
* @validationRegex /^\w+$/
*/
  username: string;


  password: SecretDefinition;
}


export class Blueprint extends ParentBlueprint {
  constructor(options_: Options) {
    const password = new Secret(this, options_.password);

    const workflowBuilder = new WorkflowBuilder(this, {
      Name: 'my_workflow',
    });


    workflowBuilder.addBuildAction({
      actionName: 'download_files',
      input: {
        Sources: ['WorkflowSource'],
      },
      output: {
        Artifacts: [{ Name: 'download', Files: ['file1'] }],
      },
      steps: [
        `curl -u ${options_.username}:${password.reference} https://example.com`,
      ],
    });

    new Workflow(
      this,
      repo,
      workflowBuilder.getDefinition(),
    );

}
```

若要進一步了解如何在 CodeCatalyst 中使用秘密，請參閱 [使用秘密遮罩資料](workflows-secrets.md)。

# 將區域元件新增至藍圖
<a name="region-comp-bp"></a>

區域類型可以新增至自訂藍圖的`Options`界面，以在藍圖精靈中產生元件，您可以輸入一或多個 AWS gions。您可以從 `blueprint.ts` 檔案的基礎藍圖匯入 gion 類型。如需詳細資訊，請參閱 [AWS 區域](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/)。

**匯入 Amazon CodeCatalyst 藍圖區域類型**

在您的 `blueprint.ts`檔案中，新增下列項目：

```
import { Region } from '@amazon-codecatalyst/blueprints.blueprint'
```

區域類型參數是可選擇的 AWS 區域代碼陣列，您也可以使用 `*` 來包含所有支援的 AWS 區域。

**Topics**
+ [註釋](#region-annotations-bp)
+ [區域元件範例](#region-components-examples)

## 註釋
<a name="region-annotations-bp"></a>

JSDoc 標籤可新增至`Options`界面中的每個欄位，以自訂欄位在精靈中的顯示和行為方式。對於區域類型，支援下列標籤：
+ `@displayName` 註釋可用於在精靈中變更欄位的標籤。

  範例：`@displayName AWS Region`
+ `@placeholder` 註釋可用來變更 Select/multiselect 元件的預留位置。

  範例：`@placeholder Choose AWS Region`

## 區域元件範例
<a name="region-components-examples"></a>

### 從指定的清單中選擇區域
<a name="region-specified-list-bp"></a>

```
export interface Options extends ParentOptions {
    ...
  /**
   * @displayName Region
   */
  region: Region<['us-east-1', 'us-east-2', 'us-west-1', 'us-west-2']>;
}
```

### 從指定的清單中選擇一或多個區域
<a name="region-specified-list-bp"></a>

```
export interface Options extends ParentOptions {
    ...
  /**
   * @displayName Regions
   */
  multiRegion: Region<['us-east-1', 'us-east-2', 'us-west-1', 'us-west-2']>[];
}
```

### 選擇一個 AWS egion
<a name="region-one-bp"></a>

```
export interface Options extends ParentOptions {
    ...
  /**
   * @displayName Region
   */
  region: Region<['*']>;
}
```

### 從指定的清單中選擇一或多個區域
<a name="region-specified-list-bp"></a>

```
export interface Options extends ParentOptions {
    ...
  /**
   * @displayName Regions
   */
  multiRegion: Region<['us-east-1', 'us-east-2', 'us-west-1', 'us-west-2']>[];
}
```

# 將儲存庫和原始程式碼元件新增至藍圖
<a name="comp-repo-source-bp"></a>

Amazon CodeCatalyst 會使用儲存庫來存放程式碼。儲存庫會採用名稱做為輸入。大多數元件存放在儲存庫中，例如原始程式碼檔案、工作流程和其他元件，例如受管開發環境 (MDE)。來源儲存庫元件也會匯出用於管理檔案和靜態資產的元件。儲存庫有名稱限制。如需詳細資訊，請參閱[將程式碼與 CodeCatalyst 中的來源儲存庫一起存放和協作儲存程式碼並與來源儲存庫協作](source.md)。

```
const repository = new SourceRepository(this, {
  title: 'my-new-repository-title',
});
```

**匯入 Amazon CodeCatalyst 藍圖儲存庫和原始程式碼元件**

在您的 `blueprint.ts`檔案中，新增下列項目：

```
import {...} from '@caws-blueprint-component/caws-source-repositories'
```

**Topics**
+ [新增檔案](#repo-add-file-bp)
+ [新增一般檔案](#repo-add-generic-file-bp)
+ [複製檔案](#repo-copy-file-bp)
+ [鎖定多個檔案](#target-multiple-files-bp)
+ [建立新的儲存庫並新增檔案](#repo-code-examples-bp)

## 新增檔案
<a name="repo-add-file-bp"></a>

您可以使用 `SourceFile` 建構將文字檔案寫入儲存庫。操作是最常見的使用案例之一，並採用儲存庫、檔案路徑和文字內容。如果檔案路徑不存在於儲存庫中，元件會建立所有必要的資料夾。

```
new SourceFile(repository, `path/to/my/file/in/repo/file.txt`, 'my file contents');
```

**注意**  
如果您將兩個檔案寫入相同儲存庫中的相同位置，則最新的實作會覆寫先前的檔案。您可以使用 功能來分層產生的程式碼，而且在延伸自訂藍圖可能已產生的程式碼時特別有用。

## 新增一般檔案
<a name="repo-add-generic-file-bp"></a>

您可以將任意位元寫入儲存庫。您可以從緩衝區讀取並使用 `File` 建構。

```
new File(repository, `path/to/my/file/in/repo/file.img`, new Buffer(...));

new File(repository, `path/to/my/file/in/repo/new-img.img`, new StaticAsset('path/to/image.png').content());
```

## 複製檔案
<a name="repo-copy-file-bp"></a>

您可以複製並貼上入門程式碼，然後在該基礎上產生更多程式碼，以開始使用產生的程式碼。將程式碼放在 `static-assets` 目錄中，然後使用 `StaticAsset` 建構將該程式碼設為目標。在此情況下，路徑一律從 `static-assets` 目錄的根目錄開始。

```
const starterCode = new StaticAsset('path/to/file/file.txt')
const starterCodeText = new StaticAsset('path/to/file/file.txt').toString()
const starterCodeRawContent = new StaticAsset('path/to/image/hello.png').content()

const starterCodePath = new StaticAsset('path/to/image/hello.png').path()
// starterCodePath is equal to 'path/to/image/hello.png'
```

的子類別`StaticAsset`為 `SubstitutionAsset`。子類別的功能完全相同，但您可以改為對檔案執行八字形替換。其有助於執行copy-and-replace樣式產生。

靜態資產替換使用八字形範本引擎來轉譯植入產生來源儲存庫的靜態檔案。轉譯期間會套用八字形範本規則，這表示所有值預設為 HTML 編碼。若要轉譯未逸出的 HTML，請使用三重八字語法 `{{{name}}}`。如需詳細資訊，請參閱[八字形範本規則](https://github.com/janl/mustache.js?tab=readme-ov-file#variables)。

**注意**  
對無法解譯文字的檔案執行替代 可能會產生錯誤。

```
const starterCodeText = new SubstitionAsset('path/to/file/file.txt').subsitite({
  'my_variable': 'subbed value1',
  'another_variable': 'subbed value2'
})
```

## 鎖定多個檔案
<a name="target-multiple-files-bp"></a>

靜態資產支援透過 上的靜態函數`StaticAsset`及其名為 的子類別來鎖定 glob`findAll(...)`，這會傳回預先載入其路徑、內容等的靜態資產清單。您可以將清單與`File`建構連結，以複製內容並貼到 `static-assets`目錄中。

```
new File(repository, `path/to/my/file/in/repo/file.img`, new Buffer(...));

new File(repository, `path/to/my/file/in/repo/new-img.img`, new StaticAsset('path/to/image.png').content());
```

## 建立新的儲存庫並新增檔案
<a name="repo-code-examples-bp"></a>

您可以使用儲存庫元件，在產生的專案中建立新的儲存庫。然後，您可以將檔案或工作流程新增至建立的儲存庫。

```
import { SourceRepository } from '@amazon-codecatalyst/codecatalyst-source-repositories';
...
const repository = new SourceRepository(this, { title: 'myRepo' });
```

下列範例示範如何將檔案和工作流程新增至現有的儲存庫：

```
import { SourceFile } from '@amazon-codecatalyst/codecatalyst-source-repositories';
import { Workflow } from '@amazon-codecatalyst/codecatalyst-workflows';
...
new SourceFile(repository, 'README.md', 'This is the content of my readme');
new Workflow(this, repository, {/**...workflowDefinition...**/});
```

結合這兩項程式碼，會產生名為 的單一儲存庫，`myRepo`其中包含來源檔案`README.md`和根目錄的 CodeCatalyst 工作流程。

# 將工作流程元件新增至藍圖
<a name="comp-workflow-bp"></a>

Amazon CodeCatalyst 專案會使用工作流程，根據觸發條件執行動作。您可以使用工作流程元件來建置和組合工作流程 YAML 檔案。如需詳細資訊，請參閱[工作流程 YAML 定義](workflow-reference.md)。

**匯入 Amazon CodeCatalyst 藍圖工作流程元件**

在您的 `blueprint.ts`檔案中，新增下列項目：

```
import { WorkflowBuilder, Workflow } from '@amazon-codecatalyst/codecatalyst-workflows'
```

**Topics**
+ [工作流程元件範例](#comp-workflows-examples-bp)
+ [連線至環境](#comp-workflows-connect-env-bp)

## 工作流程元件範例
<a name="comp-workflows-examples-bp"></a>

### WorkflowBuilder 元件
<a name="comp-workflows-workflowbuilder-bp"></a>

您可以使用 類別來建置工作流程定義。可將 定義提供給工作流程元件，以便在儲存庫中轉譯。

```
import { WorkflowBuilder } from '@amazon-codecatalyst/codecatalyst-workflows'

const workflowBuilder = new WorkflowBuilder({} as Blueprint, {
  Name: 'my_workflow',
});

// trigger the workflow on pushes to branch 'main'
workflowBuilder.addBranchTrigger(['main']);

// add a build action
workflowBuilder.addBuildAction({
  // give the action a name
  actionName: 'build_and_do_some_other_stuff',

  // the action pulls from source code
  input: {
    Sources: ['WorkflowSource'],
  },

  // the output attempts to autodiscover test reports, but not in the node modules
  output: {
    AutoDiscoverReports: {
      Enabled: true,
      ReportNamePrefix: AutoDiscovered,
      IncludePaths: ['**/*'],
      ExcludePaths: ['*/node_modules/**/*'],
    },
  },
  // execute some arbitrary steps
  steps: [
    'npm install',
    'npm run myscript',
    'echo hello-world',
  ],
  // add an account connection to the workflow
  environment: convertToWorkflowEnvironment(myEnv),
});
```

### Workflow Projen 元件
<a name="comp-workflows-projen-bp"></a>

下列範例顯示如何使用 Projen 元件將工作流程 YAML 寫入儲存庫：

```
import { Workflow } from '@amazon-codecatalyst/codecatalyst-workflows'

...

const repo = new SourceRepository
const blueprint = this;
const workflowDef = workflowBuilder.getDefinition()

// creates a workflow.yaml at .aws/workflows/${workflowDef.name}.yaml
new Workflow(blueprint, repo, workflowDef);

// can also pass in any object and have it rendered as a yaml. This is unsafe and may not produce a valid workflow
new Workflow(blueprint, repo, {... some object ...});
```

## 連線至環境
<a name="comp-workflows-connect-env-bp"></a>

許多工作流程需要在 AWS 帳戶連線中執行。工作流程透過允許 動作透過帳戶和角色名稱規格連線到環境來處理此問題。

```
import { convertToWorkflowEnvironment } from '@amazon-codecatalyst/codecatalyst-workflows'


const myEnv = new Environment(...);

// can be passed into a workflow constructor
const workflowEnvironment = convertToWorkflowEnvironment(myEnv);


// add a build action
workflowBuilder.addBuildAction({
  ...
  // add an account connection to the workflow
  environment: convertToWorkflowEnvironment(myEnv),
});
```

# 將開發環境元件新增至藍圖
<a name="comp-dev-env-bp"></a>

受管開發環境 (MDE) 用於在 CodeCatalyst 中建立和站立 MDE 工作區。元件會產生 `devfile.yaml` 檔案。如需詳細資訊，請參閱 [Devfile 簡介](https://redhat-developer.github.io/devfile/)和 [編輯開發環境的儲存庫 devfile](devenvironment-devfile-moving.md)。

```
new Workspace(this, repository, SampleWorkspaces.default);
```

**匯入 Amazon CodeCatalyst 藍圖工作區元件**

在您的 `blueprint.ts`檔案中，新增下列項目：

```
import {...} from '@amazon-codecatalyst/codecatalyst-workspaces'
```

# 將問題元件新增至藍圖
<a name="comp-issues-bp"></a>

在 CodeCatalyst 中，您可以監控功能、任務、錯誤，以及專案中涉及的任何其他工作。每個工作都會保留在不同的記錄中，稱為問題。每個問題都可以有一個描述、被指派者、狀態和其他屬性，您可以對其進行搜尋、分組和篩選。您可以使用預設檢視來檢視問題，也可以使用自訂篩選、排序或分組來建立自己的檢視。如需 問題相關概念的詳細資訊，請參閱 [問題概念](issues-concepts.md)和 [CodeCatalyst 中問題的配額](issues-quotas.md)。

問題元件會產生問題的 JSON 表示法。元件會採用 ID 欄位並發出定義做為輸入。

**匯入 Amazon CodeCatalyst 藍圖發行元件**

在您的 `blueprint.ts`檔案中，新增下列項目：

```
import {...} from '@amazon-codecatalyst/blueprint-component.issues'
```

**Topics**
+ [問題元件範例](#comp-issues-examples-bp)

## 問題元件範例
<a name="comp-issues-examples-bp"></a>

### 建立問題
<a name="comp-issues-create-bp"></a>

```
import { Issue } from '@amazon-codecatalyst/blueprint-component.issues';
...
new Issue(this, 'myFirstIssue', {
  title: 'myFirstIssue',
  content: 'This is an example issue.',
});
```

### 建立高優先順序問題
<a name="comp-issues-high-priority-bp"></a>

```
import { Workflow } from '@amazon-codecatalyst/codecatalyst-workflows'
...
const repo = new SourceRepository
const blueprint = this;
const workflowDef = workflowBuilder.getDefinition()

// Creates a workflow.yaml at .aws/workflows/${workflowDef.name}.yaml
new Workflow(blueprint, repo, workflowDef);

// Can also pass in any object and have it rendered as a yaml. This is unsafe and may not produce a valid workflow
new Workflow(blueprint, repo, {... some object ...});
```

### 使用標籤建立低優先順序問題
<a name="comp-issues-low-priority-bp"></a>

```
import { Issue } from '@amazon-codecatalyst/blueprint-component.issues';
...
new Issue(this, 'myThirdIssue', {
  title: 'myThirdIssue',
  content: 'This is an example of a low priority issue with a label.',
  priority: 'LOW',
  labels: ['exampleLabel'],
});
```

# 使用藍圖工具和 CLI
<a name="bp-cli"></a>

[藍圖 CLI](https://www.npmjs.com/package/@amazon-codecatalyst/blueprint-util.cli) 提供工具來管理和使用自訂藍圖。

**Topics**
+ [使用藍圖工具](#working-with-bp-cli)
+ [影像上傳工具](#image-upload-tool)

## 使用藍圖工具
<a name="working-with-bp-cli"></a>

**使用藍圖工具**

1. 開啟 CodeCatalyst 主控台，網址為 https：//[https://codecatalyst.aws/](https://codecatalyst.aws/)。

1. 繼續開發環境。如需詳細資訊，請參閱[恢復開發環境](devenvironment-resume.md)。

   如果您沒有開發環境，您必須先建立一個。如需詳細資訊，請參閱[建立開發環境](devenvironment-create.md)。

1. 在運作中的終端機中，執行下列命令來安裝藍圖 CLI：

   ```
   npm install -g @amazon-codecatalyst/blueprint-util.cli
   ```

1. 在 `blueprint.ts` 檔案中，匯入您想要使用的工具，格式如下：

   ```
   import { <tooling-function-name> } from '@amazon-codecatalyst/blueprint-util.cli/lib/<tooling-folder-name>/<tooling-file-name>;
   ```
**提示**  
您可以前往 [https://github.com/aws/codecatalyst-blueprints/tree/main/packages/utils/blueprint-cli](https://github.com/aws/codecatalyst-blueprints/tree/main/packages/utils/blueprint-cli) 來尋找您要使用的工具名稱。

   **如果您想要使用映像上傳工具，請將以下內容新增至指令碼：**

   ```
   import { uploadImagePublicly } from '@amazon-codecatalyst/blueprint-util.cli/lib/image-upload-tool/upload-image-to-aws';
   ```

   **範例**
   + **如果您想要使用發佈函數，請將以下內容新增至指令碼：**

     ```
     import { publish } from '@amazon-codecatalyst/blueprint-util.cli/lib/publish/publish';
     ```
   + **如果您想要使用映像上傳工具，請將以下內容新增至指令碼：**

     ```
     import { uploadImagePublicly } from '@amazon-codecatalyst/blueprint-util.cli/lib/image-upload-tool/upload-image-to-aws';
     ```

1. 呼叫 函數。

   **範例**：
   + **如果您想要使用發佈函數，請將以下內容新增至指令碼：**

     ```
     await publish(logger, config.publishEndpoint, {<your publishing options>});
     ```
   + **如果您想要使用映像上傳工具，請將以下內容新增至指令碼：**

     ```
     const {imageUrl, imageName} = await uploadImagePublicly(logger, 'path/to/image'));
     ```

## 影像上傳工具
<a name="image-upload-tool"></a>

映像上傳工具可讓您將自己的映像上傳到 AWS 帳戶中的 S3 儲存貯體，然後將該映像公開分發到 CloudFront 後方。工具會在本機儲存體 （和選用儲存貯體名稱） 中取得影像路徑做為輸入，並將 URL 傳回至公開可用的影像。如需詳細資訊，請參閱[什麼是 Amazon CloudFront？](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html)和[什麼是 Amazon S3？](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html)

**使用映像上傳工具**

1. 複製[開放原始碼藍圖 GitHub 儲存庫，該儲存庫](https://github.com/aws/codecatalyst-blueprints)可存取藍圖 SDK 和範例藍圖。在運作中的終端機中，執行下列命令：

   ```
   git clone https://github.com/aws/codecatalyst-blueprints.git
   ```

1. 執行下列命令以導覽至藍圖 GitHub 儲存庫：

   ```
   cd codecatalyst-blueprints
   ```

1. 執行下列命令來安裝相依性：

   ```
   yarn && yarn build
   ```

1. 執行下列命令，以確保已安裝最新的藍圖 CLI 版本：

   ```
   yarn upgrade @amazon-codecatalyst/blueprint-util.cli
   ```

1. 使用您要上傳映像的 S3 儲存貯體登入 AWS 帳戶。如需詳細資訊，請參閱[設定 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) 和[透過 AWS 命令列界面登入](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html)。

1. 從 CodeCatalyst 儲存庫的根目錄執行下列命令，以使用藍圖 CLI 導覽至 目錄：

   ```
   cd packages/utils/blueprint-cli
   ```

1. 執行下列命令，將映像上傳至 S3 儲存貯體：

   ```
   yarn blueprint upload-image-public <./path/to/your/image> 
         <optional:optional-bucket-name>
   ```

映像的 URL 會產生。URL 無法立即使用，因為需要一些時間才能部署 CloudFront 分佈。檢查分佈狀態以取得最新的部署狀態。如需詳細資訊，請參閱[使用 分佈](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-working-with.html)。

# 使用快照測試評估界面變更
<a name="testing-bp"></a>

支援跨藍圖的多個組態產生快照測試。

藍圖支援對您以藍圖作者身分提供的組態進行[快照測試](https://jestjs.io/docs/snapshot-testing)。這些組態是部分覆寫，合併在藍圖根目錄的 defaults.json 檔案之上。啟用並設定快照測試時，建置和測試程序會合成指定的組態，並驗證合成的輸出尚未從參考快照變更。若要檢視快照測試程式碼，請參閱 [CodeCatalyst 藍圖 GitHub 儲存庫](https://github.com/aws/codecatalyst-blueprints/blob/main/packages/utils/projen-blueprint/src/test-snapshot.ts#L12)。

**啟用快照測試**

1. 在 `.projenrc.ts` 檔案中，將輸入物件更新為 ProjenBlueprint，其中包含您想要快照的檔案。例如：

   ```
   {
     ....
     blueprintSnapshotConfiguration: {
       snapshotGlobs: ['**', '!environments/**', '!aws-account-to-environment/**'],
     },
   }
   ```

1. 重新合成藍圖，以在藍圖專案中建立 TypeScript 檔案。請勿編輯來源檔案，因為它們是由 Projen 維護和重新產生。使用下列命令：

   ```
   yarn projen
   ```

1. 導覽至 `src/snapshot-configurations`目錄以檢視具有空白物件`default-config.json`的檔案。更新 檔案，或將檔案取代為一或多個您自己的測試組態。然後，每個測試組態都會與專案`defaults.json`的檔案合併、合成，並在測試時與快照進行比較。使用下列命令來測試：

   ```
   yarn test
   ```

   第一次使用測試命令時，會顯示下列訊息：`Snapshot Summary › NN snapshots written from 1 test suite`。後續測試執行會驗證合成的輸出尚未從快照變更，並顯示下列訊息：`Snapshots: NN passed, NN total`。

   如果您刻意變更藍圖以產生不同的輸出，請執行下列命令來更新參考快照：

   ```
   yarn test:update
   ```

快照預期合成的輸出在每一次執行之間都是固定的。如果您的藍圖產生不同的檔案，您必須將這些檔案排除在快照測試之外。更新`ProjenBluerpint`輸入`blueprintSnapshotConfiguration`物件的物件以新增 `snapshotGlobs` 屬性。`snapshotGlobs` 屬性是 [glob](https://github.com/isaacs/node-glob#glob-primer) 陣列，可決定快照中包含或排除哪些檔案。

**注意**  
有預設的 glob 清單。如果您指定自己的清單，您可能需要明確地取回預設項目。