View a markdown version of this page

Amazon Neptune OpenCypher HTTPS エンドポイント - Amazon Neptune
クエリの読み取りおよび書き込みOpenCypher 結果形式HTTP 末尾ヘッダ (オプション)

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Amazon Neptune OpenCypher HTTPS エンドポイント

注記

Neptune は現在、REST API リクエストの HTTP/2 をサポートしていません。クライアントは、エンドポイントに接続するときに HTTP/1.1 を使用する必要があります。

OpenCypher が HTTPS エンドポイントでクエリを読み書きする

OpenCypher HTTPS エンドポイントは、GET と POST のメソッドの両方を使用してクエリを読み取って更新します。DELETE と PUT メソッドはサポートされていません。

次の手順では、curl コマンドおよび HTTPS を使用して OpenCypher エンドポイントに接続する方法について説明します。Neptune DB インスタンスと同じ仮想プライベートクラウド (VPC) の Amazon EC2 インスタンスからこれらの手順を実行してください。

構文は次のとおりです。

HTTPS://(the server):(the port number)/openCypher

読み取りクエリの例を次に示します。

AWS CLI
aws neptunedata execute-open-cypher-query \
  --endpoint-url https://your-neptune-endpoint:port \
  --open-cypher-query "MATCH (n1) RETURN n1"

詳細については、 コマンドリファレンスの execute-open-cypher-query AWS CLI を参照してください。

SDK
import boto3
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

response = client.execute_open_cypher_query(
    openCypherQuery='MATCH (n1) RETURN n1'
)

print(response['results'])

他の言語の AWS SDK の例については、「」を参照してくださいAWS SDK。

awscurl
awscurl https://your-neptune-endpoint:port/openCypher \
  --region us-east-1 \
  --service neptune-db \
  -X POST \
  -d "query=MATCH (n1) RETURN n1"
注記

この例では、 AWS 認証情報が 環境で設定されていることを前提としています。us-east-1 を Neptune クラスターのリージョンに置き換えます。

curl
curl https://your-neptune-endpoint:port/openCypher \
  -d "query=MATCH (n1) RETURN n1"

以下は、書き込み/更新クエリの例です。

AWS CLI
aws neptunedata execute-open-cypher-query \
  --endpoint-url https://your-neptune-endpoint:port \
  --open-cypher-query "CREATE (n:Person { age: 25 })"

詳細については、 コマンドリファレンスの execute-open-cypher-query AWS CLI を参照してください。

SDK
import boto3
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

response = client.execute_open_cypher_query(
    openCypherQuery='CREATE (n:Person { age: 25 })'
)

print(response['results'])

他の言語の AWS SDK の例については、「」を参照してくださいAWS SDK。

awscurl
awscurl https://your-neptune-endpoint:port/openCypher \
  --region us-east-1 \
  --service neptune-db \
  -X POST \
  -d "query=CREATE (n:Person { age: 25 })"
注記

この例では、 AWS 認証情報が 環境で設定されていることを前提としています。us-east-1 を Neptune クラスターのリージョンに置き換えます。

curl
curl https://your-neptune-endpoint:port/openCypher \
  -d "query=CREATE (n:Person { age: 25 })"

デフォルトの OpenCypher JSON 結果フォーマット

次の JSON 形式がデフォルトで返されます。または、リクエストヘッダーを明示的に Accept: application/json に設定することで返されます。このフォーマットは、ほとんどのライブラリのネイティブ言語機能を使用してオブジェクトに簡単に解析できるように設計されています。

返される JSON ドキュメントには、1 つのフィールドが含まれています。results には、クエリの戻り値が含まれています。以下の例は、一般的な値の JSON フォーマットを示しています。

値のレスポンスの例:

{
  "results": [
    {
      "count(a)": 121
    }
  ]
}

ノードレスポンスの例:

{
  "results": [
    {
      "a": {
        "~id": "22",
        "~entityType": "node",
        "~labels": [
          "airport"
        ],
        "~properties": {
          "desc": "Seattle-Tacoma",
          "lon": -122.30899810791,
          "runways": 3,
          "type": "airport",
          "country": "US",
          "region": "US-WA",
          "lat": 47.4490013122559,
          "elev": 432,
          "city": "Seattle",
          "icao": "KSEA",
          "code": "SEA",
          "longest": 11901
        }
      }
    }
  ]
}

リレーションシップレスポンスの例:

{
  "results": [
    {
      "r": {
        "~id": "7389",
        "~entityType": "relationship",
        "~start": "22",
        "~end": "151",
        "~type": "route",
        "~properties": {
          "dist": 956
        }
      }
    }
  ]
}

パスレスポンスの例:

{
  "results": [
    {
      "p": [
        {
          "~id": "22",
          "~entityType": "node",
          "~labels": [
            "airport"
          ],
          "~properties": {
            "desc": "Seattle-Tacoma",
            "lon": -122.30899810791,
            "runways": 3,
            "type": "airport",
            "country": "US",
            "region": "US-WA",
            "lat": 47.4490013122559,
            "elev": 432,
            "city": "Seattle",
            "icao": "KSEA",
            "code": "SEA",
            "longest": 11901
          }
        },
        {
          "~id": "7389",
          "~entityType": "relationship",
          "~start": "22",
          "~end": "151",
          "~type": "route",
          "~properties": {
            "dist": 956
          }
        },
        {
          "~id": "151",
          "~entityType": "node",
          "~labels": [
            "airport"
          ],
          "~properties": {
            "desc": "Ontario International Airport",
            "lon": -117.600997924805,
            "runways": 2,
            "type": "airport",
            "country": "US",
            "region": "US-CA",
            "lat": 34.0559997558594,
            "elev": 944,
            "city": "Ontario",
            "icao": "KONT",
            "code": "ONT",
            "longest": 12198
          }
        }
      ]
    }
  ]
}

マルチパートの OpenCypher レスポンスのオプションの HTTP 末尾ヘッダー

この機能は、Neptune エンジンリリース 1.4.5.0 以降で利用できます。

OpenCypher クエリと更新に対する HTTP レスポンスは通常、複数のチャンクで返されます。初期レスポンスチャンクの送信後に障害が発生した場合 (HTTP ステータスコードが 200)、問題を診断するのは難しい可能性があります。デフォルトでは、「Neptune」はエラーメッセージをメッセージ本文に追加してこのような障害を報告します。エラーメッセージは、レスポンスのストリーミングの性質が原因で破損する可能性があります。

末尾のヘッダーの使用

エラーの検出と診断を向上させるには、転送エンコード (TE) トレーラーヘッダー (te: トレーラー) をリクエストに配置することで、末尾のヘッダーを有効にします。これを行うと、Neptune はレスポンスチャンクの末尾ヘッダー内に 2 つの新しいヘッダーフィールドを含めます。

  • X-Neptune-Status — 応答コードの後ろに短い名前が続きます。たとえば、成功した場合、末尾ヘッダーは次のようになります。X-Neptune-Status: 200 OK。失敗の場合、応答コードは、X-Neptune-Status: 500 TimeLimitExceededException といった Neptune エンジンのエラーコードとなる可能性があります。

  • X-Neptune-Detail — 成功したリクエストでは空です。エラーの場合は、JSON エラーメッセージが含まれます。HTTP ヘッダー値には ASCII 文字しか使用できないため、JSON 文字列は URL 符号化されます。エラーメッセージは、レスポンスメッセージ本文にも追加されます。

詳細については、「TE リクエストヘッダーに関する MDN ページ」を参照してください。

OpenCypher 末尾ヘッダーの使用例

この例では、末尾のヘッダーが時間制限を超えるクエリの診断にどのように役立つかを示します。

curl --raw 'https://your-neptune-endpoint:port/openCypher' \
-H 'TE: trailers' \
-d 'query=MATCH(n) RETURN n.firstName'
 
 
Output:
< HTTP/1.1 200 OK
< transfer-encoding: chunked
< trailer: X-Neptune-Status, X-Neptune-Detail
< content-type: application/json;charset=UTF-8
< 
< 
{
  "results": [{
      "n.firstName": "Hossein"
    }, {
      "n.firstName": "Jan"
    }, {
      "n.firstName": "Miguel"
    }, {
      "n.firstName": "Eric"
    }, 
{"detailedMessage":"Operation terminated (deadline exceeded)",
"code":"TimeLimitExceededException",
"requestId":"a7e9d2aa-fbb7-486e-8447-2ef2a8544080",
"message":"Operation terminated (deadline exceeded)"}
0
X-Neptune-Status: 500 TimeLimitExceededException
X-Neptune-Detail: %7B%22detailedMessage%22%3A%22Operation+terminated+%28deadline+exceeded%29%22%2C%22code%22%3A%22TimeLimitExceededException%22%2C%22requestId%22%3A%22a7e9d2aa-fbb7-486e-8447-2ef2a8544080%22%2C%22message%22%3A%22Operation+terminated+%28deadline+exceeded%29%22%7D
レスポンスの内訳:

前述の例は、末尾のヘッダーが設定されている OpenCypher レスポンスがクエリ障害の診断にどのように役立つかを示しています。ここでは、(1) ストリーミングの開始を示す 200 OK ステータスの初期ヘッダー、(2) 失敗前に正常にストリーミングされた部分的な (破損している) JSON 結果、(3) タイムアウトを示す追加エラーメッセージ、(4) 最終ステータス (500 TimeLimitExceededException) と詳細なエラー情報を含む末尾ヘッダーの 4 つの連続した部分を示します。