Oracle Graph Server REST API (2023/08/25)

https://blogs.oracle.com/database/post/oracle-graph-server-rest-api

投稿者： Rahul Tasker | Senior Product Manager

Oracle Graphは、データ内の隠れた関係を明らかにするための強力なツールです。Oracle Graphは、グラフ構造で情報を表すことで、相互接続されたデータ・エンティティから貴重なインサイトを得ることができます。Oracle Graph製品には、単純なRESTコールにより、任意のアプリケーションからOracle Graphの機能を利用するゲートウェイであるGraph Server REST APIが含まれています。このAPIにより、開発者はグラフを操作でき、グラフの作成、問合せの実行およびデータからの実用的な情報の導出が可能になります

Oracle Graph REST API v1では、Cookieベースの認証を採用し、URL内で問合せをエンコードします。Oracle Graph Server and Clientリリース23.3では、Oracle Graph REST API v2をリリースしました。このAPIでは、トークンベースの認証を採用し、JSON本文内で問合せを送信できます。Graph Server REST APIは、開発者がグラフを簡単に作成および問い合せるための重要なリソースを提供します。

次の例の背景:

Oracle Graphには、Oracle Databaseでグラフ問合せを実行する機能と、専用のインメモリー・グラフ・サーバー(PGX)でグラフ問合せおよび分析を実行する機能があります。

bank_graphの例からデータをロードし、グラフを作成するには、このgithubリポジトリを参照してください。

Graph Server REST API v2

PostmanでGraph Server REST APIのバージョン2を使用した簡単な例を体験してみましょう。次のすべてのAPIコールについて、リクエストに次のヘッダーがあることを確認します:

• Accept: application/json、charset=UTF-8
• Content-Type: application/json

1. 認証トークンの取得

https://<Graph_Server_IP>:7007/auth/tokenへのPOSTリクエストを作成します。ユーザー名、パスワードおよびcreateSessionパラメータを含むJSON本文を追加します。

PGXセッションを作成してインメモリー・グラフ・サーバーで問合せを実行する場合は、createSessionパラメータをTrueに設定します。データベース内で問合せを実行する場合はFalseに設定します。

レスポンスは、次のAPIコールで使用するアクセス・トークンである必要があります。

2. グラフの取得

使用するドライバの問合せパラメータ(GRAPH_SERVER_PGX、PGQL_IN_DATABASEまたはSQL_IN_DATABASE)を使用して、https:// <Graph_Server_IP>:7007/v2/graphsへのGETリクエストを作成します。結果の問合せ文字列は、https:// <Graph_Server_IP>:7007/v2/graphs?driver=PGQL_IN_DATABASEのようになります。

'Bearer <access_token>'値を持つ認可ヘッダーを追加します。

応答は、認証されたユーザーのグラフのリストである必要があります。

3. 問合せの実行

https:// <Graph_Server_IP>:7007/v2/runQueryへのPOSTリクエストを作成します。

'Bearer <access_token>'値を持つ認可ヘッダーを追加します。

次の例のように、文、ドライバ、フォーマッタ、パラメータおよびビジュアル化パラメータを含むJSON本文を追加します。

{
  "statements": [
    "SELECT v FROM MATCH (v) ON BANK_GRAPH LIMIT 1"
  ],
  "driver": "PGQL_IN_DATABASE",
  "formatter": "GVT",
  "parameters": {
    "dynamicSampling": 2,
    "parallel": 8,
    "start": 0,
    "size": 100
  },
  "visualize": true
}

結果は、問合せ実行の結果を含むJSONオブジェクトである必要があります。

4. アクセス・トークンのリフレッシュ

アクセス・トークンが期限切れになる前にリフレッシュするには、https://<Graph_Server_IP>:7007/auth/tokenへのPUTリクエストを作成します。

トークンおよびcreateSessionパラメータを含むJSON本文を追加します。トークンには、現在のアクセス・トークンの値が必要です。PGXセッションを作成してインメモリー・グラフ・サーバーで問合せを実行する場合は、createSessionパラメータをTrueに設定します。データベース内で問合せを実行する場合はFalseに設定します。

レスポンスは新しいアクセス・トークンである必要があります。

Graph Server REST APIのv2および機能の完全なリストの詳細は、公式ドキュメントを参照してください。

Graph Server REST API v1

PostmanでGraph Server REST APIのバージョン1を使用した簡単な例を体験してみましょう。次のすべてのAPIコールについて、リクエストに次のヘッダーがあることを確認します:

• Accept: application/json、charset=UTF-8
• Content-Type: application/json

1. ユーザーの認証

https://<Graph_Server_IP>:7007/ui/v1/login/へのPOSTリクエストを作成します。

ユーザー名、パスワード、pgqlDriverおよびbaseUrlパラメータを含むJSON本文を追加します。pgqlDriverパラメータは、pgqlDriverを使用してデータベースに接続するか、またはpgxDriverを使用してグラフ・サーバーに接続するかを指定します。baseUrlパラメータは、pgxDriverを使用している場合はグラフ・サーバーのURLに、pgqlDriverを使用している場合はデータベースのJDBC URLにする必要があります。

応答は、認証されたユーザーのユーザー名である必要があります。正常にログインすると、サーバー・セッションCookieはCookieファイルcookie.txtに格納されます。

2. グラフのリスト

https://<Graph_Server_IP>:7007/ui/v1/graphsへのGETリクエストを作成します。Cookieは、自動的にヘッダーとしてPostmanに追加される必要があります。

応答は、認証されたユーザーのグラフのリストである必要があります。

3. 問合せの実行

pgql、graph、parallelismおよびsizeパラメータを使用して、https://<Graph_Server_IP>:7007/ui/v1/queryに対するGetリクエストを作成します。結果のURLは次のようになります。

https://<Graph_Server_IP>:7007/ui/v1/query?pgql=<PGQL_query>&graph=<graph_name>&parallelism= <parallelism_value>&size=<size>

たとえば、bank_graphから5つのエッジを問い合せるには、https://<Graph_Server_IP>:7007/ui/v1/query?pgql=SELECT%20e%0AMATCH%20()-%5Be%5D-%3E()%0ALIMIT%205&graph=BANK_GRAPH&parallelism=&size=100を使用します。

結果には、JSON形式で問い合せた結果の頂点およびエッジが含まれます。

4. Graph Serverのログアウト

https://<Graph_Server_IP>:7007/ui/v1/logout/へのPOSTリクエストを作成します。

ログアウトが成功すると、サーバーはHTTPステータス・コード200を返し、cookie.txtファイルのセッション・トークンが無効になります。

Graph Server REST APIのv1および機能の完全なリストの詳細は、公式ドキュメントを参照してください。