# データセットを管理する
<a name="datasets-manage"></a>

このトピックでは、データセットの作成、取得、一覧表示、更新、削除について説明します。

## データセットを作成する
<a name="datasets-create"></a>

`CreateDataset` API は新しい評価データセットを作成します。これは非同期オペレーション (HTTP 202) です。`ACTIVE`取り込みが完了すると、データセットは から `CREATING` に移行します。

 **必須パラメータ:** `datasetName` (英数字とアンダースコアのみ、`^[a-zA-Z][a-zA-Z0-9_]{0,47}$`)、`schemaType`、および `source` (インライン例または S3 URI)。

 **オプションパラメータ:** `description`、 `kmsKeyArn` (カスタマーマネージド暗号化キー、作成後に変更不可 — [「データセット暗号化](datasets-encryption.md)」を参照)`tags`、。

次の例は、データセットを作成する方法を示しています。

**Example**  

1. 

   ```
   # Add a dataset to your project
   agentcore add dataset --name my_eval_dataset \
       --schema-type AGENTCORE_EVALUATION_PREDEFINED_V1
   
   # Edit the generated JSONL file with your scenarios
   # File location: agentcore/datasets/my_eval_dataset.jsonl
   
   # Deploy to create the dataset in your AWS account
   agentcore deploy
   ```

   これにより、ローカル JSONL ファイルが作成され、データセットがプロジェクト設定に登録されます。`agentcore deploy` を実行してデータセットリソースを作成し、例を サービスに同期します。
**注記**  
AgentCoreプロジェクトディレクトリ内 ( で作成) からこれを実行します`agentcore create`。

1. 

   ```
   from bedrock_agentcore.evaluation import DatasetClient
   
   client = DatasetClient(region_name="us-west-2")
   
   # Create with inline examples (polls until ACTIVE)
   ds = client.create_dataset_and_wait(
       datasetName="customer_support_scenarios",
       schemaType="AGENTCORE_EVALUATION_PREDEFINED_V1",
       source={
           "inlineExamples": {
               "examples": [
                   {
                       "scenario_id": "TC-01",
                       "turns": [{"input": "What is my balance?", "expected_response": "Your balance is $50."}],
                       "assertions": ["Response includes a dollar amount"],
                   }
               ]
           }
       },
   )
   print(f"Dataset ID: {ds['datasetId']}, Status: {ds['status']}")
   
   # Create with S3 source
   ds = client.create_dataset_and_wait(
       datasetName="my_s3_dataset",
       schemaType="AGENTCORE_EVALUATION_PREDEFINED_V1",
       source={"s3Source": {"s3Uri": "s3://my-bucket/scenarios.jsonl"}},
   )
   ```
**注記**  
S3 取り込みの場合、JSONL ファイルの各行に `exampleId`フィールドが含まれている必要があります。S3 バケットは、発信者の認証情報を使用してアクセスできる必要があります。

1. 

   ```
   import boto3
   import time
   
   client = boto3.client('bedrock-agentcore-control')
   
   response = client.create_dataset(
       datasetName='customer_support_scenarios',
       schemaType='AGENTCORE_EVALUATION_PREDEFINED_V1',
       source={
           'inlineExamples': {
               'examples': [
                   {
                       'scenario_id': 'TC-01',
                       'turns': [{'input': 'What is my balance?', 'expected_response': 'Your balance is $50.'}],
                       'assertions': ['Response includes a dollar amount'],
                   }
               ]
           }
       }
   )
   dataset_id = response['datasetId']
   
   # Create with S3 source
   response = client.create_dataset(
       datasetName='my_s3_dataset',
       schemaType='AGENTCORE_EVALUATION_PREDEFINED_V1',
       source={
           's3Source': {'s3Uri': 's3://my-bucket/scenarios.jsonl'}
       }
   )
   
   # Poll until ACTIVE
   while True:
       ds = client.get_dataset(datasetId=dataset_id)
       if ds['status'] in ('ACTIVE', 'CREATE_FAILED'):
           break
       time.sleep(2)
   ```

1. 

   ```
   # Create with inline examples
   aws bedrock-agentcore-control create-dataset \
       --dataset-name "customer_support_scenarios" \
       --schema-type AGENTCORE_EVALUATION_PREDEFINED_V1 \
       --source '{"inlineExamples": {"examples": [{"scenario_id": "TC-01", "turns": [{"input": "What is my balance?", "expected_response": "Your balance is $50."}], "assertions": ["Response includes a dollar amount"]}]}}'
   
   # Create with S3 source
   aws bedrock-agentcore-control create-dataset \
       --dataset-name "my_s3_dataset" \
       --schema-type AGENTCORE_EVALUATION_PREDEFINED_V1 \
       --source '{"s3Source": {"s3Uri": "s3://my-bucket/scenarios.jsonl"}}'
   
   # Poll until ACTIVE
   aws bedrock-agentcore-control get-dataset \
       --dataset-id my-dataset-id
   ```

## データセットを取得する
<a name="datasets-get"></a>

`GetDataset` API は、データセットコンテンツのデータセットメタデータ、ステータス、サンプル数、および署名付きダウンロード URL を取得します。デフォルトでは、 はドラフトを読み取り、公開されたバージョン`datasetVersion`に を指定します。

`downloadUrl` は、ファイル全体の署名付き S3 URL です`dataset.jsonl`。認証ヘッダーなしでプレーン HTTP GET リクエストでダウンロードできます。

次の例は、データセットを取得する方法を示しています。

**Example**  

1. 

   ```
   # Show dataset deployment status and metadata
   agentcore status --type dataset
   
   # Download dataset content to your local JSONL file (default: Draft)
   agentcore dataset download --name my_eval_dataset
   
   # Download a specific published version
   agentcore dataset download --name my_eval_dataset --version 1
   ```

1. 

   ```
   from bedrock_agentcore.evaluation import DatasetClient
   
   client = DatasetClient(region_name="us-west-2")
   
   # Get dataset (default: Draft)
   ds = client.get_dataset(datasetId="my-dataset-id")
   print(f"Status: {ds['status']}, Examples: {ds['exampleCount']}")
   print(f"Download URL: {ds['downloadUrl']}")
   
   # Get a specific published version
   ds_v1 = client.get_dataset(datasetId="my-dataset-id", datasetVersion="1")
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   response = client.get_dataset(datasetId='my-dataset-id')
   print(f"Status: {response['status']}, Examples: {response['exampleCount']}")
   
   # Download the dataset content via presigned URL
   if 'downloadUrl' in response:
       import requests
       data = requests.get(response['downloadUrl'])
       print(data.text)
   
   # Get a specific published version
   response = client.get_dataset(datasetId='my-dataset-id', datasetVersion='1')
   ```

1. 

   ```
   # Get dataset (default: Draft)
   aws bedrock-agentcore-control get-dataset \
       --dataset-id my-dataset-id
   
   # Get a specific published version
   aws bedrock-agentcore-control get-dataset \
       --dataset-id my-dataset-id \
       --dataset-version 1
   ```

## データセットを一覧表示する
<a name="datasets-list"></a>

`ListDatasets` API は、アカウントとリージョンのデータセットのページ分割されたリストを返します。

次の例は、データセットを一覧表示する方法を示しています。

**Example**  

1. 

   ```
   agentcore status --type dataset
   ```

1. 

   ```
   from bedrock_agentcore.evaluation import DatasetClient
   
   client = DatasetClient(region_name="us-west-2")
   
   response = client.list_datasets()
   for dataset in response["datasets"]:
       print(f"  {dataset['datasetName']} ({dataset['status']})")
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   response = client.list_datasets()
   for dataset in response['datasets']:
       print(f"  {dataset['datasetName']} ({dataset['status']})")
   ```

1. 

   ```
   aws bedrock-agentcore-control list-datasets
   ```

## データセットを更新する
<a name="datasets-update"></a>

`UpdateDataset` API はデータセットメタデータを更新します。これは同期オペレーション (HTTP 200) です。更新`tags`できるのは `description`と のみです。`datasetName`、`schemaType`、および `kmsKeyArn`は作成後に変更できません。

データセットは、`ACTIVE`、`UPDATE_FAILED`、または `CREATE_FAILED`ステータスである必要があります。

次の例は、データセットメタデータを更新する方法を示しています。

**Example**  

1. AgentCore CLI でデータセットを更新するには、 `agentcore.json` ファイル内のデータセット設定を直接編集してから、再デプロイします。

   ```
   agentcore deploy
   ```

   を開き`agentcore.json`、`datasets`配列内のデータセットを見つけ、その を変更してから`description`、 を実行します`agentcore deploy`。変更はデプロイ後に有効になります。
**注記**  
AgentCoreプロジェクトディレクトリ内 ( で作成) からこれを実行します`agentcore create`。

1. 

   ```
   from bedrock_agentcore.evaluation import DatasetClient
   
   client = DatasetClient(region_name="us-west-2")
   
   client.update_dataset(datasetId="my-dataset-id", description="Updated description")
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   client.update_dataset(datasetId='my-dataset-id', description='Updated description')
   ```

1. 

   ```
   aws bedrock-agentcore-control update-dataset \
       --dataset-id my-dataset-id \
       --description "Updated description"
   ```

## データセットを削除する
<a name="datasets-delete"></a>

`DeleteDataset` API はデータセットを削除します。これは非同期オペレーション (HTTP 202) です。
+  **完全削除** ( を省略`datasetVersion`): すべてのバージョン、ドラフト、データセットレコードを削除します。
+  **バージョン固有の削除** (整数`datasetVersion`で指定): その公開されたバージョンのみを削除します。

データセットは、`ACTIVE`、`CREATE_FAILED`、`UPDATE_FAILED`、または `DELETE_FAILED`ステータスである必要があります。

**注記**  
バージョン固有の削除には、整数バージョン番号のみを使用できます。

次の例は、データセットを削除する方法を示しています。

**Example**  

1. 

   ```
   # Delete a specific published version
   agentcore dataset remove-version 1 --name my_eval_dataset
   
   # Delete entire dataset
   agentcore remove dataset --name my_eval_dataset
   agentcore deploy
   ```

1. 

   ```
   from bedrock_agentcore.evaluation import DatasetClient
   
   client = DatasetClient(region_name="us-west-2")
   
   # Delete a specific published version
   client.delete_dataset_and_wait(datasetId="my-dataset-id", datasetVersion="1")
   
   # Delete entire dataset (polls until complete)
   client.delete_dataset_and_wait(datasetId="my-dataset-id")
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   # Delete a specific published version
   client.delete_dataset(datasetId='my-dataset-id', datasetVersion='1')
   
   # Delete entire dataset
   client.delete_dataset(datasetId='my-dataset-id')
   ```

1. 

   ```
   # Delete a specific published version
   aws bedrock-agentcore-control delete-dataset \
       --dataset-id my-dataset-id \
       --dataset-version 1
   
   # Delete entire dataset
   aws bedrock-agentcore-control delete-dataset \
       --dataset-id my-dataset-id
   ```