Zenn
🪨

Kendra の Web Crawler v2.0 と Confluence v2.0 のデータソースを AWS CLI で作成

2024/11/28に公開
AWS
Confluence
Kendra
tech

1. はじめに

Amazon Kendra は、Apache Solrベースのフルマネージドサービスです。RAG(Retrieval Augmented Generation) を実装したものの、検索対象のドキュメントが日々追加更新できなくて困る場合もあると思います。 その場合、データ取り込み(index 再構築)機能をすでに備えているフルマネージドなサービスを検討してみるのも手です。

Amazon Kendra Web Crawler connector v2.0 と Confluence connector v2.0 が、Terraform 対応していなかったので、AWS CLI 定義する方法をメモしておきます。

2. Kendra の Web Crawler v2.0 と Confluence v2.0 について

Amazon Kendra の Web Crawler v2.0 は、公開されている Web サイトから情報を収集します。 Confluence connector v2.0 は、Atlassian Confluence から情報を収集します。 どちらも、データを収集後に、Kendra インデックスに統合するために使います。

3. AWS CLI での Data Source 構築方法

3.1 AWS CLI で Data Source を構築する理由

Kendra の多くの Data Connector は、IaC も対応しているものの、 Amazon Kendra Web Crawler connector v2.0 と Confluence connector V2.0 は、対応していません!!

苦肉の策ですが、AWS CLI で 上記の connector の設定を書く方法をメモしておきます。[1]

Kendra の index は、Terraform で構築可能なので、index や IAM の設定はすでに構築ずみとします。

3.2 Web Crawler v2.0 Connector 設定方法

下記の json と aws コマンドの <ほげ> の箇所を埋めれば最低限動きます。

aws kendra create-data-source \
    --type TEMPLATE \
    --index-id <kendra index id> \
    --cli-input-json file://<設定用のjsonファイルのパス>
json ファイル例
{
  "Name": "<data_source_name>",
  "Configuration": {
    "TemplateConfiguration": {
      "Template": {
        "connectionConfiguration": {
          "repositoryEndpointMetadata": {
            "s3SeedUrl": null,
            "s3SiteMapUrl": null,
            "siteMapUrls": null,
            "seedUrlConnections": [
              {
                "seedUrl": "<crawl対象のURL>"
              }
            ],
            "authentication": "NoAuthentication"
          }
        },
        "syncMode": "FULL_CRAWL",
        "additionalProperties": {
          "inclusionURLCrawlPatterns": [],
          "rateLimit": "300",
          "maxFileSize": "50",
          "crawlDepth": "10",
          "crawlAllDomain": false,
          "crawlSubDomain": false,
          "inclusionURLIndexPatterns": [],
          "exclusionFileIndexPatterns": [],
          "proxy": {},
          "exclusionURLCrawlPatterns": [],
          "exclusionURLIndexPatterns": [],
          "crawlAttachments": false,
          "honorRobots": true,
          "inclusionFileIndexPatterns": [],
          "crawlDomainsOnly": true,
          "maxLinksPerUrl": "100"
        },
        "type": "WEBCRAWLERV2",
        "version": "1.0.0",
        "repositoryConfigurations": {
          "attachment": {
            "fieldMappings": [
              {
                "dataSourceFieldName": "category",
                "indexFieldName": "_category",
                "indexFieldType": "STRING"
              },
              {
                "dataSourceFieldName": "sourceUrl",
                "indexFieldName": "_source_uri",
                "indexFieldType": "STRING"
              }
            ]
          },
          "webPage": {
            "fieldMappings": [
              {
                "dataSourceFieldName": "category",
                "indexFieldName": "_category",
                "indexFieldType": "STRING"
              },
              {
                "dataSourceFieldName": "sourceUrl",
                "indexFieldName": "_source_uri",
                "indexFieldType": "STRING"
              },
              {
                "dataSourceFieldName": "title",
                "indexFieldName": "_document_title",
                "indexFieldType": "STRING"
              }
            ]
          }
        }
      }
    }
  },
  "Description": "<このデータソースの説明>",
  "Schedule": "cron(0 4 ? * SUN *)",
  "LanguageCode": "ja",
  "RoleArn": "<このdata source用のRoleのArn>"
}

3.2.1. Kendra index ID を確認する手順

まず、Kendra の index ID を確認します。Kendra の data source は index に紐づくので、後のコマンドで必要になります。
以下のコマンドを実行して、index ID を取得してください。

aws kendra list-indices

出力に、 "Id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6", のように Id の項目が出るのでメモしてください。
後で、 <kendra index id> として使います。

3.2.2 json の設定項目

次に、Web Crawler V2 のデータソースを設定します。以下の手順で JSON ファイルを作成し、AWS CLI を使用してデータソースを作成します。

  1. <data_source_name>: e.g., sample_data_source
  2. <crawl 対象の URL>: e.g., https://example.com/
  3. <このデータソースの説明>: e.g., example.com 配下のすべてを取得
  4. <この data source 用の Role の Arn>: e.g., arn:aws:iam::123456789012:role/service-role/sample-role (※1)

"Schedule": "cron(0 4 ? * SUN *)" の箇所は、特に説明を書きませんが、よしなに設定してください。

(※1) 適切な role 設定がわからない場合は、コンソールで data source を作る際に、create a new role(Recommended) と出るので、それを参考にしてみてください。

{
  "Name": "<data_source_name>",
  "Configuration": {
    "TemplateConfiguration": {
      "Template": {
        "connectionConfiguration": {
          "repositoryEndpointMetadata": {
            "s3SeedUrl": null,
            "s3SiteMapUrl": null,
            "siteMapUrls": null,
            "seedUrlConnections": [
              {
                "seedUrl": "<crawl対象のURL>"
              }
            ],
            "authentication": "NoAuthentication"
          }
        },
        "syncMode": "FULL_CRAWL",
        "additionalProperties": {
          "inclusionURLCrawlPatterns": [],
          "rateLimit": "300",
          "maxFileSize": "50",
          "crawlDepth": "10",
          "crawlAllDomain": false,
          "crawlSubDomain": false,
          "inclusionURLIndexPatterns": [],
          "exclusionFileIndexPatterns": [],
          "proxy": {},
          "exclusionURLCrawlPatterns": [],
          "exclusionURLIndexPatterns": [],
          "crawlAttachments": false,
          "honorRobots": true,
          "inclusionFileIndexPatterns": [],
          "crawlDomainsOnly": true,
          "maxLinksPerUrl": "100"
        },
        "type": "WEBCRAWLERV2",
        "version": "1.0.0",
        "repositoryConfigurations": {
          "attachment": {
            "fieldMappings": [
              {
                "dataSourceFieldName": "category",
                "indexFieldName": "_category",
                "indexFieldType": "STRING"
              },
              {
                "dataSourceFieldName": "sourceUrl",
                "indexFieldName": "_source_uri",
                "indexFieldType": "STRING"
              }
            ]
          },
          "webPage": {
            "fieldMappings": [
              {
                "dataSourceFieldName": "category",
                "indexFieldName": "_category",
                "indexFieldType": "STRING"
              },
              {
                "dataSourceFieldName": "sourceUrl",
                "indexFieldName": "_source_uri",
                "indexFieldType": "STRING"
              },
              {
                "dataSourceFieldName": "title",
                "indexFieldName": "_document_title",
                "indexFieldType": "STRING"
              }
            ]
          }
        }
      }
    }
  },
  "Description": "<このデータソースの説明>",
  "Schedule": "cron(0 4 ? * SUN *)",
  "LanguageCode": "ja",
  "RoleArn": "<このdata source用のRoleのArn>"
}

この json のファイル名は、crawler_v2_setting.json として、current directory に保存されているとします。

web crawler v2.0 のデータソースを作成するには、以下のコマンドを実行します。

aws kendra create-data-source \
    --type TEMPLATE \
    --index-id <取得したKendraインデックスID> \
    --cli-input-json file://crawler_v2_setting.json

3.3 Confluence v2.0 Data Connector 設定方法

大枠は、 Web Crawler v2.0 と同様です。
kendra index ID をメモっておくのと、json ファイルを作成して、aws コマンドを実行するだけです。

3.3.1 Kendra インデックス ID を確認する手順

Web Crawler v2.0 と同様に、Kendra index ID を確認します。

aws kendra list-indices

出力に、 "Id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6", のように Id の項目が出るのでメモしてください。
後で、 <kendra index id> として使います。

3.3.2 json の設定項目

次に、Confluence v2.0 のデータソースを設定します。以下の手順で JSON ファイルを作成し、AWS CLI を使用してデータソースを作成します。

  1. <confluence_data_source_name>: e.g., sample_confluence_data_source
  2. <confluence_host_url>: crawl 対象の confluence の URL e.g., https://your_company_name.atlassian.com/ confluence cloud を使っている場合は、your_company_name のところが会社名や部署名になっていることが多いと思います。
  3. <your_secret_arn>: 暗号化する場合は、Secrets Manager を先に作成しておいてください。 e.g., arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:your_secrets_manager_name-xxxxxx
  4. <your_space_name1>: crawl 対象 confluence の space 名
  5. <your_space_name2>: 同上。crawl 対象が一つだけなら、複数指定不要です。
  6. <your_description>: このデータソースの説明
  7. <your_role_arn>: e.g., arn:aws:iam::123456789012:role/service-role/confluence-sample-role (※2)

"Schedule": "cron(0 19 * * ? *)", の箇所は、特に説明を書きませんが、よしなに設定してください。

(※2) web crawler v2.0 のときと同様に、適切な role 設定がわからない場合は、コンソールで data source を作る際に、create a new role(Recommended) と出るので、それを参考にしてみてください。結果的に web crawler v2.0 のときと同じ権限になるかもしれないですが、別 role として定義しておくことを推奨します。

aws kendra create-data-source \
    --type TEMPLATE \
    --index-id <取得したKendraインデックスID> \
    --cli-input-json file://<設定ファイルのパス>

{
  "Name": "<confluence_data_source_name>",
  "Configuration": {
    "TemplateConfiguration": {
      "Template": {
        "connectionConfiguration": {
          "repositoryEndpointMetadata": {
            "type": "SAAS",
            "authType": "Basic",
            "hostUrl": "<confluence_host_url>"
          }
        },
        "enableIdentityCrawler": false,
        "secretArn": "<your_secret_arn>",
        "syncMode": "FULL_CRAWL",
        "additionalProperties": {
          "isCrawlPageComment": false,
          "exclusionUrlPatterns": [],
          "inclusionFileTypePatterns": [],
          "isCrawlBlog": true,
          "usersAclS3FilePath": "",
          "blogTitleRegEX": [],
          "proxyPort": "",
          "inclusionUrlPatterns": [],
          "attachmentTitleRegEX": [],
          "isCrawlPage": true,
          "fieldForUserId": "email",
          "commentTitleRegEX": [],
          "exclusionSpaceKeyFilter": [],
          "isCrawlBlogAttachment": false,
          "isCrawlPersonalSpace": true,
          "exclusionFileTypePatterns": [],
          "isCrawlPageAttachment": false,
          "inclusionSpaceKeyFilter": [
            "<your_space_name1>",
            "<your_space_name2>"
          ],
          "maxFileSizeInMegaBytes": "50",
          "proxyHost": "",
          "isCrawlArchivedSpace": false,
          "isCrawlArchivedPage": false,
          "isCrawlAcl": true,
          "pageTitleRegEX": [],
          "isCrawlBlogComment": false
        },
        "type": "CONFLUENCEV2",
        "version": "1.0.0",
        "repositoryConfigurations": {
          "comment": {
            "fieldMappings": []
          },
          "page": {
            "fieldMappings": [
              {
                "dataSourceFieldName": "author",
                "indexFieldName": "_authors",
                "indexFieldType": "STRING_LIST"
              },
              {
                "dataSourceFieldName": "createdDate",
                "indexFieldName": "_created_at",
                "dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'",
                "indexFieldType": "DATE"
              },
              {
                "dataSourceFieldName": "modifiedDate",
                "indexFieldName": "_last_updated_at",
                "dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'",
                "indexFieldType": "DATE"
              },
              {
                "dataSourceFieldName": "itemType",
                "indexFieldName": "_category",
                "indexFieldType": "STRING"
              },
              {
                "dataSourceFieldName": "url",
                "indexFieldName": "_source_uri",
                "indexFieldType": "STRING"
              },
              {
                "dataSourceFieldName": "title",
                "indexFieldName": "_document_title",
                "indexFieldType": "STRING"
              }
            ]
          },
          "blog": {
            "fieldMappings": [
              {
                "dataSourceFieldName": "author",
                "indexFieldName": "_authors",
                "indexFieldType": "STRING_LIST"
              },
              {
                "dataSourceFieldName": "publishedDate",
                "indexFieldName": "_created_at",
                "dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'",
                "indexFieldType": "DATE"
              },
              {
                "dataSourceFieldName": "modifiedDate",
                "indexFieldName": "_last_updated_at",
                "dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'",
                "indexFieldType": "DATE"
              },
              {
                "dataSourceFieldName": "url",
                "indexFieldName": "_source_uri",
                "indexFieldType": "STRING"
              },
              {
                "dataSourceFieldName": "title",
                "indexFieldName": "_document_title",
                "indexFieldType": "STRING"
              }
            ]
          },
          "attachment": {
            "fieldMappings": []
          },
          "space": {
            "fieldMappings": [
              {
                "dataSourceFieldName": "itemType",
                "indexFieldName": "_category",
                "indexFieldType": "STRING"
              },
              {
                "dataSourceFieldName": "url",
                "indexFieldName": "_source_uri",
                "indexFieldType": "STRING"
              },
              {
                "dataSourceFieldName": "description",
                "indexFieldName": "cf_description",
                "indexFieldType": "STRING"
              }
            ]
          }
        }
      }
    }
  },
  "Description": "<your_description>",
  "Schedule": "cron(0 19 * * ? *)",
  "RoleArn": "<your_role_arn>",
  "LanguageCode": "ja"
}

この json のファイル名を、confluence_v2_setting.json として、current directory に保存されているとします。

confluence v2.0 のデータソースを作成するには、以下のコマンドを実行します。

aws kendra create-data-source \
    --type TEMPLATE \
    --index-id <取得したKendraインデックスID> \
    --cli-input-json file://confluence_v2_setting.json

4. まとめ

本記事では、AWS Kendra の Web Crawler v2.0 と Confluence v2.0 のデータソースを AWS CLI を使用して構築する方法を紹介しました。どこかのタイミングで、Terraform, CDK, CloudFormation などの IaC ツールが対応する可能性があるので、その場合は素直に IaC ツールを使ってください。

脚注

  1. terraform のドキュメントを見ると、少なくとも web crawler v1.0 は対応していたように見えます。バージョンが上がって未対応になっています。 ↩︎

Discussion