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

# 报告敏感数据位置的架构
<a name="findings-locate-sd-schema"></a>

Amazon Macie 使用标准化 JSON 结构存储有关在 Amazon Simple Storage Service (Amazon S3) 对象中发现的敏感数据的位置信息。这些结构用于敏感数据调查发现和敏感数据发现结果。对于敏感数据调查发现，这些结构是调查发现的 JSON 架构的一部分。要查看完整的 JSON 架构以了解调查发现，请参阅 *Amazon Macie API 参考*中的[调查发现](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html)。要了解有关敏感数据发现结果的更多信息，请参阅 [存储和保留敏感数据发现结果](discovery-results-repository-s3.md)。

**Topics**
+ [架构概览](#findings-locate-sd-schema-overview)
+ [架构详细信息和示例](#findings-locate-sd-schema-examples)

## 架构概览
<a name="findings-locate-sd-schema-overview"></a>

要报告 Amazon Macie 在受影响的 S3 对象中发现的敏感数据的位置，敏感数据调查发现和敏感数据发现结果的 JSON 架构包括一个 `customDataIdentifiers` 对象和一个 `sensitiveData` 对象。该 `customDataIdentifiers` 对象提供有关 Macie 使用[自定义数据标识符](custom-data-identifiers.md)检测到的数据的详细信息。该 `sensitiveData` 对象提供有关 Macie 使用[托管数据标识符](managed-data-identifiers.md)检测到的数据的详细信息。

每个 `customDataIdentifiers` 和 `sensitiveData` 对象都包含一个或多个 `detections` 数组：
+ 在 `customDataIdentifiers` 对象中，`detections` 数组表示哪些自定义数据标识符检测到数据并得出了调查发现。对于每个自定义数据标识符，该数组还会指示该标识符检测到的数据出现次数。它还可以指示标识符检测到的数据的位置。
+ 在 `sensitiveData` 对象中，`detections` 数组指示 Macie 使用托管数据标识符检测到的敏感数据的类型。对于每种类型的敏感数据，该数组还会指示数据的出现次数，还可以指示数据的位置。

对于敏感数据调查发现，`detections` 数组可以包含 1-15 个 `occurrences` 对象。每个 `occurrences` 对象都指定 Macie 在何处检测到特定类型的敏感数据的单个事件。

例如，以下 `detections` 数组表示 Macie 在 CSV 文件中发现的三次敏感数据（美国社会安全号码）的位置。

```
"sensitiveData": [
     {
       "category": "PERSONAL_INFORMATION",
       "detections": [
          {
             "count": 30,
             "occurrences": {
                "cells": [
                   {
                      "cellReference": null,
                      "column": 1,
                      "columnName": "SSN",
                      "row": 2
                   },
                   {
                      "cellReference": null,
                      "column": 1,
                      "columnName": "SSN",
                      "row": 3
                   },
                   {
                      "cellReference": null,
                      "column": 1,
                      "columnName": "SSN",
                      "row": 4
                   }
                ]
             },
             "type": "USA_SOCIAL_SECURITY_NUMBER"
           }
```

`detections` 数组中 `occurrences` 对象的位置和数量因 Macie 在自动敏感数据发现分析周期或敏感数据发现作业运行期间检测到的敏感数据的类别、类型和出现次数而异。对于每个分析周期或作业运行，Macie 都使用*深度优先搜索*算法，使用 Macie 在 S3 对象中检测到的 1-15 次敏感数据的位置数据填充结果调查发现。这些事件表明受影响的 S3 存储桶和对象可能包含的敏感数据的类别和类型。

`occurrences` 对象可以包含以下任何结构，具体取决于受影响的 S3 对象的文件类型或存储格式：
+ `cells` 数组‬：此数组适用于微软 Excel 工作簿、CSV 文件和 TSV 文件。此数组中的对象指定 Macie 检测到其中存在敏感数据的单元格或字段。
+ `lineRanges`数组‬：此数组适用于电子邮件 (EML) 文件以及 CSV、JSON、JSON Lines 和 TSV 文件以外的非二进制文本文件，例如 HTML、TXT 和 XML 文件。此数组中的对象指定 Macie 检测到存在敏感数据的一行或包含范围的行，以及数据在指定行上的位置。

  在某些情况下，`lineRanges` 数组中的对象以另一种类型的数组支持的文件类型或存储格式指定敏感数据检测的位置。这些情况是：在其他结构化文件的非结构化部分中检测到的情况，例如文件中的注释；在 Macie 分析为纯文本的格式错误中检测到的情况；以及 Macie 在 CSV 或 TSV 文件中检测到包含敏感数据的一个或多个列名。
+ `offsetRanges` 数组‬：此数组保留供将来使用。如果存在此数组，则其值为空。
+ `pages` 数组‬：此数组适用于 Adobe 便携式文档格式 (PDF) 文件。此数组中的对象指定 Macie 检测到其中存在敏感数据的页面。
+ `records` 数组‬：此数组适用于 Apache Avro 对象容器、Apache Parquet 文件、JSON 文件和 JSON Lines 文件。对于 Avro 对象容器和 Parquet 文件，此数组中的对象指定记录索引和 Macie 检测到存在敏感数据的记录中字段的路径。对于 JSON 和 JSON Lines 文件，此数组中的对象指定 Macie 检测到其中存在敏感数据的字段或数组的路径。对于 JSON Lines 文件，它还指定包含数据的行的索引。

这些数组的内容因受影响的 S3 对象的文件类型或存储格式及其内容而异。

## 架构详细信息和示例
<a name="findings-locate-sd-schema-examples"></a>

Amazon Macie 会定制 JSON 结构的内容，以指示在特定类型的文件和内容中检测到敏感数据的位置。以下主题解释并提供了这些结构的示例。

**Topics**
+ [Cells 数组](#findings-locate-sd-schema-examples-cell)
+ [LineRanges 数组](#findings-locate-sd-schema-examples-linerange)
+ [Page 数组](#findings-locate-sd-schema-examples-page)
+ [记录数组](#findings-locate-sd-schema-examples-record)

有关敏感数据调查发现中可以包含的 JSON 结构的完整列表，请参阅 *Amazon Macie API 参考*中的[调查发现](https://docs.aws.amazon.com/macie/latest/APIReference/findings-describe.html)。

### Cells 数组
<a name="findings-locate-sd-schema-examples-cell"></a>

**适用于：**微软 Excel 工作簿、CSV 文件和 TSV 文件

在 `cells` 数组中，`Cell` 对象指定 Macie 检测到其中存在敏感数据的单元格或字段。下表描述了 `Cell` 对象中每个字段的用途。


| 字段 | Type | 说明 | 
| --- | --- | --- | 
| cellReference | 字符串 | 包含该事件的单元格的位置，作为绝对单元格引用。此字段仅适用于 Excel 工作簿。对于 CSV 和 TSV 文件，此值为空。 | 
| column | 整数 | 包含该事件的列的列编号。对于 Excel 工作簿，此值与列标识符的字母字符相关联，例如，1 用于 A 列，2 用于 B 列，依此类推。 | 
| columnName | 字符串 | 包含该事件的列名称（如果有）。 | 
| row | 整数 | 包含该事件的行的行号。 | 

以下示例显示了一个 `Cell` 对象的结构，该对象指定 Macie 在 CSV 文件中检测到的敏感数据出现的位置。

```
"cells": [
   {
      "cellReference": null,
      "column": 3,
      "columnName": "SSN",
      "row": 5
   }
]
```

在前面的示例中，调查发现表明 Macie 在文件第三列（名为 *SSN*）第五行的字段中检测到了敏感数据。

以下示例显示了一个 `Cell` 对象的结构，该对象指定 Macie 在 Excel 工作簿中检测到的敏感数据出现的位置。

```
"cells": [
   {
      "cellReference": "Sheet2!C5",
      "column": 3,
      "columnName": "SSN",
      "row": 5
   }
]
```

在前面的示例中，调查发现表明 Macie 在工作簿中名为 *Sheet2* 的工作表中检测到了敏感数据。在该工作表中，Macie 在第三列（C 列，名为 *SSN*）第五行的单元格中检测到敏感数据。

### LineRanges 数组
<a name="findings-locate-sd-schema-examples-linerange"></a>

**适用于：**电子邮件 (EML) 文件以及 CSV、JSON、JSON Lines 和 TSV 文件以外的非二进制文本文件，例如 HTML、TXT 和 XML 文件

在 `lineRanges` 数组中，`Range` 对象指定 Macie 检测到存在敏感数据的一行或包含范围的行，以及数据在指定行上的位置。

对于 `occurrences` 对象中其他类型的数组支持的文件类型，此对象通常为空。例外情况是：
+ 其他结构化文件的非结构化部分中的数据，例如文件中的注释。
+ 格式错误的文件中的数据，Macie 将其分析为纯文本。
+ 包含一个或多个列名的 CSV 或 TSV 文件，Macie 在其中检测到敏感数据。

下表描述了 `lineRanges` 数组的 `Range` 对象中每个字段的用途。


| 字段 | Type | 说明 | 
| --- | --- | --- | 
| end | 整数 | 从文件开头到事件结尾的行数。 | 
| start | 整数 | 从文件开头到事件开头的行数。 | 
| startColumn | 整数 | 从包含事件的内容的第一行开头（start）到事件开头的字符数，包括空格并从 1 开始计数。 | 

以下示例显示了一个 `Range` 对象的结构，该对象指定 Macie 在 TXT 文件中的单行上检测到的敏感数据出现的位置。

```
"lineRanges": [
   {
      "end": 1,
      "start": 1,
      "startColumn": 119
   }
]
```

在前面的示例中，调查发现表明 Macie 检测到文件的第一行中完全出现了敏感数据（邮寄地址）。出现的第一个字符是从该行开头开始的 119 个字符（含空格）。

以下示例显示了一个 `Range` 对象的结构，该对象指定了 TXT 文件中跨越多行的敏感数据出现的位置。

```
"lineRanges": [
   {
      "end": 54,
      "start": 51,
      "startColumn": 1
   }
]
```

在前面的示例中，调查发现表明 Macie 检测到存在跨越文件第 51 行到第 54 行的敏感数据（邮寄地址）。事件的第一个字符是文件第 51 行的第一个字符。

### Page 数组
<a name="findings-locate-sd-schema-examples-page"></a>

**适用于：**Adobe 便携式文档格式 (PDF) 文件

在 `pages` 数组中，`Page` 对象指定 Macie 检测到其中存在敏感数据的页面。对象包含一个 `pageNumber` 字段。该 `pageNumber` 字段存储一个整数，用于指定包含该事件的页面的页码。

以下示例显示了一个 `Page` 对象的结构，该对象指定 Macie 在 PDF 文件中检测到的敏感数据出现的位置。

```
"pages": [
   {
      "pageNumber": 10
   }
]
```

在前面的示例中，调查发现表明该文件的第 10 页包含该事件。

### 记录数组
<a name="findings-locate-sd-schema-examples-record"></a>

**适用于：**Apache Avro 对象容器、Apache Parquet 文件、JSON 文件和 JSON Lines 文件

对于 Avro 对象容器或 Parquet 文件，`records` 数组中的 `Record` 对象指定记录索引和 Macie 检测到存在敏感数据的记录中字段的路径。对于 JSON 和 JSON Lines 文件，`Record` 对象指定 Macie 检测到其中存在敏感数据的字段或数组的路径。对于 JSON Lines 文件，它还会指定包含该事件的行的索引。

下表描述了 `Record` 对象中每个字段的用途。


| 字段 | Type | 说明 | 
| --- | --- | --- | 
| jsonPath | 字符串 |  以 JSONPath 表达式的形式指向具体值的路径。 对于 Avro 对象容器或 Parquet 文件，这是记录 (`recordIndex`) 中包含具体值的字段的路径。对于 JSON 或 JSON Lines 文件，这是包含该事件的字段或数组的路径。如果数据是数组中的一个值，则路径还会指示哪个值包含该事件。 如果 Macie 在路径中任何元素的名称中检测到敏感数据，则 Macie 会从 `Record` 对象中省略该 `jsonPath` 字段。如果路径元素的名称超过 240 个字符，Macie 会通过删除名称开头的字符来截断该名称。如果生成的完整路径超过 250 个字符，Macie 还会从路径中的第一个元素开始截断路径，直到路径包含 250 个或更少的字符。  | 
| recordIndex | 整数 | 对于 Avro 对象容器或 Parquet 文件，包含该事件的记录的索引，从 0 开始。对于 JSON Lines 文件，从 0 开始表示包含该事件的行的行索引。此值始终 0 适用于 JSON 文件。 | 

以下示例显示了一个 `Record` 对象的结构，该对象指定 Macie 在 Parquet 文件中检测到的敏感数据出现的位置。

```
"records": [
   {
      "jsonPath": "$['abcdefghijklmnopqrstuvwxyz']",
      "recordIndex": 7663
   }
]
```

在前面的示例中，调查发现表明 Macie 在索引 7663（记录号 7664）的记录中检测到了敏感数据。在该记录中，Macie 在名为 `abcdefghijklmnopqrstuvwxyz` 的字段中检测到了敏感数据。记录中该字段的完整 JSON 路径为 `$.abcdefghijklmnopqrstuvwxyz`。该字段是根（外层级别）对象的直接后代。

以下示例还显示了 Macie 在 Parquet 文件中检测到的敏感数据出现时的 `Record` 对象结构。但是，在此示例中，Macie 截断了包含该匹配项的字段的名称，因为该名称超出了字符限制。

```
"records": [
   {
      "jsonPath": "$['...uvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz']",
      "recordIndex": 7663
   }
]
```

在前面的示例中，该字段是根（外层级别）对象的直接后代。

在以下示例中，同样对于 Macie 在 Parquet 文件中检测到的敏感数据，Macie 截断了包含该事件的字段的完整路径。完整路径超过字符限制。

```
"records": [
   {
      "jsonPath": "$..usssn2.usssn3.usssn4.usssn5.usssn6.usssn7.usssn8.usssn9.usssn10.usssn11.usssn12.usssn13.usssn14.usssn15.usssn16.usssn17.usssn18.usssn19.usssn20.usssn21.usssn22.usssn23.usssn24.usssn25.usssn26.usssn27.usssn28.usssn29['abcdefghijklmnopqrstuvwxyz']",
      "recordIndex": 2335
   }
]
```

在前面的示例中，调查发现表明 Macie 在索引 2335（记录号 2336）的记录中检测到了敏感数据。在该记录中，Macie 在名为 `abcdefghijklmnopqrstuvwxyz` 的字段中检测到了敏感数据。记录中该字段的完整 JSON 路径为：

`$['1234567890']usssn1.usssn2.usssn3.usssn4.usssn5.usssn6.usssn7.usssn8.usssn9.usssn10.usssn11.usssn12.usssn13.usssn14.usssn15.usssn16.usssn17.usssn18.usssn19.usssn20.usssn21.usssn22.usssn23.usssn24.usssn25.usssn26.usssn27.usssn28.usssn29['abcdefghijklmnopqrstuvwxyz']`

以下示例显示了一个 `Record` 对象的结构，该对象指定 Macie 在 JSON 文件中检测到的敏感数据出现的位置。在此示例中，出现的是数组中的特定值。

```
"records": [
   {
      "jsonPath": "$.access.key[2]",
      "recordIndex": 0
   }
]
```

在前面的示例中，调查发现表明 Macie 在名为 `key` 的数组的第二个值中检测到了敏感数据。该数组是名为 `access` 的对象的子项。

以下示例显示了一个 `Record` 对象的结构，该对象指定 Macie 在 JSON Lines 文件中检测到的敏感数据出现的位置。

```
"records": [
   {
      "jsonPath": "$.access.key",
      "recordIndex": 3
   }
]
```

在前面的示例中，调查发现表明 Macie 在文件中的第三个值（行）中检测到了敏感数据。在该行中，事件位于名为 `key` 的字段中，该字段是名为 `access` 的对象的子项。