本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 Amazon X-Ray API 配置采样、分组和加密设置
配置

Amazon X-Ray APIs 用于配置[采样规则](xray-console-sampling.md)、组规则和[加密设置](xray-console-encryption.md)。

**Topics**
+ [

## 加密设置
](#xray-api-configuration-encryption)
+ [

## 采样规则
](#xray-api-configuration-sampling)
+ [

## 组
](#xray-api-configuration-groups)

## 加密设置


[https://docs.amazonaws.cn/xray/latest/api/API_PutEncryptionConfig.html](https://docs.amazonaws.cn/xray/latest/api/API_PutEncryptionConfig.html)用于指定用于加密的 Amazon Key Management Service (Amazon KMS) 密钥。

**注意**  
X-Ray 不支持非对称 KMS 密钥。

```
$ aws xray put-encryption-config --type KMS --key-id alias/aws/xray
{
    "EncryptionConfig": {
        "KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
        "Status": "UPDATING",
        "Type": "KMS"
    }
}
```

对于密钥 ID，您可以使用别名（如示例中所示）、密钥 ID 或 Amazon 资源名称 (ARN)。

使用 [https://docs.amazonaws.cn/xray/latest/api/API_GetEncryptionConfig.html](https://docs.amazonaws.cn/xray/latest/api/API_GetEncryptionConfig.html) 获取当前配置。X-Ray 应用设置后，状态将从 `UPDATING` 变为 `ACTIVE`。

```
$ aws xray get-encryption-config
{
    "EncryptionConfig": {
        "KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
        "Status": "ACTIVE",
        "Type": "KMS"
    }
}
```

要停止使用 KMS 密钥并使用默认加密，请将加密类型设置为 `NONE`。

```
$ aws xray put-encryption-config --type NONE
{
    "EncryptionConfig": {
        "Status": "UPDATING",
        "Type": "NONE"
    }
}
```

## 采样规则


您可以使用 X-Ray API 管理账户中的[采样规则](xray-console-sampling.md)。有关添加和管理标签的更多信息，请参阅[标记 X-Ray 采样规则和组](xray-tagging.md)。

利用 [https://docs.amazonaws.cn/xray/latest/api/API_GetSamplingRules.html](https://docs.amazonaws.cn/xray/latest/api/API_GetSamplingRules.html) 获取所有采样规则。

```
$ aws xray get-sampling-rules
{
    "SamplingRuleRecords": [
        {
            "SamplingRule": {
                "RuleName": "Default",
                "RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
                "ResourceARN": "*",
                "Priority": 10000,
                "FixedRate": 0.05,
                "ReservoirSize": 1,
                "ServiceName": "*",
                "ServiceType": "*",
                "Host": "*",
                "HTTPMethod": "*",
                "URLPath": "*",
                "Version": 1,
                "Attributes": {}
            },
            "CreatedAt": 0.0,
            "ModifiedAt": 1529959993.0
        }
    ]
}
```

默认规则应用于所有与任何其他规则都不匹配的请求。这是优先级最低的规则，无法删除。但是，您可以使用 [https://docs.amazonaws.cn/xray/latest/api/API_UpdateSamplingRule.html](https://docs.amazonaws.cn/xray/latest/api/API_UpdateSamplingRule.html) 更改速率和容器大小。

**Example [https://docs.amazonaws.cn/xray/latest/api/API_UpdateSamplingRule.html](https://docs.amazonaws.cn/xray/latest/api/API_UpdateSamplingRule.html) 的 API 输入 10000-default.json**  

```
{
    "SamplingRuleUpdate": {
        "RuleName": "Default",
        "FixedRate": 0.01,
        "ReservoirSize": 0
    }
}
```

以下示例使用前一个文件作为输入，将默认规则更改为没有容器的百分之一。标签是可选的。如果选择添加标签，则标签键是必填，标签值为选填。要从采样规则中移除现有标签，请使用 [UntagResource](https://docs.amazonaws.cn/xray/latest/api/API_UntagResource.html)

```
$ aws xray update-sampling-rule --cli-input-json file://1000-default.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
    "SamplingRuleRecords": [
        {
            "SamplingRule": {
                "RuleName": "Default",
                "RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
                "ResourceARN": "*",
                "Priority": 10000,
                "FixedRate": 0.01,
                "ReservoirSize": 0,
                "ServiceName": "*",
                "ServiceType": "*",
                "Host": "*",
                "HTTPMethod": "*",
                "URLPath": "*",
                "Version": 1,
                "Attributes": {}
            },
            "CreatedAt": 0.0,
            "ModifiedAt": 1529959993.0
        },
```

利用 [https://docs.amazonaws.cn/xray/latest/api/API_CreateSamplingRule.html](https://docs.amazonaws.cn/xray/latest/api/API_CreateSamplingRule.html) 创建更多采样规则。创建规则时，大多数规则字段都是必填字段。以下示例将创建两个规则。第一条规则为 Scorekeeep 示例应用程序设置了基本频率。它匹配 API 提供的所有不符合更高优先级规则的请求。

**Example [https://docs.amazonaws.cn/xray/latest/api/API_UpdateSamplingRule.html](https://docs.amazonaws.cn/xray/latest/api/API_UpdateSamplingRule.html) 的 API 输入 9000-base-scorekeep.json**  

```
{
    "SamplingRule": {
        "RuleName": "base-scorekeep",
        "ResourceARN": "*",
        "Priority": 9000,
        "FixedRate": 0.1,
        "ReservoirSize": 5,
        "ServiceName": "Scorekeep",
        "ServiceType": "*",
        "Host": "*",
        "HTTPMethod": "*",
        "URLPath": "*",
        "Version": 1
    }
}
```

第二条规则也应用于 Scorekeeep，但它的优先级更高，也更具体。此规则为轮询请求设置了非常低的采样率。这些是客户端每隔几秒钟发出的 GET 请求，用于检查游戏状态是否发生变化。

**Example [https://docs.amazonaws.cn/xray/latest/api/API_UpdateSamplingRule.html](https://docs.amazonaws.cn/xray/latest/api/API_UpdateSamplingRule.html) 的 API 输入 5000-polling-scorekeep.json**  

```
{
    "SamplingRule": {
        "RuleName": "polling-scorekeep",
        "ResourceARN": "*",
        "Priority": 5000,
        "FixedRate": 0.003,
        "ReservoirSize": 0,
        "ServiceName": "Scorekeep",
        "ServiceType": "*",
        "Host": "*",
        "HTTPMethod": "GET",
        "URLPath": "/api/state/*",
        "Version": 1
    }
}
```

标签是可选的。如果选择添加标签，则标签键是必填，标签值为选填。

```
$ aws xray create-sampling-rule --cli-input-json file://5000-polling-scorekeep.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
    "SamplingRuleRecord": {
        "SamplingRule": {
            "RuleName": "polling-scorekeep",
            "RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
            "ResourceARN": "*",
            "Priority": 5000,
            "FixedRate": 0.003,
            "ReservoirSize": 0,
            "ServiceName": "Scorekeep",
            "ServiceType": "*",
            "Host": "*",
            "HTTPMethod": "GET",
            "URLPath": "/api/state/*",
            "Version": 1,
            "Attributes": {}
        },
        "CreatedAt": 1530574399.0,
        "ModifiedAt": 1530574399.0
    }
}
$ aws xray create-sampling-rule --cli-input-json file://9000-base-scorekeep.json
{
    "SamplingRuleRecord": {
        "SamplingRule": {
            "RuleName": "base-scorekeep",
            "RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/base-scorekeep",
            "ResourceARN": "*",
            "Priority": 9000,
            "FixedRate": 0.1,
            "ReservoirSize": 5,
            "ServiceName": "Scorekeep",
            "ServiceType": "*",
            "Host": "*",
            "HTTPMethod": "*",
            "URLPath": "*",
            "Version": 1,
            "Attributes": {}
        },
        "CreatedAt": 1530574410.0,
        "ModifiedAt": 1530574410.0
    }
}
```

要删除采样规则，请使用 [https://docs.amazonaws.cn/xray/latest/api/API_DeleteSamplingRule.html](https://docs.amazonaws.cn/xray/latest/api/API_DeleteSamplingRule.html)。

```
$ aws xray delete-sampling-rule --rule-name polling-scorekeep
{
    "SamplingRuleRecord": {
        "SamplingRule": {
            "RuleName": "polling-scorekeep",
            "RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
            "ResourceARN": "*",
            "Priority": 5000,
            "FixedRate": 0.003,
            "ReservoirSize": 0,
            "ServiceName": "Scorekeep",
            "ServiceType": "*",
            "Host": "*",
            "HTTPMethod": "GET",
            "URLPath": "/api/state/*",
            "Version": 1,
            "Attributes": {}
        },
        "CreatedAt": 1530574399.0,
        "ModifiedAt": 1530574399.0
    }
}
```

## 组


您可以使用 X-Ray API 管理您账户中的组。组是由筛选条件表达式定义的跟踪的集合。您可以使用群组来生成其他服务图表并提供 Amazon CloudWatch 指标。请参阅 [从 Amazon X-Ray 获取数据](xray-api-gettingdata.md)，以了解有关通过 X-Ray API 使用服务图和指标的更多详细信息。有关组的更多信息，请参阅 [配置组](xray-console-groups.md)。有关添加和管理标签的更多信息，请参阅[标记 X-Ray 采样规则和组](xray-tagging.md)。

使用 `CreateGroup` 创建一个组。标签是可选的。如果选择添加标签，则标签键是必填，标签值为选填。

```
$ aws xray create-group --group-name "TestGroup" --filter-expression "service(\"example.com\") {fault}" --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
    "GroupName": "TestGroup",
    "GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
    "FilterExpression": "service(\"example.com\") {fault OR error}"
}
```

获取所有包含 `GetGroups` 的现有组。

```
$ aws xray get-groups
{
    "Groups": [
        {
            "GroupName": "TestGroup",
            "GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
            "FilterExpression": "service(\"example.com\") {fault OR error}"
        },
		{
            "GroupName": "TestGroup2",
            "GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup2/UniqueID",
            "FilterExpression": "responsetime > 2"
        }
    ],
	"NextToken": "tokenstring"
}
```

更新包含 `UpdateGroup` 的组。标签是可选的。如果选择添加标签，则标签键是必填，标签值为选填。要从群组中移除现有标签，请使用[UntagResource](https://docs.amazonaws.cn/xray/latest/api/API_UntagResource.html)。

```
$ aws xray update-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" --filter-expression "service(\"example.com\") {fault OR error}" --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]
{
    "GroupName": "TestGroup",
    "GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
    "FilterExpression": "service(\"example.com\") {fault OR error}"
}
```

删除包含 `DeleteGroup` 的组。

```
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" 
    {
    }
```