> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.cdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Connect AI は、HTTP リクエストを作成可能な REST 対応アプリケーションやインテグレーションツールがデータのクエリ、バッチクエリ操作の実行、アカウントに設定されたすべてのデータソースにわたるストアドプロシージャの実行を可能にする、フル機能の API を提供しています。この API は JSON 形式の API に基づいています。Connect AI API のベース URL は `https://cloud.cdata.com/api` です。

## 認証

Connect AI API へのすべてのリクエストは、OAuth または基本認証を使用して適切に認証される必要があります。詳細については、[認証](/ja/API/Authentication) を参照してください。

## ワークスペース

ワークスペースをクエリするには、REST API URL に「workspace」という名前の URL パラメータを追加します。クエリするワークスペースの名前をこれに設定します。これはメタデータエンドポイントの GET 操作と、クエリおよびバッチエンドポイントの POST 操作の両方で機能します。なお、/exec エンドポイントはワークスペースをサポートしていません。

## レスポンス形式

Connect AI API の操作は、操作によって以下を含む可能性がある共通のレスポンス形式を共有しています。

* 1つ以上の結果セット（以下を含む）：
  * 結果カラムのメタデータ
  * 行の値（存在する場合）
  * 影響を受けた行数
* 出力パラメータと戻りパラメータ（該当するストアドプロシージャ実行時）
* リクエスト処理の前、実行中、または実行後に発生したエラー

API が返すレスポンスオブジェクトには、以下に示す 1つ以上のトップレベルプロパティが含まれます。

```json expandable theme={null}
{
  "results": [
    {
      "schema": [
        {
          "ordinal": <int>,
          "catalogName": "<string>",
          "schemaName": "<string>",
          "tableName": "<string>",
          "columnName": "<string>",
          "columnLabel": "<string>",
          "dataType": <int>,
          "dataTypeName": "<string>",
          "length": <int>,
          "precision": <int>,
          "scale": <int>,
          "nullable": <bool>
        },
        ...
      ],
      "rows": [
        [<any>, <any>, ...],
        ...
      ],
      "affectedRows": <int>,
    },
    ...
  ],
  "parameters": {
    "@p1": { "dataType": <int>, "direction": <int>, "value": <any> }
    ...
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}
```

### プロパティ

| プロパティ          | 説明                                                          |
| :------------- | :---------------------------------------------------------- |
| *results*      | クエリの結果セットの配列。結果セットごとに 1つのオブジェクト。                            |
| *schema*       | 結果セットのカラムスキーマの配列。                                           |
| *ordinal*      | 結果セット内のカラムの位置。0 から始まります。                                    |
| *catalogName*  | カラムのカタログ名。                                                  |
| *schemaName*   | カラムのスキーマ名。                                                  |
| *tableName*    | カラムのテーブル名。                                                  |
| *columnName*   | カラムの名前。                                                     |
| *columnLabel*  | カラムのラベル。                                                    |
| *dataType*     | カラムの [データ型](#data-types)。                                   |
| *dataTypeName* | カラムのデータ型名。データソース固有の場合があります。                                 |
| *length*       | バイナリ/文字列カラムの場合は最大文字数。その他のデータ型の場合は表示長。                       |
| *precision*    | カラムの精度。該当しない場合は省略。                                          |
| *scale*        | カラムのスケール。該当しない場合は省略。                                        |
| *nullable*     | カラムが null 許容かどうか。                                           |
| *rows*         | 行の値配列の配列。各ネストされた配列は結果セット内の 1行を表し、各カラムの行の値が含まれます。            |
| *affectedRows* | 影響を受けた行数。該当しない/利用できない場合は `-1`。                              |
| *parameters*   | ストアドプロシージャによって生成された出力、入出力、または戻りパラメータ。結果にそのようなパラメータがない場合は省略。 |
| *dataType*     | パラメータの [データ型](#data-types)。                                 |
| *direction*    | パラメータの方向：入出力は `2`、出力は `4`、戻り値は `5`。                         |
| *value*        | パラメータの値。                                                    |
| *error*        | 発生したエラーに関する情報。エラーが発生しなかった場合は省略。                             |
| *code*         | エラーコード。                                                     |
| *message*      | エラーメッセージ。                                                   |

## エラー

Connect AI が API リクエストを受信すると、検証し、実行し、結果が届き次第シリアライズしてストリーミングで返します。実行前または実行中にエラーが発生した場合、レスポンスオブジェクトにはエラー情報のみが含まれます。ただし、クエリの結果の返却が開始された *後* にエラーが発生することもあります。その場合、レスポンスオブジェクトには部分的な結果とともに、結果が不完全であることを示すエラー情報が含まれることがあります。

HTTP ステータスコードはボディの前に返されるため、不完全なレスポンスの HTTP ステータスは `200 OK` になります。そのため、HTTP ステータスコードのみに頼らず、レスポンスにエラー情報が含まれているかどうかを常に確認することが重要です。

## データ型

次の表は、結果セットのシリアライズにおける dataType プロパティの有効な値を示しています。

| 値  | 意味            | 表現                                                            |
| :- | :------------ | :------------------------------------------------------------ |
| 1  | BINARY        | JSON String; Base64-encoded                                   |
| 2  | VARBINARY     | JSON String; Base64-encoded                                   |
| 3  | LONGVARBINARY | JSON String; Base64-encoded                                   |
| 4  | BLOB          | JSON String; Base64-encoded                                   |
| 5  | VARCHAR       | JSON String                                                   |
| 6  | TINYINT       | JSON Number                                                   |
| 7  | SMALLINT      | JSON Number                                                   |
| 8  | INTEGER       | JSON Number                                                   |
| 9  | BIGINT        | JSON Number                                                   |
| 10 | FLOAT         | JSON Number                                                   |
| 11 | DOUBLE        | JSON Number                                                   |
| 12 | DECIMAL       | JSON String; format: valid JSON number                        |
| 13 | NUMERIC       | JSON String; format: valid JSON number                        |
| 14 | BOOLEAN       | JSON Boolean (true/false)                                     |
| 15 | DATE          | JSON String; format: `yyyy-MM-dd`                             |
| 16 | TIME          | JSON String; format: `HH:mm:ss.fffffff`                       |
| 17 | TIMESTAMP     | JSON String; ISO8601 format: `yyyy-MM-ddTHH:mm:ss.fffffffZ`   |
| 18 | UUID          | JSON String; format: `{01234567-890a-bcde-f012-34567890abcd}` |