Zendesk - Amazon Kendra
サポートされている機能前提条件接続手順詳細メモ

Zendesk

Zendesk は、企業がカスタマーサポートのやり取りを自動化および強化するのに役立つ顧客関係管理システムです。Amazon Kendra を使用して、Zendesk のサポートチケット、チケットコメント、チケット添付ファイル、ヘルプセンターの記事、記事のコメント、記事のコメントの添付ファイル、ガイドコミュニティのトピック、コミュニティの投稿、コミュニティ投稿のコメントのインデックスを作成できます。

特定の組織内のチケットのみにインデックスを付ける場合は、組織名でフィルタリングできます。Zendesk からのデータのクローリングを開始するタイミングに合わせて、クロール日を設定することもできます。

Amazon Kendra コンソールと TemplateConfiguration API を使用して、Amazon Kendra を Zendesk データソースに接続できます。

Amazon Kendra Zendesk データソースコネクタのトラブルシューティングについては、「」を参照してください。

サポートされている機能

Amazon Kendra Zendesk データソースコネクタは以下の機能をサポートしています。

  • フィールドマッピング

  • ユーザーアクセスコントロール

  • 包含/除外フィルター

  • 変更ログ、完全および増分コンテンツ同期

  • 仮想プライベートクラウド (VPC)

前提条件

Amazon Kendra を使用して Zendesk データソースのインデックスを作成するには、Zendesk および AWS アカウントでこれらの変更を行ってください。

Zendesk で以下を確認してください。

  • Zendesk Suite (Professional/Enterprise) の管理者アカウントを作成しました。

  • Zendesk のホスト URL を書き留めました。例: https://{sub-domain}.zendesk.com/

    注記

    (オンプレミス/サーバー) Amazon Kendra は、AWS Secrets Manager に含まれるエンドポイント情報が、データソース設定の詳細で指定されているエンドポイント情報と同じかどうかを確認します。混乱する代理問題は、ユーザーがアクションを実行するアクセス許可がないにもかかわらず、Amazon Kendra をプロキシとして使用して設定された秘密にアクセスし、アクションを実行するセキュリティの問題です。後でエンドポイント情報を変更する場合は、新しいシークレットを作成してこの情報を同期する必要があります。

  • 認可コード付与フローを使用して OAuth 2.0 認証を設定します。

    1. [管理センター] で、[アプリと統合] > [API] > [Zendesk API] に移動します。

    2. [OAuth クライアント] タブを選択し、[OAuth クライアントを追加] をクリックします。

    3. OAuth クライアントの詳細を設定します。[クライアント名] と [説明] を設定します。[クライアントの種類] を [機密] に設定します。適切なリダイレクト URLs を追加します (テスト用に https://localhost/callback など)。生成されたクライアント ID とクライアントシークレットを保存し、安全な状態で保管します。

    4. OAuth クライアントに必要な「読み取り」スコープ (または書き込みアクセスが必要な場合は「読み取り書き込み」) があることを確認します。

    5. 認可コード付与フローを使用してアクセストークンを生成します。

      • ブラウザで、次の URL に移動します: https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&client_id={your_client_id}&redirect_uri={your_redirect_uri}&scope=read

      • プロンプトが表示されたら、アプリケーションを認証と認可を行います。

      • 認可後、Zendesk はコードパラメータ (例: https://localhost/callback?code={authorization_code}) を使用して redirect_uri にリダイレクトします。認可コードをコピーします。

      • Zendesk のトークンエンドポイントに POST リクエストを送信して、認可コードをアクセストークンと交換します。

        curl -X POST https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code={authorization_code}&client_id={your_client_id}&client_secret={your_client_secret}&redirect_uri={your_redirect_uri}&scope=read"

      • Zendesk は access_token を含む JSON オブジェクトで応答します。このアクセストークンを抽出して安全に保管します。

    6. 生成されたアクセストークンを安全な状態で保管します。このアクセストークンは Kendra の統合に使用されます。

  • 注記

    認証情報とシークレットは、定期的に更新またはローテーションすることをお勧めします。セキュリティに必要なアクセスレベルのみを提供してください。認証情報とシークレットを、データソース、コネクタバージョン 1.0 と 2.0 (該当する場合) で再利用することは推奨しません。

  • オプション: Amazon Kendra による接続を許可する SSL 証明書をインストールしました。

  • 各ドキュメントが Zendesk および同じインデックスを使用予定の他のデータソース間で一意であることを確認しました。インデックスに使用する各データソースには、データソース全体に同じドキュメントが含まれていてはなりません。ドキュメント ID はインデックス全体に適用され、インデックスごとに一意である必要があります。

AWS アカウント で以下を確認してください。

  • Amazon Kendra インデックスが作成済みで、API を使用している場合はインデックス ID を記録済み。

  • データソース用の IAM ロールが作成済みで、API を使用している場合は IAM ロールの ARN を記録済み。

    注記

    認証タイプと認証情報を変更した場合、正しい AWS Secrets Manager シークレット ID にアクセスできるように IAM ロールを更新する必要があります。

  • Zendesk の認証情報を AWS Secrets Manager シークレットに保存し、API を使用している場合は、シークレットの ARN を記録しました。

    注記

    認証情報とシークレットは、定期的に更新またはローテーションすることをお勧めします。セキュリティに必要なアクセスレベルのみを提供してください。認証情報とシークレットを、データソース、コネクタバージョン 1.0 と 2.0 (該当する場合) で再利用することは推奨しません。

既存の IAM ロールやシークレットがない場合は、Zendesk データソースを Amazon Kendra に接続するときに、コンソールを使用して新しい IAM ロールと Secrets Manager シークレットを作成できます。API を使用している場合は、既存の IAM ロールと Secrets Manager シークレットの ARN、およびインデックス ID を指定する必要があります。

接続手順

Amazon Kendra を Zendesk データソースに接続するには、Amazon Kendra がデータにアクセスできるように Zendesk データソースの必要な詳細情報を入力する必要があります。Amazon Kendra で Zendesk をまだ設定していない場合は、「前提条件」を参照してください。

Console

Amazon Kendra を Zendesk に接続するには

  1. AWS マネジメントコンソール にサインインして、Amazon Kendra コンソール を開きます。

  2. 左側のナビゲーションペインで、[インデックス] を選択し、インデックスのリストから使用するインデックスを選択します。

    注記

    [インデックスの設定] で、[ユーザーアクセスコントロール] 設定を設定または編集できます。

  3. [使用開始] ページで、[データソースを追加] を選択します。

  4. [データソースを追加] ページで [Zendesk コネクタ] を選択し、[コネクタを追加] を選択します。バージョン 2 (該当する場合) を使用している場合は、「V2.0」タグが付いた [Zendesk コネクタ] を選択します。

  5. [データソースの詳細を指定] ページで、次の情報を入力します。

    1. [名前と説明] の [データソース名] に、データソースの名前を入力します。ハイフン (-) は使用できますが、スペースは使用できません。

    2. (オプション) [説明] - オプションで、データソースの説明を入力します。

    3. [デフォルト言語] - インデックス用にドキュメントをフィルターするための言語。特に指定しない限り、言語はデフォルトで英語に設定されます。ドキュメントのメタデータで指定された言語は、選択した言語よりも優先されます。

    4. [タグ] の [新しいタグを追加] - リソースの検索とフィルタリングや、AWS コストの追跡を行うためのオプションのタグを含めることができます。

    5. [次へ] を選択します。

  6. [アクセスとセキュリティの定義] ページで、次の情報を入力します。

    1. Zendesk URL - Zendesk URL を入力します。例: https://{sub-domain}.zendesk.com/

    2. [承認] - アクセスコントロールリスト (ACL) があり、それをアクセスコントロールに使用する場合に、ドキュメントの ACL 情報を有効にするか無効にするかを選択します。ACL では、ユーザーとグループがアクセスできるドキュメントを指定します。ACL 情報は、ユーザーまたはそのグループのドキュメントへのアクセスに基づいて、検索結果をフィルタリングするために使用されます。詳細については、「User context filtering」を参照してください。

    3. [AWS Secrets Manager シークレット] - Zendesk の認証情報を保存する既存のシークレットを選択するか、新しい Secrets Manager シークレットを作成します。新しいシークレットの作成を選択すると、AWS Secrets Manager シークレットウィンドウが開きます。

      1. 次のような構造でシークレットを作成します。

        {
         "hostUrl": "https://yoursubdomain.zendesk.com/",
         "accessToken": "your_access_token"
}
        注記

        Kendra の統合用に、シークレット名は「AmazonKendra-Zendesk-」で始まり、その後に任意の識別子 (例: AmazonKendra-Zendesk-MyConnector) を付けます。

      2. シークレットを保存して追加します。

    4. [仮想プライベートクラウド (VPC)] - VPC の使用を選択できます。選択する場合は、[サブネット] と [VPC セキュリティグループ] を追加する必要があります。

    5. [ID クローラー] - Amazon Kendra の ID クローラーを有効にするかどうかを指定します。ID クローラーは、ドキュメントのアクセスコントロールリスト (ACL) 情報を使用して、ユーザーまたはそのグループのドキュメントへのアクセス権に基づいて検索結果をフィルタリングします。ドキュメントの ACL があり、ACL を使用する場合は、Amazon Kendra の ID クローラーを有効にして、検索結果のユーザーコンテキストフィルタリングを設定することもできます。それ以外の場合は、ID クローラーがオフになっている場合、すべてのドキュメントは公開され検索可能になります。ID クローラーがオフになっているときにドキュメントのアクセスコントロールを使用する場合は、代わりに PutPrincipalMapping API を使用して、ユーザーコンテキストフィルタリング用にユーザーとグループのアクセス情報をアップロードすることができます。

    6. [IAM ロール] - 既存の IAM ロールを選択するか、新しい IAM ロールを作成して、リポジトリの認証情報とインデックスコンテンツにアクセスします。

      注記

      インデックスに使用される IAM ロールは、データソースには使用できません。インデックスやよくある質問に既存のロールが使用されているかどうかが不明な場合は、エラーを避けるため、[新しいロールを作成] を選択してください。

    7. [次へ] を選択します。

  7. [同期設定の構成] ページで、次の情報を入力します。

    1. [コンテンツを選択] - チケット、ヘルプセンターの記事、コミュニティのトピックなどから、クロールするコンテンツのタイプを選択します。

    2. [組織名] — Zendesk の組織名を入力して同期をフィルタリングします。

    3. [同期開始日] - コンテンツのクローリングを開始する日付を入力します。

    4. [正規表現パターン] - 特定のファイルを含めるまたは除外する正規表現パターンを追加します。最大 100 のパターンを追加できます。

    5. [同期モード] - データソースのコンテンツが変更されたときのインデックスの更新方法を選択します。Amazon Kendra でデータソースを初めて同期すると、デフォルトですべてのコンテンツがクロールされ、インデックスが作成されます。同期モードオプションとして完全同期を選択していない場合でも、最初の同期が失敗した場合は、データの完全同期を実行する必要があります。

      • 完全同期: データソースがインデックスと同期されるたびに、既存のコンテンツを置き換えて、すべてのコンテンツのインデックスを新たに作成します。

      • 新規作成、変更の同期: データソースがインデックスと同期するたびに、新規作成および変更されたコンテンツのみのインデックスを作成します。Amazon Kendra は、データソースのメカニズムを利用してコンテンツの変更を追跡し、前回の同期以降に変更されたコンテンツのインデックスを作成することができます。

      • 新規作成、変更、削除の同期: データソースがインデックスと同期するたびに、新規作成、変更、削除されたコンテンツのみのインデックスを作成します。Amazon Kendra は、データソースのメカニズムを利用してコンテンツの変更を追跡し、前回の同期以降に変更されたコンテンツのインデックスを作成することができます。

    6. [同期実行スケジュール] の [頻度] - データソースコンテンツを同期してインデックスを更新する頻度を選択します。

    7. [次へ] を選択します。

  8. [フィールドマッピングを設定] ページで、次の情報を入力します。

    1. [デフォルトのデータソースフィールド] - インデックスにマッピングする Amazon Kendra 生成のデフォルトのデータソースフィールドから選択します。

    2. [フィールドを追加] - カスタムデータソースフィールドを追加して、マッピング先のインデックスフィールド名とフィールドデータタイプを作成します。

    3. [次へ] を選択します。

  9. [確認と作成] ページで、入力した情報が正しいことを確認し、[データソースを追加] を選択します。このページで情報の編集を選択することもできます。データソースが正常に追加されると、データソースが [データソース] ページに表示されます。

API

Amazon Kendra を Zendesk に接続するには

TemplateConfiguration API を使用してデータソーススキーマの JSON を指定する必要があります。これには、以下の情報を入力する必要があります。

  • [データソース] — TemplateConfiguration JSON スキーマを使用する場合は、データソースタイプを ZENDESK と指定します。また、CreateDataSource API を呼び出す場合は、データソースを TEMPLATE と指定します。

  • ホスト URL - 接続設定またはリポジトリエンドポイントの詳細の一部として Zendesk ホスト URL を提供します。例えば、 https://yoursubdomain.zendesk.com です。

  • 変更ログ - インデックス内でドキュメントを更新する必要があるかどうかを判断するために、Amazon Kendra が Zendesk データソース変更ログメカニズムを使用するかどうか。

    注記

    Amazon Kendra にすべてのドキュメントをスキャンさせない場合は、変更ログを使用します。変更ログが大きい場合、Amazon Kendra は変更ログを処理するよりも Zendesk データソースのドキュメントのスキャンにかかる時間が短くなる場合があります。Zendesk データソースをインデックスに初めて同期する場合は、すべてのドキュメントがスキャンされます。

  • [シークレット Amazon リソースネーム (ARN)] - Zendesk アカウントの認証情報が保存されている Secrets Manager シークレットの Amazon リソースネーム (ARN) を指定します。シークレットは、次のキーを含む JSON 構造に保存されます。

    {
    "hostUrl": "https://yoursubdomain.zendesk.com",
    "clientId": "client ID",
    "clientSecret": "Zendesk client secret",
    "userName": "Zendesk user name",
    "password": "Zendesk password"
}

  • [IAM ロール] - CreateDataSource を呼び出す際に RoleArn を指定して、Secrets Manager シークレットへのアクセス許可を IAM ロールに提供し、Zendesk コネクタと Amazon Kendra に必要なパブリック API を呼び出します。詳細については、「IAM roles for Zendesk data sources」を参照してください。

オプションで、次の機能を追加することもできます。

  • [仮想プライベートクラウド (VPC)] - VpcConfiguration で CreateDataSource を呼び出すタイミングを指定します。詳細については、「Amazon VPC を使用するための Amazon Kendra の設定」を参照してください。

  • ドキュメント/コンテンツタイプ — 以下をクロールするかどうかを指定します。

    • サポートチケット、チケットコメント、チケットコメントの添付ファイル

    • ヘルプセンターの記事、記事の添付ファイル、記事のコメント

    • コミュニティトピック、投稿、投稿コメントのガイド

  • [包含フィルターと除外フィルター] - Slack の特定のコンテンツを含める、または除外するように指定できます。Slack 認証情報の一部としてボットトークンを使用する場合、インデックスを作成するチャネルにボットトークンを追加する必要があります。ボットトークンを使用してダイレクトメッセージやグループメッセージのインデックスを作成することはできません。

    注記

    ほとんどのデータソースは、フィルターと呼ばれる包含または除外パターンである正規表現パターンを使用しています。包含フィルターを指定すると、包含フィルターに一致するコンテンツのみのインデックスが作成されます。包含フィルターに一致しないドキュメントのインデックスは作成されません。包含フィルターと除外フィルターを指定した場合、除外フィルターに一致するドキュメントは、包含フィルターと一致してもインデックスは作成されません。

  • [ユーザーコンテキストのフィルタリングとアクセスコントロール] — ドキュメントの ACL がある場合は、Amazon Kendra がドキュメントのアクセスコントロールリスト (ACL) をクロールします。ACL 情報は、ユーザーまたはそのグループのドキュメントへのアクセスに基づいて、検索結果をフィルタリングするために使用されます。詳細については、「User context filtering」を参照してください。

  • フィールドマッピング - 選択すると、Zendesk データソースフィールドを Amazon Kendra インデックスフィールドにマッピングします。詳細については、「データソースフィールドのマッピング」を参照してください。

    注記

    Amazon Kendra がドキュメントを検索するには、ドキュメント本文フィールドまたはドキュメントと同等のドキュメント本文が必要です。データソースのドキュメント本文フィールド名をインデックスフィールド名 _document_body にマッピングする必要があります。その他のすべてのフィールドはオプションです。

設定が必要なその他の重要な JSON キーのリストについては、「Zendesk テンプレートスキーマ」を参照してください。

詳細

Amazon Kendra と Zendesk データソースのユーザーコンテキストフィルタリングデータソースとの統合については、以下を参照してください。

メモ

  • アクセスコントロール (ACL) が有効になっている場合、Zendesk API の制限により、[新規または変更されたコンテンツのみを同期] オプションを使用できません。この同期モードを使用する必要がある場合は、代わりに「完全同期」または「新規、変更済み、または削除済みコンテンツ同期」モードを使用するか、ACL を無効にすることをお勧めします。