這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

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

# 設定 AWS CDK Library 用量資料報告
<a name="usage-data"></a>

## 什麼是 CDK 程式庫用量資料報告？
<a name="usage-data-intro"></a>

 AWS 雲端開發套件 (AWS CDK) 應用程式設定為收集和報告用量資料，以深入了解 AWS CDK 的使用方式。CDK 團隊使用此資料來執行下列動作：
+  **與客戶通訊** – 使用已知安全性或可靠性問題的建構來識別堆疊，並傳送客戶影響主題的通訊。
+  **通知 CDK 開發** – 深入了解 CDK 使用情況，以更好地通知 CDK 開發。
+  **調查 CDK 問題** – 回報錯誤時，使用資料會在故障診斷時為 CDK 團隊提供寶貴的洞見。

## 會收集哪些用量資料？
<a name="usage-data-categories"></a>

CDK 收集的應用程式用量資料有兩種類別：
+ 一般用量資料
+ 其他用量資料

### 一般用量資料收集
<a name="usage-data-categories-general"></a>

CDK 會從 CDK 應用程式收集下列類型的一般使用資料：
+ 使用的 CDK 程式庫版本。
+ 從下列`NPM`模組使用的建構名稱：
  +  AWS CDK 核心模組
  +  AWS 建構程式庫模組
  +  AWS 解決方案建構模組
  +  AWS 轉譯陣列部署套件模組

**注意**  
在 1.93.0 版之前， AWS CDK 會報告合成期間載入的模組名稱和版本，而不是堆疊中使用的建構。

### 其他用量資料收集
<a name="usage-data-categories-additional"></a>

從 CDK 2.178.0 版開始，用量資料收集擴展為包含下列其他用量資料：
+  **CDK 定義的屬性金鑰** – 當您使用 L2 建構的內建屬性時，將會收集屬性金鑰。這包括巢狀在字典物件中的內建屬性索引鍵。
+  **來自 CDK 定義的屬性索引鍵的布林值和列舉屬性值** – 對於 CDK 定義的屬性索引鍵，只會收集布林值和列舉類型的屬性值。字串值或建構參考等所有其他類型都會進行修訂。
+  **布林和列舉類型的方法名稱、索引鍵和屬性值** – 當您使用 L2 建構方法時，我們會收集布林和列舉類型的方法名稱、屬性索引鍵和屬性值。

對於您唯一建立的屬性索引鍵和值，將修訂整個物件。例如，如果您使用 ` [RestApi](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApi.html) ` ` [InlineApiDefinition](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.InlineApiDefinition.html) `定義OpenAPI規格並將其傳遞至建構，則整個`InlineApiDefinition`物件將會修訂。

如需其他用量資料收集的詳細資訊，包括其優點和潛在考量，請參閱 *aws-cdk 儲存庫*中的 [CDK 收集其他中繼資料 （在功能旗標下） \$133198](https://github.com/aws/aws-cdk/discussions/33198) 討論。

## CDK 如何收集應用程式用量資料
<a name="usage-data-how"></a>

在合成時，CDK 會從應用程式收集用量資料，並將其存放在 ` AWS::CDK::Metadata` 資源中。以下是合成 AWS CloudFormation 範本上的範例：

```
CDKMetadata:
  Type: "AWS::CDK::Metadata"
  Properties:
    Analytics: "v2:deflate64:H4sIAND9SGAAAzXKSw5AMBAA0L1b2PdzBYnEAdio3RglglY60zQi7u6TWL/XKmNUlxeQSOKwaPTBqrNhwEWU3hGHiCzK0dWWfAxoL/Fd8mvk+QkS/0X6BdjnCdgmOOQKWz+AqqLDt2Y3YMnLYWwAAAA="
```

`Analytics` 屬性是堆疊中建構的 gziped、base64 編碼、字首編碼清單。

## 如何選擇退出或加入用量資料報告
<a name="usage-data-configure"></a>

您選擇退出或選擇加入一般用量資料報告和其他用量資料報告的選項，取決於您最初用來建立應用程式的 CDK 版本。

根據預設，CDK 應用程式會設定為自動選擇加入用量資料報告，如下所示：
+  **所有 CDK 應用程式** – 選擇加入一般用量資料報告。
+  **使用早於 v2.178.0 的版本建立的 CDK 應用程式** – 未自動選擇加入其他用量資料報告。
+  **使用 v2.178.0 或更新版本建立的 CDK 應用程式** – 選擇加入其他用量資料報告。

**警告**  
如果您選擇選擇退出，CDK 將無法識別您是否受到安全問題的影響，也不會傳送通知給您。

### 選擇退出所有用量資料報告
<a name="usage-data-configure-optout-all"></a>

若要選擇退出所有用量資料報告，您可以使用 AWS 雲端開發套件 (AWS CDK) 命令列界面 (CLI) 或設定專案`cdk.json`的檔案。

 **使用 CDK CLI 選擇退出所有用量資料報告**   
+ 將 `--no-version-reporting`選項與任何 CDK CLI 命令搭配使用，以選擇退出單一命令。以下是在範本合成期間選擇退出的範例：

  ```
  $ cdk synth --no-version-reporting
  ```

  由於 CDK 會在您執行 時自動合成範本`cdk deploy`，因此您也應該`--no-version-reporting`搭配 `cdk deploy`命令使用 。

 **設定 cdk.json 檔案以選擇退出所有用量資料報告**   

1. 在 `./cdk.json`或 `false`中`versionReporting`將 設定為 `~/.cdk.json`。根據預設，這會讓您退出。以下是範例：

   ```
   {
     "app": "...",
     "versionReporting": false
   }
   ```

1. 設定之後，您可以覆寫此行為，並在個別命令`--version-reporting`上指定 以選擇加入。

### 僅選擇退出其他用量資料報告
<a name="usage-data-configure-optout-additiona"></a>

如果您的 CDK 應用程式是使用早於 2.178.0 的 CDK 版本建立，即使您選擇加入一般用量資料報告，也會自動選擇退出其他用量資料報告。您不需要採取任何動作來選擇退出其他用量資料報告。

如果您的 CDK 應用程式是使用 CDK 2.178.0 版或更新版本建立，您必須選擇退出所有用量資料報告。您無法只選擇退出額外的用量資料報告。

### 選擇使用資料報告
<a name="usage-data-configure-optin"></a>

如果您的 CDK 應用程式是使用 CDK 2.178.0 版或更新版本建立，您可以透過將 `versionReporting`設定為 來選擇加入所有用量資料報告`true`。這是 CDK 應用程式的預設行為。

如果您的 CDK 應用程式是使用早於 2.178.0 的 CDK 版本建立，您可以透過將 `versionReporting`設定為 來選擇加入一般用量資料報告。 `true`若要選擇加入其他用量資料報告，您必須啟用功能旗標。

**注意**  
這些步驟適用於最初使用早於 2.178.0 的版本建立的 CDK 應用程式

1. 確認您現在使用的是 CDK 2.178.0 版或更新版本。

1. 在 CDK 組態檔案中，指定 `@aws-cdk/core:enableAdditionalMetadataCollection`為 `true`。以下是範例：

   ```
   {
     "context": {
       "@aws-cdk/core:enableAdditionalMetadataCollection": "true"
     }
   }
   ```

1. 您也可以搭配 ` [FeatureFlags](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.FeatureFlags.html) `類別使用 `ENABLE_ADDITIONAL_METADATA_COLLECTION`值。以下是範例：

   ```
   import * as cdk from 'aws-cdk-lib';
   import { FeatureFlags } from 'aws-cdk-lib';
   import * as cx_api from 'aws-cdk-lib/cx-api';
   import { Construct } from 'constructs';
   
   export class MyStack extends cdk.Stack {
     constructor(scope: Construct, id: string, props?: cdk.StackProps) {
       super(scope, id, props);
   
       // Set the feature flag ENABLE_ADDITIONAL_METADATA_COLLECTION to true
       FeatureFlags.of(this).add(cx_api.ENABLE_ADDITIONAL_METADATA_COLLECTION, true);
   
       // Your stack resources go here
       new cdk.aws_s3.Bucket(this, 'MyBucket');
     }
   }
   
   const app = new cdk.App();
   new MyStack(app, 'MyStack');
   ```

## 範例
<a name="usage-data-examples"></a>

### 從 CDK 應用程式收集的一般和其他用量資料
<a name="usage-data-examples-example1"></a>

以下是 CDK 應用程式的範例：

```
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';

class MyStack extends cdk.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    // Create an S3 bucket (L2 construct)
    const myBucket = new s3.Bucket(this, 'MyBucket', {
      bucketName: 'my-cdk-example-bucket', // String type
      versioned: true,                    // Boolean type
      removalPolicy: cdk.RemovalPolicy.DESTROY, // ENUM type
      lifecycleRules: [{                  // Array of object type
        expirationDate: new Date('2019-10-01'),
        objectSizeLessThan: 600,
        objectSizeGreaterThan: 500,
      }],
    });

    // Use a method of the L2 construct to define additional properties
    myBucket.addLifecycleRule({
      id: 'ExpireOldObjects',
      enabled: true, // Boolean
      expiration: cdk.Duration.days(90), // Expire objects after 90 days
    });
  }
}

// Define the CDK app and stack
const app = new cdk.App();
new MyStack(app, 'MyStack');
app.synth();
```

在合成時，會收集、壓縮用量資料，並存放在 ` AWS::CDK::Metadata` 資源中。

以下是使用早於 2.178.0 的 CDK 版本收集的一般用量資料範例：

```
{
    "fqn": "aws-cdk-lib.aws-s3.Bucket",
    "version": "v2.170.0"
}
```

以下是收集的用量資料範例，包括 CDK 2.178.0 版中引入的其他用量資料：

```
{
    "fqn": "aws-cdk-lib.aws_s3.Bucket",
    "version": "2.170.0",
    "metadata": [
        {
            "type": "aws:cdk:analytics:construct",
            "data": {
                "bucketName": "*",
                "versioned": true,
                "removalPolicy": "cdk.RemovalPolicy.DESTROY",
                "lifecycleRules": [
                    {
                        "expirationDate": "*",
                        "objectSizeLessThan": "*",
                        "objectSizeGreaterThan": "*"
                    }
                ]
            }
        },
        {
            "type": "aws:cdk:analytics:method",
            "data": {
                "name": "addLifecycleRule",
                "prop": {
                    "id": "*",
                    "enabled": true,
                    "expiration": "*",
                }
            }
        }
    ]
}
```