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

# 获取有关图形的快速摘要报告
<a name="neptune-graph-summary"></a>

Neptune 图形摘要 API 会检索有关您的图形的以下信息：
+ 对于属性 (PG) 图，图形摘要 API 会返回节点和边缘标签以及属性键的只读列表，以及节点、边缘和属性的计数。
+ 对于资源描述框架 (RDF) 图，图形摘要 API 会返回类和谓词键的只读列表，以及四元组、主题和谓词的计数。

**注意**  
图形摘要 API 是在 Neptune [引擎版本 1.2.1.0](engine-releases-1.2.1.0.md) 中引入的。

借助图形摘要 API，您可以快速、全面了解图形数据的大小和内容。还可以使用 [`%summary`](notebooks-magics.md#notebooks-line-magics-summary) Neptune Workbench 魔术命令在 Neptune 笔记本中以交互方式使用 API。在图形应用程序中，API 可用于通过在搜索过程中提供已发现的节点或边缘标签来改善搜索结果。

图形摘要数据是从 [Neptune DFE 引擎](neptune-dfe-engine.md)在运行时系统期间计算的 [DFE 统计数据](neptune-dfe-statistics.md)中提取的，只要有 DFE 统计数据就可用。当您创建新的 Neptune 数据库集群时，统计数据默认处于启用状态。

**注意**  
在 `t3` 和 `t4` 实例类型（即在 `db.t3.medium` 和 `db.t4g.medium` 实例类型上）上禁用统计数据生成，以节省内存。因此，这些实例类型上的图形摘要数据也不可用。

您可使用[统计数据状态 API](neptune-dfe-statistics.md#neptune-dfe-statistics-status) 检查 DFE 统计数据的状态。只要[未禁用](neptune-dfe-statistics.md#neptune-dfe-statistics-auto-disable)自动生成统计数据，统计数据就会定期自动更新。

如果您想在请求图形摘要时确保统计数据尽可能是最新的，则可以就在检索摘要之前[手动触发统计数据更新](neptune-dfe-statistics.md#neptune-dfe-statistics-manual)。如果在计算统计数据时图形发生变化，它们必然会稍微滞后，但程度不会太大。

## 使用图形摘要 API 检索图形摘要信息
<a name="neptune-graph-summary-retrieving"></a>

对于您使用 Gremlin 或 openCypher 进行查询的属性图，您可以从属性图摘要端点检索图形摘要。该端点有长的 URI 和短的 URI：
+ `https://your-neptune-host:port/propertygraph/statistics/summary`
+ `https://your-neptune-host:port/pg/statistics/summary`

对于使用 SPARQL 查询的 RDF 图形，您可以从 RDF 摘要端点检索图形摘要：
+ `https://your-neptune-host:port/rdf/statistics/summary`

这些端点是只读的，仅支持 HTTP `GET` 操作。如果 \$1GRAPH\$1SUMMARY\$1ENDPOINT 设置为要查询的任何端点的地址，则可以使用 `curl` 和 HTTP `GET` 检索摘要数据，如下所示：

```
curl -G "$GRAPH_SUMMARY_ENDPOINT"
```

如果您尝试检索图形摘要时没有可用的统计数据，则响应如下所示：

```
{
  "detailedMessage": "Statistics are not available. Summary can only be generated after statistics are available.",
  "requestId": "48c1f788-f80b-b69c-d728-3f6df579a5f6",
  "code": "StatisticsNotAvailableException"
}
```

## 图形摘要 API 的 `mode` URL 查询参数
<a name="neptune-graph-summary-mode"></a>

图形摘要 API 接受名为 `mode` 的 URL 查询参数，该参数可以采用两个值之一，即 `basic`（默认）和 `detailed`。对于 RDF 图形，`detailed` 模式图形摘要响应包含一个附加 `subjectStructures` 字段。对于属性图，详细图形摘要响应包含另外两个字段，即 `nodeStructures` 和 `edgeStructures`。

要请求 `detailed` 图形摘要响应，请按以下方式包括 `mode` 参数：

```
curl -G "$GRAPH_SUMMARY_ENDPOINT?mode=detailed"
```

如果 `mode` 参数不存在，则默认使用 `basic` 模式，因此，虽然可以显式指定 `?mode=basic`，但这不是必需的。

## 属性图 (PG) 的图形摘要响应
<a name="neptune-graph-summary-pg-response"></a>

对于空的属性图，详细的图形摘要响应如下所示：

```
{
  "status" : "200 OK",
  "payload" : {
    "version" : "v1",
    "lastStatisticsComputationTime" : "2023-01-10T07:58:47.972Z",
    "graphSummary" : {
      "numNodes" : 0,
      "numEdges" : 0,
      "numNodeLabels" : 0,
      "numEdgeLabels" : 0,
      "nodeLabels" : [ ],
      "edgeLabels" : [ ],
      "numNodeProperties" : 0,
      "numEdgeProperties" : 0,
      "nodeProperties" : [ ],
      "edgeProperties" : [ ],
      "totalNodePropertyValues" : 0,
      "totalEdgePropertyValues" : 0,
      "nodeStructures" : [ ],
      "edgeStructures" : [ ]
    }
  }
}
```

属性图 (PG) 摘要响应包含以下字段：
+ **`status`** – 请求的 HTTP 返回代码。如果请求成功，则代码为 200。

  有关常见错误的列表，请参阅[常见图形摘要错误](#neptune-graph-summary-errors)。
+ **`payload`**
  + **`version`** – 此图形摘要响应的版本。
  + **`lastStatisticsComputationTime `** – Neptune 上次计算[统计数据](neptune-dfe-statistics.md)的时间戳，采用 ISO 8601 格式。
  + **`graphSummary`**
    + **`numNodes`** – 图形中的节点数。
    + **`numEdges`** – 图形中的边缘数。
    + **`numNodeLabels`** – 图形中不同节点标签的数量。
    + **`numEdgeLabels`** – 图形中不同边缘标签的数量。
    + **`nodeLabels`** – 图形中不同节点标签的列表。
    + **`edgeLabels`** – 图形中不同边缘标签的列表。
    + **`numNodeProperties`** – 图形中不同节点属性的数量。
    + **`numEdgeProperties`** – 图形中不同边缘属性的数量。
    + **`nodeProperties`** – 图形中不同节点属性的列表，以及使用每个属性的节点计数。
    + **`edgeProperties`** – 图形中不同边缘属性的列表以及使用每个属性的边缘计数。
    + **`totalNodePropertyValues`** – 所有节点属性的总使用次数。
    + **`totalEdgePropertyValues`** – 所有边缘属性的总使用次数。
    + **`nodeStructures`** – *只有在请求中指定 `mode=detailed` 时才会出现此字段。*它包含节点结构列表，每个节点结构都包含以下字段：
      + **`count`** – 具有此特定结构的节点数量。
      + **`nodeProperties`** – 此特定结构中存在的节点属性列表。
      + **`distinctOutgoingEdgeLabels`** – 此特定结构中存在的不同传出边缘标签的列表。
    + **`edgeStructures`** – *只有在请求中指定 `mode=detailed` 时才会出现此字段。*它包含边缘结构列表，每个边缘结构都包含以下字段：
      + **`count`** – 具有此特定结构的边缘数量。
      + **`edgeProperties`** – 此特定结构中存在的边缘属性列表。

## RDF 图形的图形摘要响应
<a name="neptune-graph-summary-rdf-response"></a>

对于空的 RDF 图形，详细的图形摘要响应如下所示：

```
{
  "status" : "200 OK",
  "payload" : {
    "version" : "v1",
    "lastStatisticsComputationTime" : "2023-01-10T07:58:47.972Z",
    "graphSummary" : {
      "numDistinctSubjects" : 0,
      "numDistinctPredicates" : 0,
      "numQuads" : 0,
      "numClasses" : 0,
      "classes" : [ ],
      "predicates" : [ ],
      "subjectStructures" : [ ]
    }
  }
}
```

RDF 图形摘要响应具有以下字段：
+ **`status`** – 请求的 HTTP 返回代码。如果请求成功，则代码为 200。

  有关常见错误的列表，请参阅[常见图形摘要错误](#neptune-graph-summary-errors)。
+ **`payload`**
  + **`version`** – 此图形摘要响应的版本。
  + **`lastStatisticsComputationTime `** – Neptune 上次计算[统计数据](neptune-dfe-statistics.md)的时间戳，采用 ISO 8601 格式。
  + **`graphSummary`**
    + **`numDistinctSubjects`** – 图形中不同主题的数量。
    + **`numDistinctPredicates`** – 图形中不同谓词的数量。
    + **`numQuads`** – 图形中四元组的数量。
    + **`numClasses`** – 图形中的类数。
    + **`classes`** – 图形中的类列表。
    + **`predicates`** – 图形中的谓词列表以及谓词计数。
    + **`subjectStructures`** – *只有在请求中指定 `mode=detailed` 时才会出现此字段。*它包含主题结构列表，每个主题结构都包含以下字段：
      + **`count`** – 此特定结构的出现次数。
      + **`predicates`** – 此特定结构中存在的谓词列表。

## 属性图 (PG) 摘要响应示例
<a name="neptune-graph-summary-sample-pg-response"></a>

以下是包含[示例属性图航线数据集](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/seed/queries/propertygraph/gremlin/airports)的属性图的详细摘要响应：

```
{
  "status" : "200 OK",
  "payload" : {
    "version" : "v1",
    "lastStatisticsComputationTime" : "2023-03-01T14:35:03.804Z",
    "graphSummary" : {
      "numNodes" : 3748,
      "numEdges" : 51300,
      "numNodeLabels" : 4,
      "numEdgeLabels" : 2,
      "nodeLabels" : [
        "continent",
        "country",
        "version",
        "airport"
      ],
      "edgeLabels" : [
        "contains",
        "route"
      ],
      "numNodeProperties" : 14,
      "numEdgeProperties" : 1,
      "nodeProperties" : [
        {
          "desc" : 3748
        },
        {
          "code" : 3748
        },
        {
          "type" : 3748
        },
        {
          "country" : 3503
        },
        {
          "longest" : 3503
        },
        {
          "city" : 3503
        },
        {
          "lon" : 3503
        },
        {
          "elev" : 3503
        },
        {
          "icao" : 3503
        },
        {
          "region" : 3503
        },
        {
          "runways" : 3503
        },
        {
          "lat" : 3503
        },
        {
          "date" : 1
        },
        {
          "author" : 1
        }
      ],
      "edgeProperties" : [
        {
          "dist" : 50532
        }
      ],
      "totalNodePropertyValues" : 42773,
      "totalEdgePropertyValues" : 50532,
      "nodeStructures" : [
        {
          "count" : 3471,
          "nodeProperties" : [
            "city",
            "code",
            "country",
            "desc",
            "elev",
            "icao",
            "lat",
            "lon",
            "longest",
            "region",
            "runways",
            "type"
          ],
          "distinctOutgoingEdgeLabels" : [
            "route"
          ]
        },
        {
          "count" : 161,
          "nodeProperties" : [
            "code",
            "desc",
            "type"
          ],
          "distinctOutgoingEdgeLabels" : [
            "contains"
          ]
        },
        {
          "count" : 83,
          "nodeProperties" : [
            "code",
            "desc",
            "type"
          ],
          "distinctOutgoingEdgeLabels" : [ ]
        },
        {
          "count" : 32,
          "nodeProperties" : [
            "city",
            "code",
            "country",
            "desc",
            "elev",
            "icao",
            "lat",
            "lon",
            "longest",
            "region",
            "runways",
            "type"
          ],
          "distinctOutgoingEdgeLabels" : [ ]
        },
        {
          "count" : 1,
          "nodeProperties" : [
            "author",
            "code",
            "date",
            "desc",
            "type"
          ],
          "distinctOutgoingEdgeLabels" : [ ]
        }
      ],
      "edgeStructures" : [
        {
          "count" : 50532,
          "edgeProperties" : [
            "dist"
          ]
        }
      ]
    }
  }
}
```

## 示例 RDF 图形摘要响应
<a name="neptune-graph-summary-sample-rdf-response"></a>

以下是包含[示例 RDF 航线数据集](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/seed/queries/rdf/sparql/airports)的 RDF 图形的详细摘要响应：

```
{
  "status" : "200 OK",
  "payload" : {
    "version" : "v1",
    "lastStatisticsComputationTime" : "2023-03-01T14:54:13.903Z",
    "graphSummary" : {
      "numDistinctSubjects" : 54403,
      "numDistinctPredicates" : 19,
      "numQuads" : 158571,
      "numClasses" : 4,
      "classes" : [
        "http://kelvinlawrence.net/air-routes/class/Version",
        "http://kelvinlawrence.net/air-routes/class/Airport",
        "http://kelvinlawrence.net/air-routes/class/Continent",
        "http://kelvinlawrence.net/air-routes/class/Country"
      ],
      "predicates" : [
        {
          "http://kelvinlawrence.net/air-routes/objectProperty/route" : 50656
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/dist" : 50656
        },
        {
          "http://kelvinlawrence.net/air-routes/objectProperty/contains" : 7004
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/code" : 3747
        },
        {
          "http://www.w3.org/2000/01/rdf-schema#label" : 3747
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/type" : 3747
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/desc" : 3747
        },
        {
          "http://www.w3.org/1999/02/22-rdf-syntax-ns#type" : 3747
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/icao" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/lat" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/region" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/runways" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/longest" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/elev" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/lon" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/country" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/city" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/author" : 1
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/date" : 1
        }
      ],
      "subjectStructures" : [
        {
          "count" : 50656,
          "predicates" : [
            "http://kelvinlawrence.net/air-routes/datatypeProperty/dist"
          ]
        },
        {
          "count" : 3471,
          "predicates" : [
            "http://kelvinlawrence.net/air-routes/datatypeProperty/city",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/code",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/country",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/desc",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/elev",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/icao",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/lat",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/lon",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/longest",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/region",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/runways",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/type",
            "http://kelvinlawrence.net/air-routes/objectProperty/route",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2000/01/rdf-schema#label"
          ]
        },
        {
          "count" : 238,
          "predicates" : [
            "http://kelvinlawrence.net/air-routes/datatypeProperty/code",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/desc",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/type",
            "http://kelvinlawrence.net/air-routes/objectProperty/contains",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2000/01/rdf-schema#label"
          ]
        },
        {
          "count" : 31,
          "predicates" : [
            "http://kelvinlawrence.net/air-routes/datatypeProperty/city",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/code",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/country",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/desc",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/elev",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/icao",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/lat",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/lon",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/longest",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/region",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/runways",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/type",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2000/01/rdf-schema#label"
          ]
        },
        {
          "count" : 6,
          "predicates" : [
            "http://kelvinlawrence.net/air-routes/datatypeProperty/code",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/desc",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/type",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2000/01/rdf-schema#label"
          ]
        },
        {
          "count" : 1,
          "predicates" : [
            "http://kelvinlawrence.net/air-routes/datatypeProperty/author",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/code",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/date",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/desc",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/type",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2000/01/rdf-schema#label"
          ]
        }
      ]
    }
  }
}
```

## 对图表摘要终端节点使用 AWS Identity and Access Management (IAM) 身份验证
<a name="neptune-graph-summary-iam"></a>

您可以使用 [awscurl](https://github.com/okigan/awscurl) 或任何其它支持 HTTPS 和 IAM 的工具，通过 IAM 身份验证安全地访问图形摘要端点。请参阅[将 `awscurl` 与临时凭证结合使用以安全地连接到启用了 IAM 身份验证的数据库集群](iam-auth-connect-command-line.md#iam-auth-connect-awscurl)，了解如何设置正确的凭证。完成此操作后，您可以提出这样的请求：

```
awscurl "$GRAPH_SUMMARY_ENDPOINT" \
    --region (your region) \
    --service neptune-db
```

**重要**  
创建临时证书的 IAM 身份或角色必须附加允许 IAM 操作[GetGraphSummary](iam-dp-actions.md#getgraphsummary)的 IAM 策略。

有关您可能遇到的常见 IAM 错误的列表，请参阅[IAM 身份验证错误](errors-engine-codes.md#errors-iam-auth)。

## 图形摘要请求可能返回的常见错误代码
<a name="neptune-graph-summary-errors"></a>

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/neptune/latest/userguide/neptune-graph-summary.html)

例如，如果您请求在启用了 IAM 身份验证的 Neptune 数据库中绘制摘要端点的图形，而请求者的 IAM policy 中没有必要的权限，您将收到如下响应：

```
{
  "detailedMessage": "User: arn:aws:iam::(account ID):(user or user name) is not authorized to perform: neptune-db:GetGraphSummary on resource: arn:aws:neptune-db:(region):(account ID):(cluster resource ID)/*",
  "requestId": "7ac2b98e-b626-d239-1d05-74b4c88fce82",
  "code": "AccessDeniedException"
}
```