> ## 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.

# Python

> このページでは、Connect AI で Python コネクタ **cdata-connect-ai** を使用する手順を説明します。PEP 249 準拠のコネクタにより、Connect AI REST API を通じた標準 SQL によるリアルタイムデータのクエリと書き込みが可能です。

詳細については、[cdata-connect-ai PyPI ページ](https://pypi.org/project/cdata-connect-ai/)を参照してください。

## 前提条件

Python を Connect AI と連携させる前に、以下が必要です。

* Python >=3.10
* `requests` >= 2.28.0
* `ijson` >= 3.1.0
* Connect AI アカウントのデータソース。詳細については、[ソース](/ja/Sources) を参照してください。
* パーソナルアクセストークン（PAT）。[Settings](/ja/Settings#personal-access-tokens) ページで PAT を生成してください。認証時のパスワードとして使用するため、コピーしておいてください。

## コネクタのインストール

```bash wrap theme={null}
pip install cdata-connect-ai
```

pandas 統合の場合：pandas サポートを有効にするために `full` エクストラ付きでコネクタをインストールします。

```bash wrap theme={null}
pip install "cdata-connect-ai[full]"
```

## Connect AI への接続

以下は、Connect AI API に接続して Salesforce 接続の Account テーブルにクエリを実行する Python コードの例です。Connect AI のユーザー名とパスワード（パスワードは前提条件で作成した PAT）を入力してください。

```python wrap theme={null}
import cdata_connect_ai

conn = cdata_connect_ai.connect(
    username="you@example.com",
    password="<your_personal_access_token>",
)

with conn.cursor() as cur:
    cur.execute("SELECT * FROM [Salesforce1].[Salesforce].[Account]")
    rows = cur.fetchall()

for row in rows:
    print(row)

conn.close()
```

### 設定ファイル

[PyHOCON](https://github.com/chimpler/pyhocon) 設定ファイルを使用して、コードから認証情報を除外できます。

```hocon theme={null}
# config.conf
cdata_api_db {
  username = "you@example.com"
  password = "<your_personal_access_token>"
}
```

コードは設定ファイルを参照するため、認証情報が含まれません。

```python theme={null}
import cdata_connect_ai

conn = cdata_connect_ai.connect(config_path="config.conf")
```

### ワークスペースへの接続

Connect AI ワークスペースに接続するには、次のように `workspace` パラメータを追加します。

```python wrap theme={null}
conn = cdata_connect_ai.connect(
    username="you@example.com",
    password="<your_personal_access_token>",
    workspace="production",
)
```

## 例

### パラメータ化されたクエリ

```python wrap theme={null}
with conn.cursor() as cur:
    cur.execute(
        "SELECT * FROM [DB].[public].[users] WHERE city = %(city)s LIMIT %(limit)s",
        {"city": "New York", "limit": 10},
    )
    rows = cur.fetchall()
```

### バッチ操作

```python wrap theme={null}
with conn.cursor() as cur:
    cur.executemany(
        "INSERT INTO [DB].[public].[cities] (city, id) VALUES (@city, @id)",
        [
            {"@city": {"dataType": 5, "value": "New York"}, "@id": {"dataType": 8, "value": 1}},
            {"@city": {"dataType": 5, "value": "London"},   "@id": {"dataType": 8, "value": 2}},
        ],
    )
```

<Note>
  `dataType` の値と説明については、[データ型](/ja/API/REST-API#data-types)を参照してください。
</Note>

### ストアドプロシージャ

```python wrap theme={null}
with conn.cursor() as cur:
    cur.callproc("[DB].[public].[my_procedure]", ("arg1", "arg2"))
    rows = cur.fetchall()
```

### Pandas 統合

```python wrap theme={null}
import cdata_connect_ai
import pandas as pd

conn = cdata_connect_ai.connect(
    username="you@example.com",
    password="<your_personal_access_token>",
)

with conn.cursor() as cur:
    cur.execute("SELECT Id, Name, Industry, AnnualRevenue FROM [Salesforce1].[Salesforce].[Account]")
    columns = [desc[0] for desc in cur.description]
    rows = cur.fetchall()

df = pd.DataFrame(rows, columns=columns)
print(df.head())
print(df.describe())

conn.close()
```

## 接続オプション

以下の表は、コネクタで使用可能な接続オプションです。

| パラメータ         | 説明                   | デフォルト |
| ------------- | -------------------- | ----- |
| `username`    | 認証ユーザー名              | -     |
| `password`    | パーソナルアクセストークン        | -     |
| `config_path` | PyHOCON 設定ファイルへのパス   | -     |
| `workspace`   | Connect AI ワークスペース名  | -     |
| `timeout`     | HTTP リクエストのタイムアウト（秒） | `90`  |
| `max_retries` | 一時的な 5xx エラー時の再試行回数  | `3`   |
| `retry_delay` | 再試行間のベース遅延（秒）        | `1.0` |