メインコンテンツまでスキップ

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

概要​

Teradata Query Service は、クライアント側のドライバを管理せずに標準 SQL ステートメントを実行するために使用できる Vantage 用の REST API です。REST API を介して Analytics データベースをクエリーしてアクセスする場合は、Query Service を使用します。

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

前提条件​

始める前に、以下のものが揃っていることを確認してください。 * クエリー サービスがプロビジョニングされている VantageCloud システム、またはクエリー サービスが有効な接続を備えた VantageCore へのアクセス。管理者であり、クエリー サービスをインストールする必要がある場合は、 クエリー サービスのインストール、構成、および使用ガイドを参照してください。

注記

Vantage のテストインスタンスが必要な場合は、 https://clearscape.teradata.com で無料でプロビジョニングできます

* クエリーサービスのホスト名とシステム名

  • データベースに接続するための認証情報

前提条件に問題がありますか? セットアップ情報については 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 応答には、認証方法とエンコードされた資格情報が含まれます。

リクエスト

応答

JWT認証​

前提条件:

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

リクエスト

応答

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

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

  • SELECT * FROM DBC.DBCInfo: エイリアス <SYSTEM_NAME> を持つシステムへのクエリー。

  • 'format': 'OBJECT': 応答の形式。サポートされている形式は、JSON オブジェクト、JSON 配列、および CSV です。

    注記

    JSONオブジェクト フォーマットでは、列名がフィールド名、列値がフィールド値である行ごとに1つのJSONオブジェクトが作成されます。

  • 'includeColumns': true: 列名や型などの列メタデータをレスポンスに含めるかどうかのリクエスト。

  • 'rowLimit': 4: クエリーから返される行の数。

リクエスト

応答

応答パラメータについては クエリー サービスのインストール、構成、および使用ガイドを参照してください。

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

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

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

リクエスト

応答

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

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

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

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

    リクエスト

    応答

  2. ステップ1で作成したセッションを使用してクエリーを送信します

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

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

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

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

    リクエスト

    応答

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

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

  1. ターゲットシステムに非同期クエリーを送信し、クエリーIDを取得します。 /system/<SYSTEM_NAME>/queries エンドポイントにPOSTリクエストを送信します。 以下の例では、リクエストには以下のものが含まれます。 * SELECT * FROM DBC.DBCInfo: エイリアス <SYSTEM_NAME> を持つシステムへのクエリー。 * 'format': 'OBJECT': 応答の形式。 * 'spooled_result_set': True: リクエストが非同期であることを示します。

    Request

    Response

  2. ステップ1で取得したIDを使用してクエリーの詳細を取得します。

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

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

    リクエスト

    応答

  3. 非同期クエリーの結果セットを表示する

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

    リクエストは、送信されたクエリーによって生成された結果セットと更新カウントの配列を返します。

    リクエスト

    応答

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

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

リクエスト

応答

リソース​

注記

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

興味深い記事