本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 亚马逊 Neptune OpenCypher HTTPS 终端节点 **Topics** + [OpenCypher 在 HTTPS 终端节点上读取和写入查询](#access-graph-opencypher-queries-read-write) + [默认 OpenCypher JSON 结果格式](#access-graph-opencypher-queries-results-simple-JSON) + [用于多 OpenCypher 部分响应的可选 HTTP 尾随标头](#optional-http-trailing-headers) **注意** 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 ``` 以下是一个读取查询示例： ------ #### [ Amazon CLI ] ``` aws neptunedata execute-open-cypher-query \ --endpoint-url https://{{your-neptune-endpoint}}:{{port}} \ --open-cypher-query "MATCH (n1) RETURN n1" ``` 有关更多信息，请参阅《 Amazon CLI 命令参考》[execute-open-cypher-query](https://docs.amazonaws.cn/cli/latest/reference/neptunedata/execute-open-cypher-query.html)中的。 ------ #### [ 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']) ``` 有关其他语言 Amazon 的 SDK 示例，请参阅[Amazon SDK](access-graph-opencypher-sdk.md)。 ------ #### [ awscurl ] ``` awscurl https://{{your-neptune-endpoint}}:{{port}}/openCypher \ --region {{us-east-1}} \ --service neptune-db \ -X POST \ -d "query=MATCH (n1) RETURN n1" ``` **注意** 此示例假设您的 Amazon 证书是在您的环境中配置的。{{us-east-1}}替换为 Neptune 集群的区域。 ------ #### [ curl ] ``` curl https://{{your-neptune-endpoint}}:{{port}}/openCypher \ -d "query=MATCH (n1) RETURN n1" ``` ------ 以下是一个示例 write/update 查询： ------ #### [ Amazon CLI ] ``` aws neptunedata execute-open-cypher-query \ --endpoint-url https://{{your-neptune-endpoint}}:{{port}} \ --open-cypher-query "CREATE (n:Person { age: 25 })" ``` 有关更多信息，请参阅《 Amazon CLI 命令参考》[execute-open-cypher-query](https://docs.amazonaws.cn/cli/latest/reference/neptunedata/execute-open-cypher-query.html)中的。 ------ #### [ 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']) ``` 有关其他语言 Amazon 的 SDK 示例，请参阅[Amazon SDK](access-graph-opencypher-sdk.md)。 ------ #### [ awscurl ] ``` awscurl https://{{your-neptune-endpoint}}:{{port}}/openCypher \ --region {{us-east-1}} \ --service neptune-db \ -X POST \ -d "query=CREATE (n:Person { age: 25 })" ``` **注意** 此示例假设您的 Amazon 证书是在您的环境中配置的。{{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](https://docs.amazonaws.cn/releases/release-1.4.5.0.xml) 开始推出。对 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 页面](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/TE)。 **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) 和详细错误信息的尾随标头。