「外部接続」管理画面では、エージェントが外部APIを呼び出す際の接続先を登録・管理できます。接続先のベースURLや認証方式をあらかじめ登録しておくことで、エージェントから外部サービスのAPIを安全に呼び出せるようになります。
この記事は、外部接続を初めて設定する方に向けて、画面の見方から接続の登録・有効化までを順を追って説明します。読み終えると、外部APIの接続先を登録し、エージェントから利用できる状態にできます。
１．はじめに知っておきたい仕様
外部接続を登録する前に、認証情報の取り扱いに関する以下の仕様をご確認ください。
- 入力した認証情報は、生成されるコードには含まれません。 そのため、接続情報が意図せずコード側に露出することはありません。
- 保存後は認証情報を参照できません。 保存すると、入力した認証情報は画面上で「*****」と表示され、値そのものを再確認することはできません。認証情報を変更する場合は、再入力が必要です。
- 外部接続を有効にすると、エージェントから利用できるようになります。無効にしている間は、接続が登録されていても、エージェントからは呼び出せません（一覧の「状態」は「無効」と表示されます）。
※：本機能は、エージェント複製と仕様書のエクスポート／インポートには対応していません。
２．外部接続の追加
（１） 外部接続を追加できる画面
外部接続情報は、エージェントの作成状況に応じて、以下のいずれの画面からも追加できます。
- 外部接続の一覧画面：左下の「＋ 外部接続を追加」をクリックします。
- エージェント仕様書の作成後（エージェント生成前）の画面：エージェントを生成する前でも、外部接続情報を追加できます。
エージェント作成後のエージェント画面「外部接続」タブ：エージェントを作成した後でも、「外部接続」タブから追加できます。
（２） 認証方式の追加画面
外部接続の一覧画面の左下にある「＋ 外部接続を追加」をクリックすると、外部接続の追加画面が開きます。
（３） 設定項目の説明
接続の追加・編集画面では、以下の項目を設定します。
| 項目 | 説明・表示例 | 初期値 | ||||||
|---|---|---|---|---|---|---|---|---|
| 接続ID | コード生成時に利用する識別子です。 （英小文字・数字・ハイフン・アンダースコア） 例：slack、zendesk、teams | - | ||||||
| 表示名 | 管理画面上で表示される名前です。 例：Slack API | - | ||||||
| ベースURL | 外部APIの接続先URLです。 例：https://slack.com/api | - | ||||||
| 認証方式 | 以下の認証方式を選択できます。詳細は「２．（４）認証方式の種類」を参照してください
| 認証なし | ||||||
| 認証情報の値 | 接続先APIへ送信するキーまたはトークンそのものを入力します。「Bearerトークン」「ヘッダー」「クエリパラメータ」の各方式で使用します。保存後は参照できないため、入力内容に誤りがないかご確認ください。 例 : a1b2c3d4e5f6g7h8i9j0 | - | ||||||
| 認証ヘッダー名 | 「ヘッダー」認証を選択した場合に表示されます。認証情報の値を載せるHTTPヘッダーの名前を指定します。接続先APIの仕様に合わせて入力してください。 例 : X-API-Key | - | ||||||
| 認証クエリパラメータ名 | 「クエリパラメータ」認証を選択した場合に表示されます。認証情報の値を載せるURLパラメータの名前を指定します。指定した名前は、リクエスト時にベースURLの末尾へ自動的に付与されます。 例 : apikey | - | ||||||
| トークンエンドポイントURL | アクセストークンを取得するためのURLです。接続先APIの認可サーバーが提供するトークン発行用エンドポイントを指定します。ベースURLではなく、トークン取得専用のURLを入力してください。 例 : https://login.microsoftonline.com/(テナントID)/oauth2/v2.0/token | - | ||||||
| クライアントID | 接続先APIに登録したアプリケーションの識別子です。認可サーバー側でアプリを登録した際に発行されます。 例 : 00001111-aaaa-2222-bbbb-3333cccc4444 | - | ||||||
| クライアントシークレット | クライアントIDとペアで使用する秘密鍵です。認可サーバー側で発行されます。保存後は参照できないため、入力内容に誤りがないかご確認ください。 例 : A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u | - | ||||||
| スコープ（任意） | 取得するアクセストークンで許可する操作の範囲を指定します。複数指定する場合はスペースで区切ります。指定は任意で、空欄の場合は接続先APIの既定の範囲が適用されます。 例 : https://graph.microsoft.com/.default | - | ||||||
| タイムアウト(秒) | 指定した秒数以内に応答がない場合、タイムアウトになります。 1～120秒で指定できます。 例 : 60 | 30秒 | ||||||
| リトライ回数 | 失敗した場合に再実行する最大回数です。 0～5回で指定できます。 例 : 5 | 2回 | ||||||
| レート制限 | 一定時間あたりの呼び出し回数の上限です。空欄の場合は無制限です。 例 : 60 | 空欄（無制限） | ||||||
| 有効にする | 「有効にする」をオンにして「保存」をクリックすると、登録直後からエージェントで利用できるようになります。後で有効化する場合は、オフのまま保存し、あとから編集画面で切り替えることもできます。 | - |
補足：
- 認証情報の値 は機密情報です。第三者に共有せず、安全に管理してください。保存後は「*****」と表示され、値の再確認はできません。
- 認証ヘッダー名 や 認証クエリパラメータ名 に指定すべき値は、接続先APIのドキュメントをご確認ください。
「Bearerトークン」を選択した場合は、
Authorization: Bearer (認証情報の値)の形式で自動的に送信されるため、ヘッダー名やパラメータ名の入力は不要です。
（４） 認証方式の種類
「認証方式」では、接続先APIに合わせて以下から選択できます。
| 認証方式 | 説明 | 主な利用シーン |
|---|---|---|
| 認証なし | 認証ヘッダーを付与しません | 認証不要なエンドポイント、テスト用API |
| Bearerトークン | Authorization: Bearer ヘッダーでトークンを送信します | 多くのクラウドAPI（Slack、Zendesk など） |
| ヘッダー | 独自のヘッダー名でキーを送信します（例：X-API-Key） | 独自開発API、社内API |
| クエリパラメータ | URLの末尾にキーを付与します（例：?apikey=xxxxx） | 一部のSaaS API |
| Basic認証 | ユーザー名とパスワードを用いたHTTP Basic認証です | レガシーAPI、一部の管理API |
| OAuth 2.0 Client Credentials | クライアントIDとクライアントシークレットでアクセストークンを取得します | サーバー間連携（Microsoft Graph など） |
３．外部接続の一覧
登録済みの接続が一覧で表示されます。各接続について、以下の情報を確認できます。
（１） 表示項目
一覧では、下記の内容を確認できます。
| 項目 | 説明 | 表示例 |
|---|---|---|
| 接続ID | コード生成時に利用する識別子 | slack |
| 表示名 | 管理画面上で表示される名前 | slack |
| 状態 | 有効／無効（利用可否） | 有効 無効 |
| ベースURL | 外部APIの接続先 | https://slack.com/api |
| 疎通結果 | 疎通テストを実施すると、疎通結果を表示できます。
| 【疎通成功】 【疎通失敗】 |
画面右側の「設定」からは接続内容の編集、「疎通テスト」からは接続先への通信確認ができます。新しい接続を登録する場合は、左下の「＋ 外部接続を追加」をクリックします。
４．疎通テスト
外部接続を登録した後に、一覧右側の「疎通テスト」ボタンをクリックすると、接続先へ正しく通信できるかを確認できます。
（１）疎通テストの結果の見方
「疎通テスト」を実行すると、接続先に実際に通信できるかを確認できます。結果には、HTTPステータスコードと応答時間が表示されます。
表示例：疎通OK（HTTP 302 / 184ms）
この例は、接続先へ通信でき（疎通成功）、応答時間が184ミリ秒、サーバーからリダイレクト（HTTP 302）が返ってきたことを示します。
（２）よくあるエラー
疎通テスト時に表示される代表的なエラーメッセージと、その原因・対処方法は以下のとおりです。エラーメッセージをもとに、該当する項目をご確認ください。
| エラーメッセージ | 原因 | 対処方法 |
|---|---|---|
| ホスト名を解決できませんでした。 | ベースURLのホスト名が正しくありません。 | ベースURLに入力したホスト名（ドメイン部分）に、誤字や不要な文字が含まれていないかを確認し、正しいURLに修正してください。 |
| トークンエンドポイントのURLの形式が不正です。 | 認証方式「OAuth 2.0 Client Credentials」を選択した際に、トークンエンドポイントのURLの形式が正しくありません。 | トークンエンドポイントのURLが「https://」から始まる正しい形式で入力されているかを確認し、修正してください。 |
| アクセストークンの取得が拒否されました。設定値を確認してください。 | 認証情報（クライアントIDやクライアントシークレット等）が正しくないため、アクセストークンを取得できませんでした。 | クライアントID・クライアントシークレットなどの認証情報に誤りがないかを確認し、正しい値を入力してください。 |
上記の対処方法を試しても接続に失敗する場合は、以下の点もあわせてご確認ください。
- 入力値の前後に不要なスペースが含まれていないか
- コピー＆ペースト時に文字が欠落・重複していないか
- 接続先の外部システム側で、アクセス制限（IP制限など）が設定されていないか
５．接続を編集・削除する
登録済みの接続を変更する場合は、一覧右側の「設定」ボタンをクリックすると、編集画面を開きます。
編集画面では、各項目の変更に加えて、下部の「削除」ボタンをクリックすると接続を削除でき、「キャンセル」ボタンをクリックすると変更を取り消し、「保存」をクリックすると変更を保存できます。
ご注意：
認証情報は保存後に参照できません。認証情報を変更する場合は、あらためて入力し直してください。
６．関連情報
なお、本記事の「外部接続」は、エージェントが外部APIを呼び出す際の認証設定です。
反対に、外部システムから Leapnet エージェントを呼び出す際の認証方式（x-api-key ヘッダーの利用など）については、「APIの利用方法」をご確認ください。
Leapnet APIでは、「x-api-key」というHTTPヘッダーにAPIキーを設定して認証を行います。