翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # グラフに関する簡単なサマリーレポートを取得する 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 DB クラスターを新規作成すると、統計がデフォルトで有効になります。 **注記** メモリを節約するため、`t3` および `t4` インスタンスタイプ (つまり、`db.t3.medium` および `db.t4g.medium` インスタンスタイプ) では、統計の生成が無効になっています。そのため、どちらのインスタンスタイプでもグラフサマリーデータは使用できません。 DFE 統計のステータスは、[統計ステータス API](neptune-dfe-statistics.md#neptune-dfe-statistics-status) を使用して確認できます。統計の自動生成が[無効になって](neptune-dfe-statistics.md#neptune-dfe-statistics-auto-disable)いない限り、統計は定期的に自動更新されます。 グラフサマリーをリクエストするときに統計をできるだけ最新の状態に保ちたい場合は、サマリーを取得する直前に、[手動で統計の更新をトリガー](neptune-dfe-statistics.md#neptune-dfe-statistics-manual)できます。統計の計算中にグラフが変化する場合、必然的に少し遅れますが、それほど遅れることはありません。 ## グラフサマリー 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` の 2 つの値のいずれかを指定できます。RDF グラフの場合、`detailed` モードグラフサマリーレスポンスには追加の `subjectStructures` フィールドが含まれます。プロパティグラフの場合、詳細グラフサマリーレスポンスには、`nodeStructures` と `edgeStructures` という 2 つの追加フィールドが含まれます。 `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 です。 共通エラーリストについては、[一般的なグラフサマリーエラー](#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 グラフのグラフサマリーレスポンス 空の 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) サマリーレスポンス 以下は、[サンプルプロパティグラフの航空路データセット](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 グラフサマリーレスポンス 以下は、[サンプルの 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) 認証の使用 グラフサマリーエンドポイントには、[awscurl](https://github.com/okigan/awscurl) または、HTTP および IAM で動作するその他のツールを使用して IAM 認証で安全にアクセスできます。適切な認証情報を設定する方法については、「[一時的な認証情報で `awscurl` を使用して、IAM 認証が有効になっている DB クラスターに安全に接続する](iam-auth-connect-command-line.md#iam-auth-connect-awscurl)」を参照してください。設定が完了したら、次のようなリクエストを行うことができます。 ``` awscurl "$GRAPH_SUMMARY_ENDPOINT" \ --region {{(your region)}} \ --service neptune-db ``` **重要** 一時的な認証情報を作成する IAM ID またはロールには、[GetGraphSummary](iam-dp-actions.md#getgraphsummary) IAM アクションを許可する IAM ポリシーがアタッチされている必要があります。 よく発生する IAM エラーのリストについては、「[IAM 認証エラー](errors-engine-codes.md#errors-iam-auth)」を参照してください。 ## グラフサマリーリクエストが返す可能性のある一般的なエラーコード - ****`AccessDeniedException`**** - **HTTP ステータス:** 403 / **メッセージ:** 認証トークンが見つかりません。 / **エラーシナリオ:** 署名されていない、または正しく署名されていないリクエストが IAM が有効な Neptune データベースに送信されました。 / **緩和:** 送信する前に SigV4 でリクエストに署名してください (「[IAM とグラフサマリー](#neptune-graph-summary-iam)」を参照)。 - **HTTP ステータス:** 403 / **メッセージ:** ユーザー: {{(ユーザー ARN)}} は、リソース: {{(リソース ARN)}} に対して neptune-db:GetGraphSummary を実行することを承認されていません。 / **エラーシナリオ:** IAM ポリシーでは、IAM が有効になっている Neptune データベースにグラフサマリーリクエストが送信された場合、[GetGraphSummary](iam-dp-actions.md#getgraphsummary) アクションは許可されません。 / **緩和:** リクエストを行うユーザーまたはロールにアタッチされている IAM ポリシーが `GetGraphSummary` アクションを許可していることを確認してください。 - ****`BadRequestException`**** - **HTTP ステータス:** 400 / **メッセージ:** 統計は無効になっているため、グラフサマリーも無効になっています。 / **エラーシナリオ:** 統計が無効になっているバースト可能なインスタンスタイプ (`t3` または `t4g`) でサマリーを取得しようとしています。 / **緩和:** 統計の生成が有効になっているインスタンスタイプを使用してください (`t3` と `t4g` を除くすべてのサポート対象インスタンス)。 - **HTTP ステータス:** 400 / **メッセージ:** 不正なルート: {{/rdf/statistics/summarypathapi}} / **エラーシナリオ:** 無効なパスに送信されたリクエスト。 / **緩和:** グラフサマリーエンドポイントには正しいルートを使用してください。 - ****`InvalidParameterException`**** - **HTTP ステータス:** 400 - **メッセージ:** リクエストに未知のパラメータが含まれています: '{{(不明なパラメータ)}}'。 - **エラーシナリオ:** リクエストで無効なパラメータが指定されている場合。 - **緩和:** リクエストには有効なパラメータ (`mode` など) のみを使用してください。 - ****`InvalidParameterException`**** - **HTTP ステータス:** 400 - **メッセージ:** URI クエリパラメータ 'mode' にサポートされていない値 '{{(無効な値)}}' があります。 - **エラーシナリオ:** リクエストの URL パラメータ 'mode' の後に無効な値が続く場合。 - **緩和:** URL パラメータ 'mode' を指定するときには、有効な値 (`basic` や `detailed` など) を使用してください。 - ****`MethodNotAllowedException`**** - **HTTP ステータス:** 405 - **メッセージ:** 許されないメソッド。 - **エラーシナリオ:** `GET` 以外の HTTP メソッド (`POST` や `DELETE` など) を使用してサマリーエンドポイントを呼び出す。 - **緩和:** サマリーエンドポイントを呼び出すときには、HTTP `GET` メソッドを使用してください。 - ****`StatisticsNotAvailableException`**** - **HTTP ステータス:** 400 / **メッセージ:** 統計はまだ計算されていません。統計の計算が完了すると、グラフサマリーが使用可能になります。 / **エラーシナリオ:** リクエストがサマリーエンドポイントに送信されたとき、利用できる統計がありません。 / **緩和:** 統計の生成が完了するまで待ちます。統計生成のステータスは、[統計ステータス API](neptune-dfe-statistics.md#neptune-dfe-statistics-status) を使用して確認できます。 - **HTTP ステータス:** 400 / **メッセージ:** 統計の上限に達したため、グラフサマリーは使用できません。 / **エラーシナリオ:** [統計サイズ制限](neptune-dfe-statistics.md#neptune-dfe-statistics-limits)に達したため、統計の生成が停止しました。 / **緩和:** このグラフに関するグラフサマリーは使用可能ではありません。 例えば、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" } ```