iT邦幫忙

第 12 屆 iT 邦幫忙鐵人賽

DAY 26
0
AI & Data

看圖說故事,讓 Neo4j 重新詮釋你的資料庫系列 第 26

使用 HTTP API 開發 Neo4j 應用程式

講了大半個月的 Neoj 資料庫管理、查詢、維護與部署,就是都還沒說到開發,無論圖形資料庫多麽強大,最終還是得呈現在商業應用上才有價值。今天開始我們來看看 Neo4j 開發方面的資源~

我打算從前端講到後端,如果你是一位純前端開發者,至少在講完 Neo4j 前端相關的 API 之後,已經有能力自己開發一個完整的應用了。

首先登場的是 Neo4j HTTP API,如果你在使用的是 Neo4j 3.5 或更舊的版本,還有個 Neo4j REST API,但是在 Neo4j 4.0 已經完全移除,官方已不建議使用。

Discovery API

這是一個入口 API,除了查看伺服器的版本,並簡單列出幾個重要 API 的 endpoints
GET http://localhost:7474/

{
    "bolt_routing": "neo4j://localhost:7687",
    "transaction": "http://localhost:7474/db/{databaseName}/tx",
    "bolt_direct": "bolt://localhost:7687",
    "neo4j_version": "4.1.1",
    "neo4j_edition": "enterprise"
}

Neo4j HTTP API 安全性驗證

除了上述的入口 API 之外,其他 API 的呼叫都需要 HTTP 基本認證,簡單的說,你必須把帳密字串 "neo4j:yourpassword" 轉成 BASE64 編碼後放到 Authorization header,例如

Authorization: Basic bmVvNGo6bXlwYXNzd29yZA==

另一個作法則是直接附加在網址上,當然這樣就更不安全了

http://neo4j:yourpassword@localhost:7474/db/neo4j/tx

Trasantion Commit API

疑?怎麼一下子就跳到 Transaction API?這沒錯!Neo4j HTTP API 不管是新增、查詢、修改、刪除全都是共用這組交易 API,即使你沒有要使用交易,仍然是用交易的概念,在一次的 HTTP Request 直接完成交易並 Commit。

POST http://localhost:7474/db/neo4j/tx/commit
Content-Type: application/json

{
  "statements" : [ {
    "statement" : "MATCH (n) WHERE ID(n) = $nodeId RETURN n",
    "parameters" : {
      "nodeId" : 6
    }
  } ]
}

查詢的回傳結果有點冗長,我直接列出大概的結構出來

{
   "results": [
       {
          // first statement's results
           "columns": [],
           "data": [
               {
                   "row": [ row-data ],
                   "meta": [ metadata ]
               },
               {

               }
           ]
       },
       {
            // second statement’s results
       }
   ]
}

Begin Transaction API

接下來我們看看交易的完整流程如圖

Neo4j Cypher Transaction flow
(圖片來源:Neo4j 官網)

上圖中最下方那一條流程,就是剛才講過的,直接在一個 HTTP Request 中開啟交易後立即 Commit 結束交易。
其他則都是標準的交易流程,大約步驟如下:

  1. POST /db/neo4j/tx 開啟一個新的交易
  2. 再來就是根據回應的交易 API endpoint 持續進行交易,這時候會打
    POST /db/neo4j/tx/{transaction_id}
  3. 隨時都可以打 Commit API 確認此筆交易,或是 Rollback API 取消
    Commit: POST /db/neo4j/tx/{transaction_id}/commit
    Rollbak: DELETE /db/neo4j/tx/{transaction_id}

每一筆交易的預設 timeout 時間是 60 秒,超過就會自動被 Rollback。

例如,以下就是開啟一個新的交易,並建立兩個新的 Node

POST http://localhost:7474/db/neo4j/tx
Content-Type: application/json
Authorization: Basic bmVvNGo6bXlwYXNzd29yZA==

{
    "statements": [
        {
            "statement": "CREATE (n:Person $props) RETURN n",
            "parameters": {
                "props": {
                    "name": "Egg"
                }
            }
        },
                {
            "statement": "CREATE (n:Tech $props) RETURN n",
            "parameters": {
                "props": {
                    "name": "Neo4j"
                }
            }
        }
    ]
}

Request Body 結構上都是如此,可以在一個 HTTP Request 包含很多個 Cypher,或是分散到多個不同的交易要求,這部分就是各自的應用與需求去做變化了。

{
  "statements": [
    {
      "statement": "...",
      "parameters": {...}
    },
    {
      "statement": "...",
      "parameters": {...}
    },
    ...
  ]
}

延長交易

上面有說 Neo4j 預設的一個交易時間是 60 秒,如果想延長,可以丟一個空的交易內容如下:

{
  "statements" : [ ]
}

Rollback Transaction API

Rollback 只需要打 HTTP DELETE 即可

DELETE http://localhost:7474/db/neo4j/tx/{transaction_id}

查看統計資訊

如果想知道該筆查詢的細節資訊,可以加上 includeStats 如下

{
  "statements" : [ {
    "statement" : "CREATE (n:Person {name: 'Aura'}) RETURN n",
    "includeStats" : true
  } ]
}

以下是一個完整的開始新交易的回傳結果

{
    "results": [
        {
            "columns": [
                "n"
            ],
            "data": [
                {
                    "row": [
                        {
                            "name": "Aura"
                        }
                    ],
                    "meta": [
                        {
                            "id": 9,
                            "type": "node",
                            "deleted": false
                        }
                    ]
                }
            ],
            "stats": {
                "contains_updates": true,
                "nodes_created": 1,
                "nodes_deleted": 0,
                "properties_set": 1,
                "relationships_created": 0,
                "relationship_deleted": 0,
                "labels_added": 1,
                "labels_removed": 0,
                "indexes_added": 0,
                "indexes_removed": 0,
                "constraints_added": 0,
                "constraints_removed": 0,
                "contains_system_updates": false,
                "system_updates": 0
            }
        }
    ],
    "errors": [],
    "commit": "http://localhost:7474/db/neo4j/tx/18/commit",
    "transaction": {
        "expires": "Sat, 10 Oct 2020 16:30:48 GMT"
    }
}

回傳圖形結構資料

除了回傳的節點,若還需要周圍的關係和節點,可以加上 resultDataContents

{
  "statements" : [ {
    "statement" : "CREATE (n:Person {name: 'Aura'}) RETURN n",
    "resultDataContents" : [ "row", "graph" ],
    "includeStats" : true
  } ]
}

這可應用在需要自己設計完全客製的圖形化顯示 Neo4j 資料庫時使用,還記得第一篇說過的用 d3.js 呈現 Neo4j 嗎?就是有用到這個指令。

錯誤處理

需要注意的是,每個 Transaction API 回應的 HTTP Status Code 都是 200,除非 Cypher 語法明顯有誤,判斷是否有錯誤的一個依據是,看是否會有 transaction 這個 key,如果沒有,那表示你語法錯囉!

"transaction": {
    "expires": "Sat, 10 Oct 2020 16:04:24 GMT"
}

以上是今天的分享,學會 Neo4j HTTP API 之後,離自己寫前端應用不遠了~


上一篇
Neo4j Aura 雲端資料庫服務
下一篇
使用 JavaScript API 開發 Neo4j 應用程式
系列文
看圖說故事,讓 Neo4j 重新詮釋你的資料庫30

尚未有邦友留言

立即登入留言