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

# Amazon Neptune OpenCypher HTTPS 端點
<a name="access-graph-opencypher-queries"></a>

**Topics**
+ [HTTPS 端點上的 OpenCypher 讀取和寫入查詢](#access-graph-opencypher-queries-read-write)
+ [預設 OpenCypher JSON 結果格式](#access-graph-opencypher-queries-results-simple-JSON)
+ [多部分 OpenCypher 回應的選用 HTTP 結尾標頭](#optional-http-trailing-headers)

**注意**  
Neptune 目前不支援 HTTP/2 for REST API 請求。連接到端點時，用戶端必須使用 HTTP/1.1。

## HTTPS 端點上的 OpenCypher 讀取和寫入查詢
<a name="access-graph-opencypher-queries-read-write"></a>

OpenCypher HTTPS 端點支援使用 和 `POST`方法讀取`GET`和更新查詢。不支援 `DELETE` 和 `PUT` 方法。

下列指示會逐步引導您使用 `curl`命令和 HTTPS 連線至 OpenCypher 端點。您必須從與您的 Neptune 資料庫執行個體位於同一虛擬私有雲端 (VPC) 的 Amazon EC2 執行個體依照以下指示進行。

語法是：

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

以下是範例讀取查詢，一個使用 `POST`，一個使用 `GET`：

1. 使用 `POST`：

```
curl HTTPS://server:port/openCypher \
  -d "query=MATCH (n1) RETURN n1;"
```

2. 使用 `GET` (查詢字串是 URL 編碼的)：

```
curl -X GET \
  "HTTPS://server:port/openCypher?query=MATCH%20(n1)%20RETURN%20n1"
```

以下是範例寫入/更新查詢，一個使用 `POST`，一個使用 `GET`：

1. 使用 `POST`：

```
curl HTTPS://server:port/openCypher \
  -d "query=CREATE (n:Person { age: 25 })"
```

2. 使用 `GET` (查詢字串是 URL 編碼的)：

```
curl -X GET \
  "HTTPS://server:port/openCypher?query=CREATE%20(n%3APerson%20%7B%20age%3A%2025%20%7D)"
```

## 預設 OpenCypher JSON 結果格式
<a name="access-graph-opencypher-queries-results-simple-JSON"></a>

預設會傳回下列 JSON 格式，或將請求標頭明確設定為 `Accept: application/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 結尾標頭
<a name="optional-http-trailing-headers"></a>

 此功能從 Neptune 引擎版本 [1.4.5.0](https://docs.aws.amazon.com/releases/release-1.4.5.0.xml) 開始可用。

 OpenCypher 查詢和更新的 HTTP 回應通常會以多個區塊傳回。當傳送初始回應區塊之後發生失敗 (HTTP 狀態碼為 200)，診斷問題可能很困難。根據預設，`Neptune 會透過將錯誤訊息附加至訊息內文來報告此類失敗，這可能會因為回應的串流性質而損毀。

**使用結尾標頭**  
 為了改善錯誤偵測和診斷，您可以在請求中包含傳輸編碼 (TE) 尾端標頭 (te： 尾端），以啟用尾端標頭。這樣做會導致 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) 和詳細的錯誤資訊。