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

# 新增可搜尋的中繼資料至特徵
<a name="feature-store-add-metadata"></a>

在 Amazon SageMaker Feature Store 中，您可以搜尋所有特徵。若要讓您的特徵更容易被搜尋，您可以在其中新增中繼資料。您可以新增以下類型的中繼資料：
+ 描述 – 特徵的可搜尋描述。
+ 參數 – 可搜尋的鍵值對。

描述最長可為 255 個字元。對於參數，您必須在搜尋中指定鍵值對。您最多可以新增 25 個參數。

若要更新特徵的中繼資料，您可以使用主控台或 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateFeatureMetadata.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateFeatureMetadata.html) 操作。

## 如何將可搜尋的中繼資料新增至您的特徵
<a name="feature-store-add-metadata-how-to"></a>

您可以使用主控台或 Amazon SageMaker Feature Store API，將可搜尋的中繼資料新增至您的特徵。透過主控台使用 Feature Store 的指示取決於您是否已啟用 [Amazon SageMaker Studio](studio-updated.md) 或 [Amazon SageMaker Studio Classic](studio.md) 做為預設體驗。

### 如果 Studio 是您的預設體驗 (主控台)，請將可搜尋的中繼資料新增至特徵
<a name="feature-store-add-metadata-how-to-with-studio-updated"></a>

1. 遵循 [啟動 Amazon SageMaker Studio](studio-updated-launch.md) 中的指示開啟 Studio 主控台。

1. 在左側導覽窗格中，選擇**資料**以展開下拉式清單。

1. 從下拉式清單中，選擇 **Feature Store**。

1. (選用) 若要檢視您的特徵，請選擇**我的帳戶**。若要檢視共用特徵，請選擇**跨帳戶**。

1. 若要檢視您的特徵群組，請在**特徵目錄**索引標籤下選擇**我的帳戶**。

1. 在**特徵目錄**索引標籤下，選擇**跨帳戶**來檢視其他人讓您可探索的特徵群組。在**建立者**下，您可以檢視特徵群組的資源擁有者帳戶 ID。

1. 您可以從**搜尋**下拉式清單中搜尋您的特徵。
   + (選用) 若要篩選搜尋，請選擇**搜尋**下拉式清單旁邊的篩選條件圖示。您可以使用篩選條件來指定搜尋結果中的參數或日期範圍。如果您搜尋參數，請同時指定其金鑰和值。若要更輕鬆地找到特徵，您可以指定時間範圍或取消選取不想查詢的資料欄。
   + 對於共用資源，如果您具有從資源擁有者帳戶授與的適當存取許可，則只能編輯特徵群組中繼資料或特徵定義。僅具有探索能力許可不允許您編輯中繼資料或特徵定義。如需如何授與存取許可的詳細資訊，請參閱 [啟用跨帳戶存取權](feature-store-cross-account-access.md)。

1. 選擇您的特徵。

1. 選擇**編輯中繼資料**。

1. 在**描述**欄位中新增或更新描述。

1. 在**參數**下的**參數**欄位中，指定參數的鍵值對。

1. (可選) 選擇**新增參數**以新增其他參數。

1. 選擇**儲存變更**。

1. 選擇**確認**。

### 使用 SDK for Python (Boto3) 將可搜尋的中繼資料新增至您的特徵
<a name="feature-store-add-metadata-how-to-with-sdk"></a>

本節中的程式碼使用 適用於 Python (Boto3) 的 AWS SDK 中的 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateFeatureMetadata.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateFeatureMetadata.html) 操作，針對不同案例將可搜尋的中繼資料新增至您的特徵。如需要提交查詢的其他語言的相關資訊，請參閱 *Amazon SageMaker API 參考*中的[另請參閱](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateFeatureMetadata.html#API_Search_SeeAlso)。

如需更多特徵存放區範例和資源，請參閱 [Amazon SageMaker Feature Store 資源](feature-store-resources.md)。

------
#### [ Add a list of parameters to a feature ]

若要將參數清單新增至特徵，請為下列欄位指定值：
+ `FeatureGroupName`
+ `Feature`
+ `Parameters`

下列範例程式碼使用 適用於 Python (Boto3) 的 AWS SDK 來新增兩個參數。

```
sagemaker_client.update_feature_metadata(
    FeatureGroupName="feature_group_name",
    FeatureName="feature-name",
    ParameterAdditions=[
        {"Key": "example-key-0", "Value": "example-value-0"},
        {"Key": "example-key-1", "Value": "example-value-1"},
    ]
)
```

------
#### [ Add a description to a feature ]

若要將描述新增至特徵，請為下列欄位指定值：
+ `FeatureGroupName`
+ `Feature`
+ `Description`

```
sagemaker_client.update_feature_metadata(
    FeatureGroupName="feature-group-name",
    FeatureName="feature-name",
    Description="description"
)
```

------
#### [ Remove parameters for a feature ]

若要移除特徵的所有參數，請執行下列操作。

為下列欄位指定值：
+ `FeatureGroupName`
+ `Feature`

指定要在其 `ParameterRemovals` 移除之參數的鍵。

```
sagemaker_client.update_feature_metadata(
    FeatureGroupName="feature_group_name",
    FeatureName="feature-name",
        ParameterRemovals=[
        {"Key": "example-key-0"},
        {"Key": "example-key-1"},
    ]
)
```

------
#### [ Remove the description for a feature ]

若要移除特徵的描述，請執行下列操作。

為下列欄位指定值：
+ `FeatureGroupName`
+ `Feature`

指定 `Description` 的空字串。

```
sagemaker_client.update_feature_metadata(
    FeatureGroupName="feature-group-name",
    FeatureName="feature-name",
    Description=""
)
```

------

#### 範例程式碼
<a name="feature-store-add-metadata-python-sdk-example"></a>

更新特徵的中繼資料後，您可以透過 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeFeatureMetadata.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeFeatureMetadata.html) 操作查看您所做的更新。

下列程式碼使用 適用於 Python (Boto3) 的 AWS SDK完成範例工作流程。此範例程式碼可做到以下操作：

1. 設定您的 SageMaker AI 環境。

1. 建立特徵群組。

1. 將特徵新增至群組。

1. 將中繼資料新增至特徵。

如需更多特徵存放區範例和資源，請參閱 [Amazon SageMaker Feature Store 資源](feature-store-resources.md)。

##### 步驟 1：設定
<a name="feature-store-add-metadata-step-1"></a>

若要開始使用 Feature Store，請建立 SageMaker AI、boto3 和 Feature Store 工作階段。然後設定要用於特徵的 S3 儲存貯體。這是您的離線儲存。下列程式碼會使用 SageMaker AI 預設儲存貯體，並將自訂字首新增至其中。

**注意**  
您使用的角色必須附加下列受管政策：`AmazonS3FullAccess` 和 `AmazonSageMakerFeatureStoreAccess`。

```
# SageMaker Python SDK version 2.x is required
%pip install 'sagemaker>=2.0.0'
import sagemaker
import sys
```

```
import boto3
import pandas as pd
import numpy as np
import io
from sagemaker.session import Session
from sagemaker import get_execution_role
from botocore.exceptions import ClientError


prefix = 'sagemaker-featurestore-introduction'
role = get_execution_role()

sagemaker_session = sagemaker.Session()
region = sagemaker_session.boto_region_name
s3_bucket_name = sagemaker_session.default_bucket()
sagemaker_client = boto_session.client(service_name='sagemaker', region_name=region)
```

##### 步驟 2：建立特徵群組和新增特徵
<a name="feature-store-add-metadata-step-2"></a>

下列程式碼是使用特徵定義建立特徵群組的範例。

```
feature_group_name = "test-for-feature-metadata"
feature_definitions = [
    {"FeatureName": "feature-1", "FeatureType": "String"},
    {"FeatureName": "feature-2", "FeatureType": "String"},
    {"FeatureName": "feature-3", "FeatureType": "String"},
    {"FeatureName": "feature-4", "FeatureType": "String"},
    {"FeatureName": "feature-5", "FeatureType": "String"}
]
try:
    sagemaker_client.create_feature_group(
        FeatureGroupName=feature_group_name,
        RecordIdentifierFeatureName="feature-1",
        EventTimeFeatureName="feature-2",
        FeatureDefinitions=feature_definitions,
        OnlineStoreConfig={"EnableOnlineStore": True}
    )
except ClientError as e:
    if e.response["Error"]["Code"] == "ResourceInUse":
        pass
    else:
        raise e
```

##### 步驟 3：新增中繼資料
<a name="feature-store-add-metadata-step-3"></a>

在新增中繼資料之前，請使用此 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeFeatureGroup.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeFeatureGroup.html) 操作確保特徵群組的狀態為 `Created`。

```
sagemaker_client.describe_feature_group(
        FeatureGroupName=feature_group_name
    )
```

新增描述至特徵。

```
sagemaker_client.update_feature_metadata(
    FeatureGroupName=feature_group_name,
    FeatureName="feature-1",
    Description="new description"
)
```

您可以使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeFeatureMetadata.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeFeatureMetadata.html) 操作來查看您是否已成功更新特徵群組的描述。

```
    sagemaker_client.describe_feature_metadata(
    FeatureGroupName=feature_group_name,
    FeatureName="feature-1"
)
```

您也可以使用該操作將參數新增至特徵群組。

```
sagemaker_client.update_feature_metadata(
    FeatureGroupName=feature_group_name,
    FeatureName="feature-1",
    ParameterAdditions=[
        {"Key": "team", "Value": "featurestore"},
        {"Key": "org", "Value": "sagemaker"},
    ]
)
```

您可以再次透過該 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeFeatureMetadata.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeFeatureMetadata.html) 操作查看是否已成功新增參數。

```
    sagemaker_client.describe_feature_metadata(
    FeatureGroupName=feature_group_name,
    FeatureName="feature-1"
)
```