REST APIを使ってVantageにクエリーを送信する方法

概要

Teradata Query Service は、Vantage 用の REST API で、これを使用すると、クライアント側のドライバを管理せずに標準的な SQL 文を実行できます。REST API を使用して Analytics データベースにクエリおよびアクセスする場合は、Query Service を使用します。

このハウツーでは、Query Service を使い始めるのに役立つ、一般的な使用例を紹介します。

前提条件

始める前に、以下のものが揃っていることを確認してください。

Query Service がプロビジョニングされている VantageCloud システム、または Query Service が有効な接続を備えた VantageCore へのアクセス。管理者で、Query Service をインストールする必要がある場合は、 Query Service のインストール、構成、および使用ガイドを参照してください。

If you need a test instance of Vantage, you can provision one for free at https://clearscape.teradata.com.
Query Service のホスト名とシステム名
データベースに接続するための認証情報

前提条件に問題がありますか？設定情報については、Teradataに連絡してください。

Query Service API の例

例題を使用する際は、以下の点に注記してください。

このドキュメントではPythonを使用していますが、これを利用してお好きな言語でサンプルを作成することができます。

ここで提供されるサンプルは完全なものであり、すぐに使用できますが、ほとんどの場合、多少のカスタマイズが必要です。

このドキュメントの例では、URL https://<QS_HOSTNAME>:1443/ を使用しています。

以下の変数を独自の値に置き換えます。

<QS_HOSTNAME>: Query Service がインストールされているサーバー

<SYSTEM_NAME>: システムの事前設定されたエイリアス

VantageインスタンスがClearScape Analytics Experienceを通じて提供される場合、<QS_HOSTNAME>はClearScape Analytics ExperienceのホストURLであり、<SYSTEM_NAME>は「ローカル」です。

Query Service インスタンスへの接続

HTTP Basic 認証または JWT 認証を使用してターゲット Analytics データベースにアクセスするための有効な認証情報を提供します。

HTTP基本認証

データベースのユーザ名とパスワードは、文字列("username : password")に結合され、Base64を使用してエンコードされています。API 応答には、認証メソッドとエンコードされた信頼証明が含まれます。

リクエスト

import requests
import json
import base64
requests.packages.urllib3.disable_warnings()

# run it from local.

db_user, db_password = 'dbc','dbc'
auth_encoded = db_user + ':' + db_password
auth_encoded = base64.b64encode(bytes(auth_encoded, 'utf-8'))
auth_str = 'Basic ' + auth_encoded.decode('utf-8')

print(auth_str)

headers = {
  'Content-Type': 'application/json',
  'Authorization': auth_str # base 64 encoded username:password
}

print(headers)

応答

Basic ZGJjOmRiYw==
{
  'Content-Type': 'application/json',
  'Authorization': 'Basic ZGJjOmRiYw=='
}

JWT認証

前提条件:

ユーザーはデータベースにすでに存在している必要があります。
データベースはJWT対応である必要があります。

リクエスト

import requests
import json
requests.packages.urllib3.disable_warnings()

# run it from local.

auth_encoded_jwt = "<YOUR_JWT_HERE>"
auth_str = "Bearer " + auth_encoded_jwt

headers = {
  'Content-Type': 'application/json',
  'Authorization': auth_str
}

print(headers)

応答

{'Content-Type': 'application/json', 'Authorization': 'Bearer <YOUR_JWT_HERE>'}

基本的なオプションで簡単なAPIリクエストを行う

以下の例では、リクエストの内容は以下の通りです。

SELECT * FROM DBC.DBCInfo: エイリアス `<SYSTEM_NAME>`を持つシステムへのクエリー。
'format': 'OBJECT': 応答の形式。サポートされているフォーマットは、JSONオブジェクト、JSON配列、CSVです。

JSONオブジェクトフォーマットでは、列名がフィールド名、列値がフィールド値である行ごとに1つのJSONオブジェクトが作成されます。
'includeColumns': true: 列名や型などの列メタデータをレスポンスに含めるかどうかのリクエスト。
'rowLimit': 4: クエリーから返される行の数。

リクエスト

url = 'https://<QS_HOSTNAME>:1443/systems/<SYSTEM_NAME>/queries'

payload = {
  'query': example_query, # 'SELECT * FROM DBC.DBCInfo;',
  'format': 'OBJECT',
  'includeColumns': True,
  'rowLimit': 4
}

payload_json = json.dumps(payload)

response = requests.request('POST', url, headers=headers, data=payload_json, verify=False)

num_rows = response.json().get('results')[0].get('rowCount')
print('NUMBER of ROWS', num_rows)
print('==========================================================')

print(response.json())

応答

NUMBER of ROWS 4
==========================================================
{
  "queueDuration":7,
  "queryDuration":227,
  "results":[
    {
      "resultSet":True,
      "columns":[
        {
          "name":"DatabaseName",
          "type":"CHAR"
        },
        {
          "name":"USEDSPACE_IN_GB",
          "type":"FLOAT"
        },
        {
          "name":"MAXSPACE_IN_GB",
          "type":"FLOAT"
        },
        {
          "name":"Percentage_Used",
          "type":"FLOAT"
        },
        {
          "name":"REMAININGSPACE_IN_GB",
          "type":"FLOAT"
        }
      ],
      "data":[
        {
          "DatabaseName":"DBC",
          "USEDSPACE_IN_GB":317.76382541656494,
          "MAXSPACE_IN_GB":1510.521079641879,
          "Percentage_Used":21.03670247964377,
          "REMAININGSPACE_IN_GB":1192.757254225314
        },
        {
          "DatabaseName":"EM",
          "USEDSPACE_IN_GB":0.0007491111755371094,
          "MAXSPACE_IN_GB":11.546071618795395,
          "Percentage_Used":0.006488017745513208,
          "REMAININGSPACE_IN_GB":11.545322507619858
        },
        {
          "DatabaseName":"user10",
          "USEDSPACE_IN_GB":0.019153594970703125,
          "MAXSPACE_IN_GB":9.313225746154785,
          "Percentage_Used":0.20566016,
          "REMAININGSPACE_IN_GB":9.294072151184082
        },
        {
          "DatabaseName":"EMEM",
          "USEDSPACE_IN_GB":0.006140708923339844,
          "MAXSPACE_IN_GB":4.656612873077393,
          "Percentage_Used":0.13187072,
          "REMAININGSPACE_IN_GB":4.650472164154053
        },
        {
          "DatabaseName":"EMWork",
          "USEDSPACE_IN_GB":0.0,
          "MAXSPACE_IN_GB":4.656612873077393,
          "Percentage_Used":0.0,
          "REMAININGSPACE_IN_GB":4.656612873077393
        }
      ],
      "rowCount":4,
      "rowLimitExceeded":True
    }
  ]
}

応答パラメータについては、「Query Service インストール、構成、および使用ガイド」を参照してください。

CSV形式での応答リクエスト

APIレスポンスをCSV形式で返すには、リクエストの format フィールドに CSV という値を設定します。

CSV 形式にはクエリー結果のみが含まれ、応答メタデータは含まれません。応答には行ごとに 1 行が含まれており、各行にはカンマで区切られた行列が含まれます。以下の例では、データをカンマ区切り値として返します。

リクエスト

# CSV with all rows included

url = 'https://<QS_HOSTNAME>:1443/systems/<SYSTEM_NAME>/queries'

payload = {
  'query': example_query, # 'SELECT * FROM DBC.DBCInfo;',
  'format': 'CSV',
  'includeColumns': True
}

payload_json = json.dumps(payload)

response = requests.request('POST', url, headers=headers, data=payload_json, verify=False)

print(response.text)

応答

DatabaseName,USEDSPACE_IN_GB,MAXSPACE_IN_GB,Percentage_Used,REMAININGSPACE_IN_GB
DBC                           ,317.7634754180908,1510.521079641879,21.036679308932754,1192.7576042237881
EM                            ,7.491111755371094E-4,11.546071618795395,0.006488017745513208,11.545322507619858
user10                        ,0.019153594970703125,9.313225746154785,0.20566016,9.294072151184082
EMEM                          ,0.006140708923339844,4.656612873077393,0.13187072,4.650472164154053
EMWork                        ,0.0,4.656612873077393,0.0,4.656612873077393
EMJI                          ,0.0,2.3283064365386963,0.0,2.3283064365386963
USER_NAME                     ,0.0,2.0,0.0,2.0
readonly                      ,0.0,0.9313225746154785,0.0,0.9313225746154785
aug12_db                      ,7.200241088867188E-5,0.9313225746154785,0.0077312,0.9312505722045898
SystemFe                      ,1.8024444580078125E-4,0.7450580596923828,0.024192,0.744877815246582
dbcmngr                       ,3.814697265625E-6,0.09313225746154785,0.004096,0.09312844276428223
EMViews                       ,0.027594566345214844,0.09313225746154785,29.62944,0.06553769111633301
tdwm                          ,6.732940673828125E-4,0.09313225746154785,0.722944,0.09245896339416504
Crashdumps                    ,0.0,0.06984921544790268,0.0,0.06984921544790268
SYSLIB                        ,0.006252288818359375,0.03725290298461914,16.78336,0.031000614166259766
SYSBAR                        ,4.76837158203125E-6,0.03725290298461914,0.0128,0.03724813461303711
SYSUDTLIB                     ,3.5381317138671875E-4,0.029802322387695312,1.1872,0.029448509216308594
External_AP                   ,0.0,0.01862645149230957,0.0,0.01862645149230957
SysAdmin                      ,0.002307891845703125,0.01862645149230957,12.3904,0.016318559646606445
KZXaDtQp                      ,0.0,0.009313225746154785,0.0,0.009313225746154785
s476QJ6O                      ,0.0,0.009313225746154785,0.0,0.009313225746154785
hTzz03i7                      ,0.0,0.009313225746154785,0.0,0.009313225746154785
Y5WYUUXj                      ,0.0,0.009313225746154785,0.0,0.009313225746154785

明示的なセッションを使用してクエリーを送信する

トランザクションが複数のリクエストにまたがる必要がある場合や、揮発性のテーブルを使用する場合は、明示的なセッションを使用します。これらのセッションは、クエリーリクエストでセッションを参照する場合にのみ再利用されます。リクエストがすでに使用されている明示的セッションを参照する場合、リクエストはキューに入れられます。

セッションを作成します。

POST リクエストを /system/<SYSTEM_NAME>/sessions エンドポイントに送信します。リクエストは新しいデータベースセッションを作成し、セッションの詳細を応答として返します。

以下の例では、リクエストに `'auto_commit':True` - 完了時にクエリーをコミットするリクエストが含まれています。

リクエスト

# first create a session
url = 'https://<QS_HOSTNAME>:1443/systems/<SYSTEM_NAME>/sessions'

payload = {
  'auto_commit': True
}

payload_json = json.dumps(payload)

response = requests.request('POST', url, headers=headers, data=payload_json, verify=False)

print(response.text)

応答

{
  'sessionId': 1366010,
  'system': 'testsystem',
  'user': 'dbc',
  'tdSessionNo': 1626922,
  'createMode': 'EXPLICIT',
  'state': 'LOGGINGON',
  'autoCommit': true
}

手順1で作成したセッションを使用して、クエリーを送信します。

/system/<SYSTEM_NAME>/queries エンドポイントに POST リクエストを送信します。

リクエストでは、対象システムに対してクエリーを送信し、対象システムのリリース番号とバージョン番号を返します。

以下の例では、リクエストには以下のものが含まれます。

SELECT * FROM DBC.DBCInfo: エイリアス <SYSTEM_NAME> を持つシステムへのクエリー。
'format': 'OBJECT':応答の形式。
'Session' : <Session ID>:明示的なセッションを作成するためにステップ1で返されたセッションID。

リクエスト

# use this session to submit queries afterwards

url = 'https://<QS_HOSTNAME>:1443/systems/<SYSTEM_NAME>/queries'

payload = {
  'query': 'SELECT * FROM DBC.DBCInfo;',
  'format': 'OBJECT',
  'session': 1366010 # <-- sessionId
}
payload_json = json.dumps(payload)

response = requests.request('POST', url, headers=headers, data=payload_json, verify=False)

print(response.text)

応答

{
  "queueDuration":6,
  "queryDuration":41,
  "results":[
    {
      "resultSet":true,
      "data":[
        {
          "InfoKey":"LANGUAGE SUPPORT MODE",
          "InfoData":"Standard"
        },
        {
          "InfoKey":"RELEASE",
          "InfoData":"15.10.07.02"
        },
        {
          "InfoKey":"VERSION",
          "InfoData":"15.10.07.02"
        }
      ],
      "rowCount":3,
      "rowLimitExceeded":false
    }
  ]
}

非同期クエリーを使用する

非同期クエリーは、大量のデータや長時間実行するクエリーによってシステムやネットワークのパフォーマンスに影響を与える場合に使用します。

非同期クエリーをターゲットシステムに送信し、クエリー IDを取得します。

POST リクエストを /system/<SYSTEM_NAME>/queries エンドポイントに送信します。

以下の例では、リクエストには以下のものが含まれます。
- SELECT * FROM DBC.DBCInfo: エイリアス `<SYSTEM_NAME>`を持つシステムへのクエリー。
- 'format': 'OBJECT':応答の形式。
- 'spooled_result_set': True: リクエストが非同期であることを示します。
リクエスト

## Run async query . url = 'https://<QS_HOSTNAME>:1443/systems/<SYSTEM_NAME>/queries' payload = { 'query': 'SELECT * FROM DBC.DBCInfo;', 'format': 'OBJECT', 'spooled_result_set': True } payload_json = json.dumps(payload) response = requests.request('POST', url, headers=headers, data=payload_json, verify=False) print(response.text)
応答

{"id":1366025}
ステップ 1 で取得した ID を使用してクエリーの詳細を取得します。

GET リクエストを /system/<SYSTEM_NAME>/queries/<queryID> エンドポイントに送信し、 <queryID> をステップ 1 で取得した ID に置き換えます。

リクエストは、 queryState、 queueOrder、 queueDuration などを含む特定のクエリーの詳細を返します。応答フィールドの完全なリストとその説明については、「Query Service のインストール、構成、および使用ガイド」を参照してください。

リクエスト
```
## response for async query .

url = 'https://<QS_HOSTNAME>:1443/systems/<SYSTEM_NAME>/queries/1366025'

payload_json = json.dumps(payload)
response = requests.request('GET', url, headers=headers, verify=False)

print(response.text)
```
応答
```
{
  "queryId":1366025,
  "query":"SELECT * FROM DBC.DBCInfo;",
  "batch":false,
  "system":"testsystem",
  "user":"dbc",
  "session":1366015,
  "queryState":"RESULT_SET_READY",
  "queueOrder":0,
  "queueDuration":6,
  "queryDuration":9,
  "statusCode":200,
  "resultSets":{

  },
  "counts":{

  },
  "exceptions":{

  },
  "outParams":{

  }
}
```

非同期クエリーの結果セットを表示します

 GET リクエストを `/system/<SYSTEM_NAME>/queries/<queryID>/results` エンドポイントに送信し、 `<queryID>` をステップ 1 で取得した ID に置き換えます。
リクエストは、送信されたクエリーによって生成された結果セットと更新カウントの配列を返します。

リクエスト

url = 'https://<QS_HOSTNAME>:1443/systems/<SYSTEM_NAME>/queries/1366025/results'

payload_json = json.dumps(payload)
response = requests.request('GET', url, headers=headers, verify=False)

print(response.text)

応答

{
  "queueDuration":6,
  "queryDuration":9,
  "results":[
    {
      "resultSet":true,
      "data":[
        {
          "InfoKey":"LANGUAGE SUPPORT MODE",
          "InfoData":"Standard"
        },
        {
          "InfoKey":"RELEASE",
          "InfoData":"15.10.07.02"
        },
        {
          "InfoKey":"VERSION",
          "InfoData":"15.10.07.02"
        }
      ],
      "rowCount":3,
      "rowLimitExceeded":false
    }
  ]
}

アクティブまたはキューイングされたクエリーのリストを取得する

/system/<SYSTEM_NAME>/queries エンドポイントにGET リクエストを送信します。リクエストはアクティブなクエリーの ID を返します。

リクエスト

url = 'https://<QS_HOSTNAME>:1443/systems/<SYSTEM_NAME>/queries'

payload={}

response = requests.request('GET', url, headers=headers, data=payload, verify=False)

print(response.json())

応答

[
  {
    "queryId": 12516087,
    "query": "SELECt * from dbcmgr.AlertRequest;",
    "batch": false,
    "system": "BasicTestSys",
    "user": "dbc",
    "session": 12516011,
    "queryState": "REST_SET_READY",
    "queueOrder": 0,
    "queueDurayion": 3,
    "queryDuration": 3,
    "statusCode": 200,
    "resultSets": {},
    "counts": {},
    "exceptions": {},
    "outparams": {}
  },
  {
    "queryId": 12516088,
    "query": "SELECt * from dbc.DBQLAmpDataTbl;",
    "batch": false,
    "system": "BasicTestSys",
    "user": "dbc",
    "session": 12516011,
    "queryState": "REST_SET_READY",
    "queueOrder": 0,
    "queueDurayion": 3,
    "queryDuration": 3,
    "statusCode": 200,
    "resultSets": {},
    "counts": {},
    "exceptions": {},
    "outparams": {}
  }
]

リソース

機能、例、および参考資料: クエリサービスのインストール、設定、および使用ガイド
Query Service API OpenAPI 仕様

ご質問がある場合、またはさらにサポートが必要な場合は、コミュニティフォーラムにアクセスしてサポートを受け、他のコミュニティメンバーと交流してください。

このページは役に立ちましたか?