获取有关图形的快速摘要报告 - Amazon Neptune
检索图形摘要mode 参数属性图摘要RDF 图形摘要示例 PG 摘要示例 RDF 摘要IAM 和图形摘要常见图形摘要错误
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

获取有关图形的快速摘要报告

Neptune 图形摘要 API 会检索有关您的图形的以下信息：

  • 对于属性 (PG) 图，图形摘要 API 会返回节点和边缘标签以及属性键的只读列表，以及节点、边缘和属性的计数。

  • 对于资源描述框架 (RDF) 图，图形摘要 API 会返回类和谓词键的只读列表，以及四元组、主题和谓词的计数。

注意

图形摘要 API 是在 Neptune 引擎版本 1.2.1.0 中引入的。

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

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

注意

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

您可使用统计数据状态 API 检查 DFE 统计数据的状态。只要未禁用自动生成统计数据，统计数据就会定期自动更新。

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

使用图形摘要 API 检索图形摘要信息

对于您使用 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 操作。如果 $GRAPH_SUMMARY_ENDPOINT 设置为要查询的任何端点的地址，则可以使用 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 查询参数

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

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

curl -G "$GRAPH_SUMMARY_ENDPOINT?mode=detailed"

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

属性图 (PG) 的图形摘要响应

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

{
  "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。

    有关常见错误的列表，请参阅常见图形摘要错误。

  • payload

    • version – 此图形摘要响应的版本。

    • lastStatisticsComputationTime – Neptune 上次计算统计数据的时间戳，采用 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 图形的图形摘要响应

对于空的 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。

    有关常见错误的列表，请参阅常见图形摘要错误。

  • payload

    • version – 此图形摘要响应的版本。

    • lastStatisticsComputationTime – Neptune 上次计算统计数据的时间戳，采用 ISO 8601 格式。

    • graphSummary

      • numDistinctSubjects – 图形中不同主题的数量。

      • numDistinctPredicates – 图形中不同谓词的数量。

      • numQuads – 图形中四元组的数量。

      • numClasses – 图形中的类数。

      • classes – 图形中的类列表。

      • predicates – 图形中的谓词列表以及谓词计数。

      • subjectStructures – 只有在请求中指定 mode=detailed 时才会出现此字段。它包含主题结构列表，每个主题结构都包含以下字段：

        • count – 此特定结构的出现次数。

        • predicates – 此特定结构中存在的谓词列表。

属性图 (PG) 摘要响应示例

以下是包含示例属性图航线数据集的属性图的详细摘要响应：

{
  "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 图形摘要响应

以下是包含示例 RDF 航线数据集的 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"
          ]
        }
      ]
    }
  }
}

对图表摘要终端节点使用 Amazon Identity and Access Management (IAM) 身份验证

您可以使用 awscurl 或任何其它支持 HTTPS 和 IAM 的工具，通过 IAM 身份验证安全地访问图形摘要端点。请参阅将 awscurl 与临时凭证结合使用以安全地连接到启用了 IAM 身份验证的数据库集群，了解如何设置正确的凭证。完成此操作后，您可以提出这样的请求：

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

创建临时证书的 IAM 身份或角色必须附加允许 IAM 操作GetGraphSummary的 IAM 策略。

有关您可能遇到的常见 IAM 错误的列表，请参阅IAM 身份验证错误。

图形摘要请求可能返回的常见错误代码

Neptune 服务错误代码 HTTP 状态 消息 错误情形 缓解措施

AccessDeniedException

403

身份验证令牌缺失。

未签名或签名错误的请求已发送到启用 IAM 的 Neptune 数据库。

在发送请求之前，使用 SigV4 对请求进行签名（请参阅IAM 和图形摘要）。

403

用户:（用户 ARN）无权在资源:（资源 ARN）GetGraphSummary 上执行：neptune-db：。

当图表摘要请求发送到启用 IAM 的 Neptune 数据库GetGraphSummary时，IAM 策略不允许执行该操作。

确保附加到发出请求的用户或角色的 IAM policy 允许执行 GetGraphSummary 操作。

BadRequestException

400

统计数据被禁用，因此图形摘要也被禁用。

正在尝试提取禁用统计数据的可突增实例类型（t3 或 t4g）的摘要。

使用启用了统计数据生成的实例类型（除 t3 和 t4g 之外所有支持的实例）。

400

错误路由：/rdf/statistics/summarypathapi

请求已发送到无效路径。

为图形摘要端点使用正确的路由。

InvalidParameterException

400

请求包含未知参数：“（未知的一个参数或多个参数）”。

在请求中指定无效的参数时。

仅在请求中使用有效的参数（例如 mode）。

InvalidParameterException

400

URI 查询参数“mode”具有不支持的值“（无效值）”。

当请求中的 URL 参数“mode”后跟一个无效值时。

指定 URL 参数“mode”时，请使用有效值（例如 basic 或 detailed）。

MethodNotAllowedException

405

不允许此方法。

使用除 GET 之外的任何 HTTP 方法（例如 POST 或 DELETE）调用摘要端点。

调用摘要端点时使用 HTTP GET 方法。

StatisticsNotAvailableException

400

统计数据尚未计算，统计数据计算完成后将提供图形摘要。

当请求发送到摘要端点时，没有可用的统计数据。

等到统计数据生成完成。您可使用统计数据状态 API 检查统计数据生成的状态。

400

已达到统计限制，因此图形摘要不可用。

统计数据生成已停止，因为它已达到统计数据大小限制。

此图形上没有图形摘要。

例如，如果您请求在启用了 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"
}