Jak połączyć się z API Neo4j?

Neo4j domyślnie oferuje wygodny interfejs w postaci konsoli uruchamianej w przeglądarce webowej. Wystarczy połączyć się z adresem hosta na którym uruchomiona jest baza Neo4j, z portem 7474, np:

http://10.0.0.1:7474

Używając komend bazy danych, Cypher, możemy np. importować i eksportować pliki.Jednak taki sposób pracy nie daje możliwości automatyzacji zadań. Jeśli chcemy wykorzystywać silnik neo4j z poziomu innych aplikacji, automatycznie przetwarzać dane lub wygodnie pracować z grafową bazą danych potrzebujemy innej możliwości korzystania z zasobów Neo4j.

Z bazą Neo4j możemy połączyć się na kilka sposóbów. Dwa głowne to wykorzystanie sterowników oraz połączenie z wbudowanym HTTP API.

Korzystanie z gotowych bibliotek/sterówników

Neo4j oferuje gotowe oficjalne i nieoficjalne sterowniki do łączenia się z bazą z różnych środowisk. Na ich stronie znajdziemy gotowe biblioteki dla Java, Python, JavaScript, .NET, GO, Perl, PHP i inne. Niektóre ETL mają już te sterowniki wbudowane w rozszerzenia które umożliwiają połączenie się z Neo4j.

Posiadając odpowiedni sterownik możemy korzystać ze środowiska grafowej bazy danych bezpośrednio z danego języka oprogramowania/aplikacji.

Łączenie się z Neo4j HTTP API

Uruchomiona baza Neo4j posiada gotowy do użycia HTTP API. Dokumentacja do aktualnej wersji znajduje sie tutaj. Wysyłamy zapytania i odbieramy dane z tego API w formacie JSON. Daje to nam bardzo dużą swobodę; połączymy się Neo4j z każdego systemu/aplikacji.

Neo4j HTTP API umożliwia wykonanie serii instrukcji Cypher w ramach transakcji. Transakcja może być otwarta dla wielu żądań HTTP, dopóki klient nie zdecyduje się zatwierdzić lub wycofać. Każde żądanie HTTP może zawierać listę poleceń, a dla wygody możesz dołączyć polecenia wraz z żądaniem rozpoczęcia lub zatwierdzenia transakcji.

Możemy sprawdzić gotowość API odpytując:

GET http://host:7474/

W odpowiedzi otrzymamy:

{
  "bolt_direct": "bolt://host:7687",
  "bolt_routing": "neo4j://host:7687",
  "cluster": "http://host:7687/db/{databaseName}/cluster",
  "transaction": "http://host:7687/db/{databaseName}/tx",
  "neo4j_version": "4.1.1",
  "neo4j_edition": "community"
}

OK, jak widać API jest gotowe na nasze zapytania. By jednak produkcyjnie wykorzystywać naszą bazę musimy się zalogować.

Autoryzacja w API

Byśmy mogli odczytać lub zapisać dane w Neo4j musimy się tam zautoryzować. Autoryzacja może być przeprowadzona na dwa sposóby. Pierwszy to wysłanie nagłówka 'Authorization' w zapytaniu do API. Np:

Authorization: Basic dGVzdC5hY

Jak utworzyć hash basic? Uzyskujemy go kodujac frazę 'użytkownik:hasło' funkcją Base64.

Drugi sposób atoryzacji, prostszy, to link który zawiera dane logowania. Przykład takiego url:

http://neo4j:haslo@10.0.0.1:7474

Komunikacja z API

Komunikujemy się HTTP API Neo4j wysyłając zapytania i odbieramy odpowiedzi w formacie JSON. Zapytania wysyłamy używając metody POST. HTTP Neo4j umożliwia wykonanie serii instrukcji Cypher w ramach transakcji. Transakcja może być otwarta dla wielu żądań HTTP, dopóki klient nie zdecyduje się zatwierdzić lub wycofać transakcje.

Tak więc by wykonać zapytanie nawiązujemy dwukrotnie połączenie z HTTP API. W Pierwszym rządaniu otwieramy transakcję, w drugim zatwierdzamy transakcję. W poniższym przykłądzie wybieramy parametry węzła 0.

Otwieramy transakcję i wysyłamy polecenie:

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


W rezultacie HTTP API odpowie:

{"results":[],"errors":[],"commit":"http://localhost:7474/db/neo4j/tx/18/commit","transaction":{"expires":"Fri, 2 Oct 2060 15:49:42 GMT"}}

Obiekt 'commit' odpowiedzi zawiera URL pod który należy wysłać następne zapytania by potwierdzić transakcje. Mamy na to 60 sekund - możemy przedłużyć sesję transakcji wysyłając np puste zapytanie.

Zatem by zatwierdzić transakcję, łączymy się raz jeszcze z API pod wskazanym adresem.

Powodzenia!