1.はじめに知っておきたい仕様
- 入力した認証情報は、生成されるコードには含まれません。 そのため、接続情報が意図せずコード側に露出することはありません。
- 保存後は認証情報を参照できません。 保存すると、入力した認証情報は画面上で「*****」と表示され、値そのものを再確認することはできません。認証情報を変更する場合は、再入力が必要です。
- 外部接続を有効にすると、エージェントから利用できるようになります。無効にしている間は、接続が登録されていても、エージェントからは呼び出せません(一覧の「状態」は「無効」と表示されます)。
2.外部接続の追加
- 外部接続の一覧画面:左下の「+ 外部接続を追加」をクリックします。
- エージェント仕様書の作成後(エージェント生成前)の画面:エージェントを生成する前でも、外部接続情報を追加できます。
- エージェント作成後のエージェント情報画面「外部接続」タブ:エージェントを作成した後でも、「外部接続」タブから追加できます。
(1) 外部接続を追加する
入力項目 | 概要 | 備考 |
| 接続ID(必須) | コード生成時に利用する識別子です。タスク内容では、この接続IDを使って外部APIを呼び出すよう指示します。 | 英小文字・数字・ハイフン・アンダースコア |
| 表示名(必須) | 管理画面上で表示される、識別しやすい名前です。 | 例:Slack API |
| ベースURL(任意) | 外部APIの接続先URLです。 | 例:https://slack.com/api |
※:エージェントを作成した後に、認証方式の登録は「3.外部接続の認証登録」をご覧ください。
(2) API定義の取込(任意)
外部接続ごとに、OpenAPI 3.0/3.1形式(JSONまたはYAML)のAPI定義を取り込めます。
- 仕様書の処理手順ごとに利用する外部APIの操作を選び、外部APIへ送る項目・受け取る項目と、エージェントの入力・先行手順の出力・固定値などとの対応を画面で設定できます。
- 設定内容はエージェント作成・更新時のコード生成に反映され、仕様書のエクスポート/インポートやエージェントの複製でも引き継がれます。
「API定義を取り込む」 ボタンをクリックすると、OpenAPI 3.0/3.1形式(JSONまたはYAML)のAPI定義ファイルを取り込めます。
「ファイルを選択」ボタンをクリックすると、API定義ファイルを選択できます。
取り込み内容を確認できます。また、定義内容の編集ができます。
エージェントで利用した操作を選択して、「取り込む」ボタンでAPI定義を取り込みます。
取り込み後に、操作の件数を確認できます。また、API定義の再取り込みや定義の削除ができます。
「更新」ボタンをクリックすると、外部接続が登録されます。
(3) API定義の入出力を対応付ける(マッピングする)
OpenAPI形式のAPI定義を取り込むと、エージェントの入力や処理結果と、外部接続APIのリクエスト・レスポンス項目を対応付けることができます。
・ 処理手順に外部接続APIを設定する
外部接続APIを利用する処理手順で「+外部APIを設定」をクリックします。
利用する外部接続とAPIの操作を選択すると、外部APIへ送信する項目と、外部APIから受け取る項目を設定できます。
外部APIを利用する処理手順には、利用する接続と操作が「外部API: 接続ID / 操作」の形で表示されます。
「外部APIを編集」から設定内容の変更ができます。
・ リクエスト項目を設定する
外部APIへ送信する各項目について、値の取得元を設定します。
以下から選択できます。
- 未設定(仕様書の指示に従う):仕様書の指示に従って値が作られます。
エージェントの入力:エージェントに入力された値を利用します。
- 先行手順の出力:前の処理手順で得られた値を使用します。
固定値:指定した固定値を使用します。
・ レスポンス項目を設定する
外部APIから受け取る項目について、取得した値をどこで利用するか設定します。
- 未設定(仕様書の指示に従う):仕様書の指示に従って値が作られます。
- 後続の手順で利用する:後続の処理手順で利用します。後続手順で使用する項目名を指定します。
エージェントの出力:外部APIから取得した値をエージェントの出力として使用します。
保存した入出力の設定内容は、エージェントの作成・更新時のコード生成に反映されます。また、仕様書のエクスポート/インポートやエージェントの複製でも引き継がれます。
3.外部接続の認証登録
(1) 認証方式の追加画面
(2) 設定項目の説明
| 項目 | 説明・表示例 | 初期値 | ||||||
|---|---|---|---|---|---|---|---|---|
| 接続ID | コード生成時に利用する識別子です。 (英小文字・数字・ハイフン・アンダースコア) 例:slack、zendesk、teams | - | ||||||
| 表示名 | 管理画面上で表示される名前です。 例:Slack API | - | ||||||
| ベースURL | 外部APIの接続先URLです。 例:https://slack.com/api | - | ||||||
| 認証方式 | 以下の認証方式を選択できます。詳細は「3.(3)認証方式の種類」を参照してください
| 認証なし | ||||||
| 認証情報の値 | 接続先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 (認証情報の値)の形式で自動的に送信されるため、ヘッダー名やパラメータ名の入力は不要です。
(3) 認証方式の種類
| 認証方式 | 説明 | 主な利用シーン |
|---|---|---|
| 認証なし | 認証ヘッダーを付与しません | 認証不要なエンドポイント、テスト用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 など) |
4.外部接続の一覧
(1) 表示項目
| 項目 | 説明 | 表示例 |
|---|---|---|
| 接続ID | コード生成時に利用する識別子 | slack |
| 表示名 | 管理画面上で表示される名前 | slack |
| 状態 | 有効/無効(利用可否) | 有効 無効 |
| ベースURL | 外部APIの接続先 | https://slack.com/api |
| 疎通結果 | 疎通テストを実施すると、疎通結果を表示できます。
| 【疎通成功】 【疎通失敗】 |
5.疎通テスト
外部接続を登録した後に、一覧右側の「疎通テスト」ボタンをクリックすると、接続先へ正しく通信できるかを確認できます。
(1)疎通テストの結果の見方
(2)よくあるエラー
| エラーメッセージ | 原因 | 対処方法 |
|---|---|---|
| ホスト名を解決できませんでした。 | ベースURLのホスト名が正しくありません。 | ベースURLに入力したホスト名(ドメイン部分)に、誤字や不要な文字が含まれていないかを確認し、正しいURLに修正してください。 |
| トークンエンドポイントのURLの形式が不正です。 | 認証方式「OAuth 2.0 Client Credentials」を選択した際に、トークンエンドポイントのURLの形式が正しくありません。 | トークンエンドポイントのURLが「https://」から始まる正しい形式で入力されているかを確認し、修正してください。 |
| アクセストークンの取得が拒否されました。設定値を確認してください。 | 認証情報(クライアントIDやクライアントシークレット等)が正しくないため、アクセストークンを取得できませんでした。 | クライアントID・クライアントシークレットなどの認証情報に誤りがないかを確認し、正しい値を入力してください。 |
- 入力値の前後に不要なスペースが含まれていないか
- コピー&ペースト時に文字が欠落・重複していないか
- 接続先の外部システム側で、アクセス制限(IP制限など)が設定されていないか
6.接続を編集・削除する
登録した外部接続はエージェント情報画面や外部接続画面で編集や削除できます。
(1)エージェント情報画面の外部接続
エージェント情報画面で、外部接続一覧の右側の「編集」ボタンや削除ボタンをクリックして、外部接続を編集・削除ができます。