18 グラフ・サーバーのRESTエンドポイント

この項では、グラフ・サーバーのRESTエンドポイントについて説明します:

使用可能なRESTエンドポイントは次のとおりです。

ノート:

RESTエンドポイントに示されている例では、次のことを前提としています。

  • PGXサーバーは、https://localhost:7007で稼働中です。
  • cURLを含むLinuxがインストールされています。cURLは、グラフ・サーバーの検証にCA証明書を使用してgraph.publish APIにアクセスする方法を示すために使用されます。

18.1 ログイン

HTTPリクエスト: POST https://localhost:7007/ui/v1/login/

認証: Cookieベースの認証を使用します。

表18-1 パラメータ

パラメータ パラメータ・タイプ 必須
Content-type ヘッダー application/json はい
username 本文 <username> はい
password 本文 <password> はい
baseUrl 本文 グラフ・サーバー(PGX)またはデータベースを指す<baseUrl> オプション。空の場合、web.xmlファイル内のpgx.base_urlパラメータ値が使用されます。web.xmlファイルの場所については、表19-1を参照してください。
pgqlDriver 本文 有効なPGQLドライバの構成値は次のとおりです。
  • pgxDriver: グラフ・サーバー上のPGQL (PGX)の場合
  • pgqlDriver: Oracle Database上のPGQLの場合
はい
sessionId 本文 グラフ・サーバー(PGX)からのsessionId オプション

リクエスト

次のcurlコマンドは、グラフ・サーバーにユーザーをサインインします:

curl --cacert /etc/oracle/graph/ca_certificate.pem -c cookie.txt -X POST -H "Content-Type: application/json" -d '{"username": "<username>", "password": "<password>", "pgqlDriver": "<pgqlDriver>","baseUrl": "<baseUrl>", "sessionId": "<sessionId>" }' https://localhost:7007/ui/v1/login/
レスポンス: ログインに使用されたusername。たとえば:
"oracle"

ログインに成功すると、サーバー・セッションCookieがCookieファイルcookie.txtに格納されます。APIへのその後のコールで、このCookieファイルを使用します。

18.2 グラフのリスト

GET /v2/graphs

HTTPリクエスト: GET https://localhost:7007/ui/v2/graphs

リクエスト

次のcurlコマンドは、ユーザーがアクセスできるすべてのグラフをスキーマ情報とともにリストします。

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v2/graphs'

レスポンス: 現在のユーザーが使用できるグラフおよびスキーマの詳細のリスト。たとえば:

[
  {
    "schema": "HR",
    "graphName": "MY_GRAPH"
  }
]

また、schemaパラメータは、グラフ・サーバー(PGX)で作成されたグラフの場合、NULLになることに注意してください。

GET /v1/graphs

ノート:

/v1/graphsエンドポイントは、Graph Server and Clientの将来のリリースで非推奨になる可能性があります。したがって、/v2/graphsエンドポイントを使用して、ユーザーのすべてのグラフをリストすることをお薦めします。
HTTPリクエスト: GET https://localhost:7007/ui/v1/graphs

リクエスト

次のcurlコマンドは、ユーザーに属するすべてのグラフをリストします。

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/graphs'

レスポンス: 現在のユーザーが使用できるグラフのリスト。たとえば:

["hr", "bank_graph_analytics"]

18.3 PGQL問合せの実行

HTTPリクエスト: GET https://localhost:7007/ui/v1/query?pgql=<PGQL_query>&graph=<graph_name>&parallelism=<parallelism_value>&size=<size_value>&formatter=<formatter_value>

表18-2 問合せパラメータ

パラメータ 説明 必須
pgql PGQL問合せ文字列 <PGQL_query> はい
graph グラフの名前 <graph_name> pgql問合せパラメータにグラフ名が含まれている場合にのみ、オプションです。それ以外の場合は、必須です。
parallelism 並列度 <parallelism_value> オプション。
デフォルト値は、PGQLドライバ構成によって異なります。
  • pgxDriver: <number-of-cpus>

    表21-1parallelismを参照してください。

  • pgqlDriver: 1
size 問合せ結果のフェッチ・サイズ(=行数) <size_value> オプション。サイズのデフォルト値は100です。
formatter グラフのフォーマッタ <formatter_value> オプション。
サポートされているフォーマッタは次のとおりです:
  • datastudio
  • gvt

デフォルト値はdatastudioです。

リクエスト

次のcurlコマンドは、プロパティ・グラフでPGQL問合せを実行します。

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/query?pgql=SELECT%20e%0AMATCH%20()-%5Be%5D-%3E()%0ALIMIT%205&graph=hr&size=100'

レスポンス: PGQL問合せの結果はJSON形式になります。

{
  "name": "bank_graph_analytics_2",
  "resultSetId": "pgql_14",
  "graph": {
    "idType": "number",
    "vertices": [
      {
        "_id": "1",
        "p": [],
        "l": [
          "Accounts"
        ],
        "g": [
          "anonymous_1"
        ]
      },
      {
        "_id": "418",
        "p": [],
        "l": [
          "Accounts"
        ],
        "g": [
          "anonymous_2"
        ]
      },
      {
        "_id": "259",
        "p": [],
        "l": [
          "Accounts"
        ],
        "g": [
          "anonymous_2"
        ]
      }
    ],
    "edges": [
      {
        "_id": "0",
        "p": [
          {
            "n": "AMOUNT",
            "v": "1000.0",
            "s": false
          }
        ],
        "l": [
          "Transfers"
        ],
        "g": [
          "e"
        ],
        "s": "1",
        "d": "259",
        "u": false
      },
      {
        "_id": "1",
        "p": [
          {
            "n": "AMOUNT",
            "v": "1000.0",
            "s": false
          }
        ],
        "l": [
          "Transfers"
        ],
        "g": [
          "e"
        ],
        "s": "1",
        "d": "418",
        "u": false
      }
    ],
    "paths": [],
    "totalNumResults": 2
  },
  "table": "e\nPgxEdge[provider=Transfers,ID=0]\nPgxEdge[provider=Transfers,ID=1]"
}

18.4 ユーザーの取得

HTTPリクエスト: GET https://localhost:7007/ui/v1/user

リクエスト

次のcurlコマンドは、現行ユーザーの名前を取得します。

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/user'

レスポンス: 現行ユーザーの名前。たとえば:

"oracle"

18.5 ログアウト

HTTPリクエスト: POST https://localhost:7007/ui/v1/logout/

リクエスト

次のcurlコマンドによって、グラフ・ビジュアライゼーション・アプリケーションから正常にログアウトします。

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt -X POST 'https://localhost:7007/ui/v1/logout/'

レスポンス: なし

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

18.6 非同期RESTエンドポイント

グラフ・サーバーのRESTエンドポイントは、問合せの取消しをサポートしています。

問合せを取り消すには、次の非同期RESTエンドポイントを使用して問合せを送信する必要があります。

18.6.1 PGQL問合せの非同期実行

HTTPリクエスト: GET https://localhost:7007/ui/v1/async-query?pgql=<PGQL query>&graph=<graph>&parallelism=<value>&size=<size value>

問合せパラメータの詳細は、表18-2を参照してください。

リクエスト

次のcurlコマンドは、プロパティ・グラフでPGQL問合せを非同期に実行します。

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-query?pgql=SELECT%20e%0AMATCH%20()-%5Be%5D-%3E()%0ALIMIT%205&graph=hr&parallelism=&size=100'

レスポンス: なし。

ノート:

問合せの形式が正しくない場合、またはグラフが存在しない場合は、エラー・メッセージが返されます。

18.6.2 問合せ完了の確認

HTTPリクエスト: GET https://localhost:7007/ui/v1/async-query-complete

リクエスト

次のcurlコマンドは、PGQL問合せの実行が完了しているかどうかを確認します。

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-query-complete'

レスポンス: 問合せの実行が完了したかどうかを示すブール。たとえば、

true

ノート:

現在実行中の問合せはHTTPセッションにアタッチされているため、リクエストIDを指定する必要はありません。セッションごとに1つの問合せのみを実行できます。問合せを同時実行するには、複数回ログインして複数のHTTPセッションを作成します。

18.6.3 問合せ実行の取消し

HTTPリクエスト: DELETE https://localhost:7007/ui/v1/async-query

リクエスト

次のcurlコマンドは、プロパティ・グラフで現在実行中のPGQL問合せを取り消します。

curl -X DELETE --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-query'

レスポンス: 取消しの確認か、問合せの実行がすでに完了している場合はエラー・メッセージ。

18.6.4 問合せ結果の取得

HTTPリクエスト: GET https://localhost:7007/ui/v1/async-result

ノート:

次のような、問合せ結果を取得するエンドポイントGET https://localhost:7007/ui/v1/async-result?pgql=<PGQL query>&graph=<graph>&parallelism=<value>&size=<size value>は非推奨となりました。
curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-result?pgql=SELECT%20e%0AMATCH%20()-%5Be%5D-%3E()%0ALIMIT%205&graph=hr&parallelism=&size=100'

リクエスト

次のcurlコマンドは、正常に完了した問合せの結果を取得します。

curl --cacert /etc/oracle/graph/ca_certificate.pem -b cookie.txt 'https://localhost:7007/ui/v1/async-result'

レスポンス: PGQL問合せの結果はJSON形式になります。

{
  "name": "bank_graph_analytics_2",
  "resultSetId": "pgql_14",
  "graph": {
    "idType": "number",
    "vertices": [
      {
        "_id": "1",
        "p": [],
        "l": [
          "Accounts"
        ],
        "g": [
          "anonymous_1"
        ]
      },
      {
        "_id": "418",
        "p": [],
        "l": [
          "Accounts"
        ],
        "g": [
          "anonymous_2"
        ]
      },
      {
        "_id": "259",
        "p": [],
        "l": [
          "Accounts"
        ],
        "g": [
          "anonymous_2"
        ]
      }
    ],
    "edges": [
      {
        "_id": "0",
        "p": [
          {
            "n": "AMOUNT",
            "v": "1000.0",
            "s": false
          }
        ],
        "l": [
          "Transfers"
        ],
        "g": [
          "e"
        ],
        "s": "1",
        "d": "259",
        "u": false
      },
      {
        "_id": "1",
        "p": [
          {
            "n": "AMOUNT",
            "v": "1000.0",
            "s": false
          }
        ],
        "l": [
          "Transfers"
        ],
        "g": [
          "e"
        ],
        "s": "1",
        "d": "418",
        "u": false
      }
    ],
    "paths": [],
    "totalNumResults": 2
  },
  "table": "e\nPgxEdge[provider=Transfers,ID=0]\nPgxEdge[provider=Transfers,ID=1]"
}