View a markdown version of this page

亚马逊 Neptune OpenCypher HTTPS 终端节点 - Amazon Neptune
读取和写入查询OpenCypher 结果格式可选的 HTTP 尾随标头

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

亚马逊 Neptune OpenCypher HTTPS 终端节点

注意

Neptune 目前不支持 HTTP/2 来处理 REST API 请求。客户端在连接到端点时必须使用 HTTP/1.1。

OpenCypher 在 HTTPS 终端节点上读取和写入查询

OpenCypher HTTPS 终端节点支持同时使用和POST方法进行读取GET和更新查询。不支持 DELETE 和 PUT 方法。

以下说明将引导您使用curl命令和 HTTPS 连接到 OpenCypher 终端节点。必须从与您的 Neptune 数据库实例位于同一虚拟私有云 (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"

有关更多信息，请参阅《 AWS CLI 命令参考》execute-open-cypher-query中的。

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"

以下是一个示例 write/update 查询：

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

有关更多信息，请参阅《 AWS CLI 命令参考》execute-open-cypher-query中的。

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 结果格式

默认情况下或通过将请求标头显式设置为 Accept: application/json，返回以下 JSON 格式。这种格式旨在使用大多数库的原生语言特征轻松解析为对象。

返回的 JSON 文档包含一个字段 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: trailers）来启用尾随标头。这样做会导致 Neptune 在响应块的尾随标头中加入两个新的标头字段：

  • X-Neptune-Status – 包含响应代码后跟一个短名称。例如，如果成功，则尾随标头将是：X-Neptune-Status: 200 OK。如果失败，响应代码将是 Neptune 引擎错误代码，例如 X-Neptune-Status: 500 TimeLimitExceededException。

  • 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) 和详细错误信息的尾随标头。