Oracle Graph Server REST API (2023/08/25)
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>¶llelism= <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¶llelism=&size=100を使用します。
結果には、JSON形式で問い合せた結果の頂点およびエッジが含まれます。
4. Graph Serverのログアウト
https://<Graph_Server_IP>:7007/ui/v1/logout/へのPOSTリクエストを作成します。
ログアウトが成功すると、サーバーはHTTPステータス・コード200を返し、cookie.txtファイルのセッション・トークンが無効になります。
Graph Server REST APIのv1および機能の完全なリストの詳細は、公式ドキュメントを参照してください。
コメント
コメントを投稿