本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 取得有關圖形的快速摘要報告
<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 工作台魔法，在 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 圖形的詳細摘要回應，其中包含[範例 RDF 航線資料集](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/seed/queries/rdf/sparql/airports)：

```
{
  "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_tw/neptune/latest/userguide/neptune-graph-summary.html)

例如，如果您在已啟用 IAM 身分驗證的 Neptune 資料庫中對圖形化摘要端點提出請求，且請求者的 IAM 政策中沒有必要的許可，則您會得到如下的回應：

```
{
  "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"
}
```