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

# 指定自訂中繼資料
<a name="CloudWatch-RUM-custom-metadata"></a>

CloudWatch RUM 會附加額外的資料至每個事件作為中繼資料。事件中繼資料是由鍵-值對形式的屬性組成。您可以使用這些屬性來搜尋或篩選 CloudWatch RUM 主控台中的事件。根據預設，CloudWatch RUM 會為您建立一些中繼資料。如需有關預設中繼資料的詳細資訊，請參閱 [RUM 事件中繼資料](CloudWatch-RUM-datacollected.md#CloudWatch-RUM-datacollected-metadata)。

您也可以使用 CloudWatch RUM Web 用戶端將自訂中繼資料新增至 CloudWatch RUM 事件。自訂中繼資料可以包含工作階段屬性和頁面屬性。

若要新增自訂中繼資料，您必須使用版本 1.10.0 或更新版本的 CloudWatch RUM Web 用戶端。

## 要求與語法
<a name="CloudWatch-RUM-custom-metadata-syntax"></a>

每個事件可以在中繼資料中包含多達 10 個自訂屬性。自訂屬性的語法要求如下：
+ **鍵**
  + 最多 128 個字元。
  + 可以包含英數字元、冒號 (:) 和底線 (\_)。
  + 開頭不能是 `aws:`。
  + 不能完全由下一節中列出的任何保留關鍵字組成。可以將這些關鍵字用作鍵名稱的一部分。
+ **Values (數值)**
  + 最多 256 個字元。
  + 必須是字串、數字或布林值

**保留的關鍵字**

您不能使用下列保留關鍵字作為完整鍵名稱。您可以使用下列關鍵字作為鍵名稱的一部分，例如 `applicationVersion`。
+ `browserLanguage`
+ `browserName`
+ `browserVersion`
+ `countryCode`
+ `deviceType`
+ `domain`
+ `interaction`
+ `osName`
+ `osVersion`
+ `pageId`
+ `pageTags`
+ `pageTitle`
+ `pageUrl`
+ `parentPageId`
+ `platformType`
+ `referrerUrl`
+ `subdivisionCode`
+ `title`
+ `url`
+ `version`

**注意**  
如果屬性包含無效的鍵或值，或者已達到每個事件 10 個自訂屬性的限制，CloudWatch RUM 會從 RUM 事件中移除自訂屬性。

## 新增工作階段屬性
<a name="CloudWatch-RUM-session-attributes"></a>

如果您設定自訂工作階段屬性，屬性會新增至工作階段中的所有事件。您可以使用 `addSessionAttributes` 命令在 CloudWatch RUM Web 用戶端初始化期間或在執行階段期間來設定工作階段屬性。

例如，您可以將應用程式的版本新增為工作階段屬性。然後，在 CloudWatch RUM 主控台中，您可以依版本篩選錯誤，找出錯誤率增加的情況是否與應用程式的某個特定版本相關聯。

**在初始化期間新增工作階段屬性 (NPM 範例)**

粗體的程式碼區段會新增工作階段屬性。

```
import { AwsRum, AwsRumConfig } from 'aws-rum-web';

try {
  const config: AwsRumConfig = {
    allowCookies: true,
    endpoint: "https://dataplane.rum.us-west-2.amazonaws.com",
    guestRoleArn: "arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth",
    identityPoolId: "us-west-2:00000000-0000-0000-0000-000000000000",
    sessionSampleRate: 1,
    telemetries: ['errors', 'performance'],
    sessionAttributes: {
        applicationVersion: "1.3.8"
    }
  };

  const APPLICATION_ID: string = '00000000-0000-0000-0000-000000000000';
  const APPLICATION_VERSION: string = '1.0.0';
  const APPLICATION_REGION: string = 'us-west-2';

  const awsRum: AwsRum = new AwsRum(
    APPLICATION_ID,
    APPLICATION_VERSION,
    APPLICATION_REGION,
    config
  );
} catch (error) {
  // Ignore errors thrown during CloudWatch RUM web client initialization
}
```

**在執行階段期間新增工作階段屬性 (NPM 範例)**

```
awsRum.addSessionAttributes({ 
    applicationVersion: "1.3.8"    
})
```

**在初始化期間新增工作階段屬性 (內嵌指令碼範例)**

粗體的程式碼區段會新增工作階段屬性。

```
<script>
    (function(n,i,v,r,s,c,u,x,z){...})(
        'cwr',
        '00000000-0000-0000-0000-000000000000',
        '1.0.0',
        'us-west-2',
        'https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',
        {
            sessionSampleRate:1,
            guestRoleArn:'arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth',
            identityPoolId:'us-west-2:00000000-0000-0000-0000-000000000000',
            endpoint:'https://dataplane.rum.us-west-2.amazonaws.com',
            telemetries:['errors','http','performance'],
            allowCookies:true,
            sessionAttributes: {
                applicationVersion: "1.3.8"
            }
        }
    );
</script>
```

**在執行階段期間新增工作階段屬性 (內嵌指令碼範例)**

```
<script>
    function addSessionAttribute() {
        cwr('addSessionAttributes', {
            applicationVersion: "1.3.8"
        })
    }
            
</script>
```

## 新增頁面屬性
<a name="CloudWatch-RUM-page-attributes"></a>

如果您設定自訂頁面屬性，這些屬性會新增至目前頁面上的所有事件。您可以使用 `recordPageView` 命令在 CloudWatch RUM Web 用戶端初始化期間或在執行階段期間設定頁面屬性。

例如，您可以新增頁面範本作為頁面屬性。然後，在 CloudWatch RUM 主控台中，您可以依頁面範本篩選錯誤，找出錯誤率增加的情況是否與應用程式的某個特定頁面範本相關聯。

**在初始化期間新增頁面屬性 (NPM 範例)**

粗體的程式碼區段會新增頁面屬性。

```
const awsRum: AwsRum = new AwsRum(
    APPLICATION_ID,
    APPLICATION_VERSION,
    APPLICATION_REGION,
    { disableAutoPageView:  true // optional }
);
awsRum.recordPageView({  
    pageId:'/home',  
    pageAttributes: {
      template: 'artStudio'
    }
});
const credentialProvider = new CustomCredentialProvider();
if(awsCreds) awsRum.setAwsCredentials(credentialProvider);
```

**在執行階段期間新增頁面屬性 (NPM 範例)**

```
awsRum.recordPageView({ 
    pageId: '/home', 
    pageAttributes: {
        template: 'artStudio'
    } 
});
```

**在初始化期間新增頁面屬性 (內嵌指令碼範例)**

粗體的程式碼區段會新增頁面屬性。

```
<script>
    (function(n,i,v,r,s,c,u,x,z){...})(
        'cwr',
        '00000000-0000-0000-0000-000000000000',
        '1.0.0',
        'us-west-2',
        'https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',
        {
            disableAutoPageView: true //optional
        }
    );
    cwr('recordPageView', { 
       pageId: '/home',  
       pageAttributes: {
           template: 'artStudio'
       }
    });
    const awsCreds = localStorage.getItem('customAwsCreds');
    if(awsCreds) cwr('setAwsCredentials', awsCreds)
</script>
```

**在執行階段期間新增頁面屬性 (內嵌指令碼範例)**

```
<script>
    function recordPageView() {
        cwr('recordPageView', { 
            pageId: '/home', 
            pageAttributes: {
                template: 'artStudio'
            }
        });
    }        
</script>
```

## 在主控台中依中繼資料屬性進行篩選
<a name="CloudWatch-RUM-custom-attiributes-console"></a>

若要使用任何內建或自訂中繼資料屬性篩選 CloudWatch RUM 主控台中的視覺化效果，請使用搜尋列。在搜尋列中，您可以 **key=value** 的形式指定多達 20 個篩選條件，以套用至視覺化效果。例如，若僅要篩選 Chrome 瀏覽器的資料，您可以新增篩選條件用語 **browserName=Chrome**。

根據預設，CloudWatch RUM 主控台會擷取 100 個最常見的屬性鍵值，顯示在搜尋列的下拉式清單中。若要將更多中繼資料屬性新增為篩選條件用語，請在搜尋列中輸入完整的屬性鍵值。

一個篩選條件最多可包含 20 個篩選條件用語，每個應用程式監視器最多可儲存 20 個篩選條件。儲存篩選條件時，篩選條件會儲存在 **Saved filters** (已儲存的篩選條件) 下拉式清單中。您也可以刪除儲存的篩選條件。