Kore.ai APIの使用

Kore.aiボットプラットフォームは、安全なAPIを使用したボット開発へのアクセスを提供します。ボットの作成、ボットのインポートとエクスポート、トレーニング、公開など、開発者が行う主なアクティビティは、すべてこれらのAPIを使用して行うことができます。ボットビルダーへのアクセス権、管理者、ボットのロールの管理などの主要なアカウント管理アクティビティは、安全な公開APIを介して行うことができます。APIのリストおよび使用方法についてはこちらを参照してください。APIリクエストの認証には、以下の2つのステップが含まれます。

1. アプリの作成：アプリ作成の一環として、アプリのAPIスコープを選択する必要があります。これにより、選択したAPIのみへのアクセスをアプリに提供することができます。
   • ボットビルダーのAPIスコープ：ボット開発者は、ボットビルダーツールから、ボット固有のAPIスコープを定義することができます。
   • ボットの管理者コンソールのAPIスコープ：アカウント管理者は、管理者コンソールから、アカウントに組み込まれたボットにアクセスするためのAPIスコープを定義することができます。
2. アプリにAPIスコープを関連付ける：クライアントアプリケーションがボットプラットフォームAPIにアクセスするためには、クライアントアプリケーションとボットを関連付ける必要があります。

さらに、以下の方法でプラットフォームとの接続を確保することができます。

1. JTIクレームを実施 – 有効にすると、プラットフォームは、リクエストにJTIクレームが含まれる通話からのリクエストのみを受け付け、JTIクレームが含まれないものは拒否されます
2. JWE暗号化を実施 – JWTトークンの生成：ボットプラットフォームの公開APIにアクセスするには、APIリクエストを行うアプリケーションの認証が必要です。Kore.aiでは、JWT（JSONウェブトークン）の仕組みを使用して認証を行っています。JWTトークンの概要については、「JWTトークンの紹介」をご覧ください。上記のクライアントアプリのクライアントIDtoクライアントシークレットを使用してJWTトークンを生成します。このトークンは、認証のために各APIリクエストの一部として渡される必要があります。

アプリの作成と管理

ボットビルダー

以下の手順では、ボットビルダーからクライアントアプリを作成します。

1. トップメニューから [デプロイ] タブを選択します。
2. 左メニューの [システム連携] > [アプリを管理] をクリックします。
3. [新しいアプリ] をクリックします。
4. [クライアントアプリを作成] ページで：
   1. アプリの名前を入力します。
   2. お客様のご要望に応じてJTIおよび/またはJWEを実施します。
5. [次へ] と [完了] をクリックします。
6. [アプリを管理] ページが表示され、このボットに関連するすべてのアプリが表示されます。
7. アプリを選択すると、[クライアントID] と [クライアントシークレット] のセクションが表示されます。また、ウェブSDKやボットキットSDKなど、このアプリが使用されている場所のリストも表示されます。
8. この画面では、それぞれのアプリに対してゴミ箱のアイコンを使用してアプリを削除することもできます。なお、アプリを削除できるのはボットオーナーのみです。

注意：プラットフォームのバージョン7.3がリリースされる前は、アプリはユーザーに関連付けられていました。このアプリは、プラットフォームのバージョン7.3のリリース以降、ボットに関連付けられています。  ボットオーナー以外のボット開発者は、アプリとスコープの権限を得て、これらのアプリにアクセスできるようになります。後方互換性を確保するために、アプリが複数のボットで使用されている場合は、これらのボットごとに同じ認証情報でアプリが複製されます。

ボットの管理者コンソール

以下の手順では、ボット管理者コンソールからクライアントアプリを作成します。

1. Bot管理ホームページのサイドナビゲーションパネルで、[セキュリティおよび管理] > [APIスコープ] をクリックします。
2. [APIスコープ] ページで [新規] をクリックします。
3. 新しいアプリを作成するには、[アプリを管理] リンクをクリックします。
4. [新しいアプリ] をクリックします。
   1. 名前を入力します。
   2. お客様のご要望に応じてJTIおよび/またはJWEを実施します。
5. [保存] をクリックします。

データテーブル

プラットフォームのバージョン7.3で、データテーブルオプションが追加されました（詳細はこちらをご確認ください）。これらへのアクセスコントロールは、ボットビルダーやボット管理者コンソールのアクセスコントロールとは異なります。データテーブルやデータビューからデータに安全にアクセスするためのアプリを定義することができます。

• 1つ以上のアプリを作成することができ、それらはあなたが所有することになります。方法についてはこちらをご確認ください。
• これらのアプリは、以下の用途で使用されます。
  • 公開APIを介したデータのテーブルやビューへのアクセス
  • サービスノードを使用したデータのテーブルやビューへのアクセス
  • データテーブルやデータビューを定義するためのエクスポートおよびインポートAPIへのアクセス
• このアプリには、テーブルやビューごとに個別に読み取り、書き込み、削除の権限を与えることができます。詳細についてはこちらをご確認ください。

関連するAPIスコープ

クライアントアプリを作成したら、APIスコープと関連付ける必要があります。

ボットビルダー

以下の手順では、ボットビルダーからクライアントアプリにAPIスコープを関連付けます。

1. サイドナビゲーションパネルにカーソルを合わせ、[API拡張] をクリックします。
2. [API拡張] ページで [APIスコープ] タブをクリックし、[新規] をクリックします。
3. [新しいAPIスコープマッピング] ページで、[アプリ] ドロップダウンリストから、認証用の既存のクライアントアプリを選択します。
4. アプリを選択すると、[クライアントID] と [クライアントシークレット] のセクションが表示されます。値をコピーすることができます。
5. [スコープ] セクションで、クライアントアプリにアクセス権限を与えたいAPIを選択します。アプリは、ここで選択されていないAPIにはアクセスすることができません。以下は、選択可能なスコープのリストです。
   • インテントおよびエンティティの検出 – セキュリティで保護されたAPIを使用して、発話からインテントやエンティティを検出できるようにします
   • チャット履歴 – セキュリティで保護されたAPIを使用して、このボットのチャットトランスクリプトを取得します
   • デバッグログ – セキュリティで保護されたAPIを使用して、このボットのデバッグログを取得します
   • ボットをエクスポート – 選択したボットの定義をエクスポートします
   • 変数をインポート – セキュリティで保護されたAPIを使用して、このボットの変数をインポートします
   • 変数をエクスポート – セキュリティで保護されたAPIを使用して、このボットの変数をエクスポートします
   • MLを学習 – 与えられた発話をNLモデルと照合し、発話に含まれる可能性のあるインテントやエンティティを識別します
   • FAQをトレーニング – 指定されたFAQをFAQモデルと照合します
   • 発話のインポート – ボットタスク用に音声をインポートします
   • 発話のエクスポート – ボットタスク用に音声をエクスポートします
   • ログ履歴 – 特定のボットのログ履歴を取得します
   • ボットセッション – ボットの会話セッションを取得します
   • カスタムレポート – カスタムウィジェットやレポートに関連するデータを取得します
   • RCSメッセージイベント – RCSビジネスメッセージングチャネルにユーザーをオプトインし、同報メッセージを送信します
   • 外部ボットをリンク – このアカウントに属さない子ボットのリンクさせます

注意：有効になったら、APIスコープを公開する必要があります。公開手順に従って、[API拡張] オプションから [APIスコープ] が選択されていることを確認します。

ボットの管理者コンソール

以下の手順では、ボット管理者コンソールからクライアントアプリにAPIスコープを関連付けます。

1. Bot管理ホームページのサイドナビゲーションパネルで、[セキュリティおよび管理] > [APIスコープ] をクリックします。
2. [APIスコープ] ページで [新規] をクリックします。
3. [新しいAPIスコープマッピング] ページで、[アプリ] ドロップダウンリストから、認証用の既存のクライアントアプリを選択します。新しいアプリを作成するには、[アプリを管理] リンクをクリックします。
4. アプリを選択すると、[クライアントID] と [クライアントシークレット] のセクションが表示されます。値をコピーします。
5. この画面では、それぞれのアプリに対してゴミ箱のアイコンを使用してアプリを削除することもできます。
6. [スコープ] セクションで、クライアントアプリにアクセス権限を与えたいAPIを選択します。APIスコープのリストについてはこちらを参照してください。

JWTトークンの生成

APIスコープをクライアントアプリに関連付けたら、APIリクエスト用のJWTトークンを生成する必要があります。

1. 以下のリンクを使用してトークンを生成することができます。こちらをクリックします。
2. トークンの生成に使用するアルゴリズム（HS256またはRS256）を選択します。
3. [解読済み] セクションまで下にスクロールします。
4. [ペイロード] ボックスの内容を、前のセクションでコピーしたアプリのクライアントIDに置き換えます。

   { "appId": "your-client-id-here" }

   注意：ボットビルダーは、トークンが正確に「appId」として生成された場合にのみ、トークンを検証します。このプラットフォームでは、「App ID」「appid」「app ID」などの他の形式で生成されたトークンは検証されません。
5. [署名を検証] ボックスでは、
   • HS256エンコーディングの場合は、前のセクションでコピーしたクライアントシークレットをyour-256-bit-secretというテキストのボックスに入力します。
   • RS256エンコーディングの場合は、パブリックキーとプライベートキーを対応するテキストエリアに入力します。注意：キーは [開始] タグと [終了] タグ内に貼り付ける必要があります。
6. 生成されたJWTトークンを上部の [エンコード済み] セクションからコピーするか、下部の [JWTをコピー] ボタンを使用します。
7. このトークンは、必要なAPIにアクセスするために使用され、認証のために各APIリクエストの一部として渡される必要があります。
8. APIコレクションを使用して、PostmanのセットアップからAPIをテストすることができます。詳細はこちらをご確認ください。