Private Cloud Connector を使って CData Connect AI を QuickBooks Desktop に接続する方法

QuickBooks Desktop には財務データが格納されていますが、多くのAIツールはこのデータに直接アクセスできません。QuickBooks Desktop はネットワーク内の Windows マシン上で動作しており、クラウドのAIサービスからは直接到達する経路がないためです。CData Connect AI は、軽量な Docker コンテナである Private Cloud Connector を使ってこの課題を解決します。インターネットからのインバウンドポートを開放することなく、ネットワークから Connect AI へのセキュアなアウトバウンド専用トンネルを確立できます。

この記事では、Windows マシンへの QuickBooks Desktop Gateway のインストールから、AIツールで QuickBooks のリアルタイムデータに対して自然言語で質問するところまで、セットアップの全手順を解説します。

接続の仕組み

接続は、4つのコンポーネントが連携して成り立っています。QuickBooks Desktop は、会社ファイルを開いた状態で Windows マシンまたはサーバー上で動作します。CData QuickBooks Desktop Gateway は同じマシンにインストールする無料の Windows アプリケーションで、他のソフトウェアが QuickBooks とセキュアに通信できるようにします(デフォルトのポートは 8166)。Private Cloud Connector は、ネットワーク内の Linux マシン上で Docker コンテナとして動作し、Connect AI へのセキュアなアウトバウンド専用トンネルを確立します。Connect AI はAIツールが接続するクラウドサービスで、クエリをトンネル経由で QuickBooks Gateway から QuickBooks へ送り、結果を返します。

接続経路の全体像は次のとおりです。

AI tool > Connect AI (cloud) > Private Cloud Connector (Docker, inside your network) > QuickBooks Gateway > QuickBooks Desktop

前提条件

始める前に、次のものを用意してください。

1. CData Connect AI のアカウント(無料トライアルでも可)。
2. QuickBooks Desktop が動作する Windows マシン(管理者権限でアクセスでき、会社ファイルが利用できること)。
3. QuickBooks マシンと同じネットワーク上にある、Docker を実行できる Linux マシン。スペックは控えめで十分です(CPU 2コア、RAM 2〜4 GB、ディスク 20 GB)。ゲートウェイ自体のメモリ使用量は通常 300 MB 未満です。
4. Linux マシンから次のホスト名へのポート 443 でのアウトバウンド HTTPS アクセス: *.cdata.com、*.azurecr.io、*.servicebus.windows.net。インターネットからのインバウンドアクセスは不要です。
5. Linux マシンから QuickBooks マシンの Gateway ポート(デフォルトは 8166)へのネットワーク経路。通常は Windows ファイアウォールのルールを1つ追加すれば確保できます。

注: Docker Desktop は Windows や Mac の開発マシン向けのGUIツールで、Windows Server ではサポートされていません。Docker Engine は Linux 上でネイティブに動作する標準的なサーバー向けバージョンで、このガイドではこちらを使用します。QuickBooks マシンが Windows Server の場合は、QuickBooks サーバー自体ではなく、別の Linux マシンで Private Cloud Connector を実行してください。

注: ネットワークで SSL/TLS 通信を検査している場合は、ネットワーク管理チームに依頼して、上記3つのホスト名を検査の対象外(バイパス)に設定してもらってください。バイパスを設定しないと、ゲートウェイの接続と切断が繰り返し発生します。

パート1: QuickBooks Desktop Gateway をセットアップする

ここでは、QuickBooks Desktop が動作する Windows マシンでの作業を説明します。

ステップ1: 無料の CData QuickBooks Desktop Gateway をダウンロードしてインストールします。一般的な Windows プログラムと同じ手順でインストールでき、システムトレイにアイコンが表示されます。

ステップ2: QuickBooks Desktop を起動し、管理者としてログインして、対象の会社ファイルを開きます。

ステップ3: システムトレイから QuickBooks Gateway を開きます。Users タブに移動して Add をクリックし、ユーザー名とパスワードを作成します。これらは後で Connect AI が使用する認証情報なので、控えておいてください。読み取り専用の接続にしたい場合は、このユーザーの Data Access を Read Only に設定します。

ステップ4: ポートを確認します。Gateway はデフォルトでポート 8166 をリッスンします。マシン上の別のアプリケーションがこのポートを使用している場合は、Gateway の Advanced タブを開き、8167 など空いている任意のポートに変更してから Gateway を再起動します。後で必要になるため、使用するポート番号を控えておいてください。

ステップ5: QuickBooks マシンに、そのポートを許可する Windows ファイアウォールのルールを作成します。セキュリティをさらに高めるため、IT 部門に依頼して、Linux マシンの IP アドレスのみを許可するようにルールの範囲を絞ることもできます。

ステップ6: 最初の接続が行われると、QuickBooks にアプリケーションを許可するかどうかを確認する認証ダイアログが表示されます。許可してください。その後、無人でも動作し続けるようにするには、Edit > Preferences > Integrated Applications > Company Preferences の順に移動し、Gateway のエントリを選択して Properties をクリックし、Allow this application to login automatically にチェックを入れます。

パート2: Linux マシンに Docker Engine をインストールする

以下のコマンドは Ubuntu 向けです。ターミナルで1つずつ入力してください。

ステップ1: 利用可能なソフトウェアの一覧を更新します。

sudo apt-get update

ステップ2: 補助ツールを2つインストールします。

sudo apt-get install -y ca-certificates curl

ステップ3: 信頼するソフトウェアのキーを保存するフォルダーを作成します。

sudo install -m 0755 -d /etc/apt/keyrings

ステップ4: Docker の公式署名キーをダウンロードします。

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc

ステップ5: Docker の公式ダウンロードソースを登録します。

echo "deb [signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list

ステップ6: ソフトウェア一覧を更新し、Docker Engine をインストールします。

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

ステップ7: Docker が動作することを確認します。

sudo docker run hello-world

「Hello from Docker!」と表示されれば、インストールは成功です。サービスが起動していない場合は、先に sudo systemctl start docker で起動してから、もう一度コマンドを実行してください。

ステップ8: このマシンから Connect AI に到達できることを確認します。

curl -v https://cloud.cdata.com/api

証明書の検証に成功し、何らかの HTTP レスポンスが返れば、ネットワーク経路と暗号化が機能していることを確認できます。ここで HTTP 404 が返っても問題ありません。エンドポイントには到達できており、その特定のパスが存在しないだけです。

ステップ9: IP フォワーディングが有効になっていることを確認します。

sudo sysctl net.ipv4.ip_forward

net.ipv4.ip_forward = 1 と返ってくるはずです。0 が返った場合は、次の2つのコマンドで設定を永続化します。

echo 'net.ipv4.ip_forward = 1' | sudo tee /etc/sysctl.d/99-ip-forward.conf
sudo sysctl --system

パート3: Connect AI にゲートウェイを登録する

ここでは、ブラウザーで Connect AI を操作します。

ステップ1: Connect AI にログインし、左メニューの Sources を開いて + Add Connection をクリックし、QuickBooks を検索して選択します。すでに接続を作成済みの場合は、その接続を開いて編集します。

ステップ2: 接続の Connect Gateway タブを開き、+ Add Gateway をクリックします。

ステップ3: ゲートウェイの設置場所がわかる Location Name を入力します(例: 「Main Office」「QuickBooks Server」)。入力したら Confirm をクリックします。

ステップ4: 新しいロケーションが Pending ステータスで一覧に表示され、コピーが必要な3つの値(Account Id、Location Id、Key)も表示されます。コピーアイコンで各値を控え、目のアイコンをクリックすると Key が表示されます。Key はパスワードと同様に厳重に取り扱ってください。

パート4: Private Cloud Connector コンテナを起動する

Linux マシンに戻り、次のコマンドを実行します。3つのプレースホルダーは、パート3でコピーした値に置き換えてください。5行すべてを1つのコマンドとしてまとめてコピーします。

sudo docker run -d --restart unless-stopped --name onprem-gateway \
 -e GATEWAY_LOCATION_ID=<your location id> \
 -e GATEWAY_API_KEY=<your key> \
 -e ACCOUNT_ID=<your account id> \
 connectaipublic.azurecr.io/connectgateway:latest

--restart unless-stopped フラグを指定すると、マシンの再起動後にゲートウェイが自動的に起動します。そのため、夜間のパッチ適用に伴う再起動でも、ゲートウェイが停止したままになることはありません。

ゲートウェイの起動状況をログで確認します。

sudo docker logs -f onprem-gateway

Ctrl+C を押すとログの表示を終了できます。ゲートウェイはバックグラウンドで動作し続けます。約10秒以内に次の3行が表示されれば、セキュアなトンネルが有効になっています。

Tunneling configuration retrieved successfully ...
Azure Relay listener connected successfully ...
Starting connection accept loop...

ブラウザーに戻ると、ゲートウェイのステータスが Pending から緑色の Success に変わっています。

Test Gateways をクリックして、往復の通信テストに成功することを確認します。

パート5: QuickBooks 接続を完成させてテストする

ステップ1: 接続の Basic Settings タブで、Connection Type を Connect Gateway に設定します。

ステップ2: ドロップダウンから Location Name を選択します。

ステップ3: 認証情報を入力します。User と Password は、パート1で作成した QuickBooks Gateway の認証情報です。URL は Linux マシンから QuickBooks Gateway に到達できるアドレスで、http://マシン:ポート の形式で指定します。次に例を示します。

localhost ではなく、QuickBooks マシンのマシン名または IP アドレスを使用してください。Docker コンテナ内から見た localhost は、QuickBooks マシンではなくコンテナ自身を指します。

ステップ4: Save and Test をクリックします。成功すると緑色のバナーで接続が確認され、ステータスが Authenticated に変わり、Data Model パネルに Accounts、Invoices、Bills など QuickBooks のテーブルが表示されます。

ステップ5: 読み取り専用の接続にする場合は、Permissions タブを開き、SELECT のみが許可されていることを確認します。INSERT、UPDATE、DELETE の権限を削除しておけば、この接続を通じて帳簿が変更されることはありません。

ステップ6: AIツールを接続します。Connect AI のアカウントには MCP エンドポイントが用意されており、ChatGPT、Claude、Microsoft Copilot Studio をはじめ、MCP に対応したあらゆるツールで利用できます。Connect AI のドキュメントにある各ツール向けのガイドに従って追加し、QuickBooks のデータについて自然言語で質問してみましょう。

よくある問題のトラブルシューティング

テストが失敗し、コンテナのログに「Connection timed out」と表示される

トンネルは機能していますが、コンテナが QuickBooks Desktop Gateway に到達できていません。次の3つのポートが一致している必要があります。QuickBooks Desktop Gateway がリッスンしているポート、接続 URL に指定したポート、Windows ファイアウォールで許可しているポートです。ネットワーク上の任意の Windows マシンから、PowerShell でポートをテストします。

Test-NetConnection <QuickBooks machine IP> -Port 8166

TcpTestSucceeded: True は、ポートが開いていて到達可能であることを意味します。False の場合は、そのポートでリッスンしているものがないか、ファイアウォールによってブロックされています。

エラー: 「fffffffc - Action impossible while not connected」

ゲートウェイが現在接続されていないため、Connect AI がゲートウェイに到達できませんでした。sudo docker ps でコンテナが実行中であることを確認し、sudo docker logs onprem-gateway でログにエラーがないか確認してください。必要に応じて再起動し、「Starting connection accept loop」の行が表示されるのを待ってから、もう一度テストします。

コンテナのログに「SslHandshakeTimeoutException: handshake timed out」と表示される

ネットワーク上の何か(多くの場合、SSL 検査アプライアンス、プロキシ、VPN クライアント)が、ゲートウェイの暗号化通信に介入しています。*.cdata.com、*.azurecr.io、*.servicebus.windows.net を TLS 検査のバイパス対象に設定することで解消できます。

再起動やパッチ適用後にゲートウェイが切断される

セキュリティ強化のベースラインによって IP フォワーディングが 0 にリセットされることがよくあり、その場合、気付かないうちにコンテナの接続が失われます。パート2のステップ9にある永続化の設定を適用し、セキュリティ強化の担当チームに依頼して、このマシンについて net.ipv4.ip_forward = 1 を例外として文書化してもらってください。

接続テストに成功した後に QuickBooks 固有のエラーが発生する

QuickBooks マシン上で QuickBooks Desktop が起動していて正しい会社ファイルが開かれていること、QuickBooks 内で Gateway が許可されていること、そして QuickBooks を実行している専用の Windows セッションが1つだけであることを確認してください。同じマシンに複数のユーザーがログインしてそれぞれ QuickBooks を実行すると、連携レイヤーが混乱することがあるため、常時稼働の専用セッションを使用するのが最適です。

AIツールを QuickBooks のリアルタイムデータに接続する

セットアップが完了すると、AIツールはインターネットに直接公開されることなく、セキュアで統制の取れた接続を通じて QuickBooks のデータにクエリを実行できます。経理・財務チームは自然言語で質問し、リアルタイムデータに基づく回答を得ながら、帳簿の整合性を守る読み取り専用の制御も維持できます。

これを可能にする接続レイヤーを提供するのが CData Connect AI です。無料トライアルを開始して、今すぐAIツールを QuickBooks Desktop に接続しましょう。