翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Atlassian サービスでの OpenSearch Ingestion パイプラインの使用
Atlassian Jira および Confluence ソースプラグインを使用して、Atlassian サービスからのデータを OpenSearch Ingestion パイプラインにデータを取り込むことができます。これらの統合により、継続的なモニタリングと更新の自動同期を通じてリアルタイムの関連性を維持しながら、完全な Jira プロジェクトと Confluence スペースを同期することで、統合された検索可能なナレッジベースを作成できます。
------
#### [ Integrating with Jira ]
Jira コンテンツを OpenSearch に統合することで、強力なコンテキスト検索機能を使用して Jira エクスペリエンスを変換します。Data Prepper [Atlassian Jira](https://www.atlassian.com/software/jira) ソースプラグインを使用すると、継続的なモニタリングと更新の自動同期を通じてリアルタイムの関連性を維持しながら、完全な Jira プロジェクトを同期することで、統合された検索可能なナレッジベースを作成できます。この統合により、特定のプロジェクト、問題タイプ、ステータスの柔軟なフィルタリングオプションによるデータ同期が可能になり、必要な情報のみがインポートされます。
安全で信頼性の高い接続を確保するために、プラグインは基本的な API キー認証や OAuth2 認証など、複数の認証方法をサポートし、 AWS Secrets Managerに保存されているシークレットを使用して認証情報を管理するセキュリティを強化します。また、中断のないアクセスのためのトークンの自動更新機能も備えているため、継続的なオペレーションが保証されます。Atlassian の [API バージョン 2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#version%22%3Eapi-version-2) 上に構築されたこの統合により、チームは OpenSearch の高度な検索機能を通じて Jira データから貴重なインサイトを引き出すことができます。
------
#### [ Integrating with Confluence ]
Data Prepper の Confluence ソースプラグインを使用して [Atlassian Confluence](https://www.atlassian.com/software/confluence) コンテンツを OpenSearch に統合することで、チームのナレッジ管理とコラボレーション機能を強化します。この統合により、一元化された検索可能な集合的知識のリポジトリを作成し、情報検出とチームの生産性を向上させることができます。Confluence コンテンツを同期し、更新を継続的にモニタリングすることで、プラグインは OpenSearch インデックスが常に最新かつ包括的な状態に保たれるようにします。
統合には柔軟なフィルタリングオプションが用意されているため、特定のスペースやページタイプからコンテンツを選択的にインポートし、同期されたコンテンツを組織のニーズに合わせて調整できます。プラグインは、基本的な API キーと OAuth2 認証方法の両方をサポートし、 AWS Secrets Managerを介して認証情報を安全に管理することもできます。プラグインの自動トークン更新機能により、中断のないアクセスとシームレスな操作が保証されます。Atlassian の Confluence [API](https://developer.atlassian.com/cloud/confluence/rest/v1/intro/#auth) 上に構築されたこの統合により、チームは Confluence コンテンツ全体で OpenSearch の高度な検索機能を活用して、組織内の情報のアクセシビリティと使用率を高めることができます。
------
**Topics**
+ [前提条件](#atlassian-prerequisites)
+ [パイプラインロールの設定](#atlassian-pipeline-role)
+ [Jira コネクタパイプライン設定](#jira-connector-pipeline)
+ [Confluence コネクタパイプライン設定](#confluence-connector-pipeline)
+ [データ整合性](#data-consistency)
+ [制限事項](#limitations)
+ [アトラシアンコネクタの CloudWatch のメトリクス](#metrics)
+ [OAuth 2.0 を使用して Amazon OpenSearch Ingestion パイプラインを Atlassian Jira または Confluence に接続する](configure-client-atlassian-OAuth2-setup.md)
## 前提条件
OpenSearch Ingestion パイプラインを作成する前に、次の手順を完了します。
1. 次のいずれかのオプションを選択して、Jira サイトの認証情報を準備します。OpenSearch Ingestion では、コンテンツに対する `ReadOnly` 認可のみが必要です。
1. **オプション 1: API キー** – Atlassian アカウントにログインし、次のトピックの情報を使用して API キーを生成します。
+ [Atlassian アカウントの API トークンを管理する](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)
1. **オプション 2: OAuth2** – Atlassian アカウントにログインし、[OAuth 2.0 を使用して Amazon OpenSearch Ingestion パイプラインを Atlassian Jira または Confluence に接続する](configure-client-atlassian-OAuth2-setup.md) の情報を使用します。
1. [AWS Secrets Managerにシークレットを作成](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)し、前の手順で作成した認証情報の詳細を保存ます。手順に従って、次の選択を行います。
+ **[Secret type] (シークレットタイプ)** で、**[Other type of secret]** (他の種類のシークレット) を選択します。
+ **[キー/値のペア]** の場合、選択した認可タイプに応じて次のペアを作成します。
------
#### [ API key ]
```
{
"username": user-name-usualy-email-id,
"password": api-key
}
```
------
#### [ OAuth 2.0 ]
```
{
"clientId": client-id
"clientSecret": client-secret
"accessKey": access-key
"refreshKey": refresh-key
}
```
------
シークレットを作成したら、シークレットの Amazon リソースネーム (ARN) をコピーします。パイプラインロールのアクセス許可ポリシーに含めます。
## パイプラインロールの設定
パイプラインで渡されるロールには、前提条件セクションで作成されたシークレットを読み書きするための次のポリシーがアタッチされている必要があります。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretReadWrite",
"Effect": "Allow",
"Action": [
"secretsmanager:GetResourcePolicy",
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret",
"secretsmanager:PutSecretValue",
"secretsmanager:ListSecretVersionIds"
],
"Resource": "arn:aws:secretsmanager:us-east-1:111122223333:secret:secret-name-random-6-characters"
}
]
}
```
------
ロールには、選択したシンクにアクセスして書き込むためのポリシーもアタッチする必要があります。例えば、シンクとして OpenSearch を選択した場合、ポリシーは次のようになります。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "OpenSearchWritePolicy",
"Effect": "Allow",
"Action": "aoss:*",
"Resource": "arn:aws:aoss:us-east-1:111122223333:collection/collection-id"
}
]
}
```
------
## Jira コネクタパイプライン設定
事前設定された Atlassian Jira ブループリントを使用して、このパイプラインを作成できます。詳細については、「[ブループリントの使用](pipeline-blueprint.md)」を参照してください。
*プレースホルダー値*を、ユーザー自身の情報に置き換えます。
```
version: "2"
extension:
aws:
secrets:
jira-account-credentials:
secret_id: "secret-arn"
region: "secret-region"
sts_role_arn: "arn:aws:iam::123456789012:role/Example-Role"
atlassian-jira-pipeline:
source:
jira:
# We only support one host url for now
hosts: ["jira-host-url"]
acknowledgments: true
authentication:
# Provide one of the authentication method to use. Supported methods are 'basic' and 'oauth2'.
# For basic authentication, password is the API key that you generate using your jira account
basic:
username: ${{aws_secrets:jira-account-credentials:username}}
password: ${{aws_secrets:jira-account-credentials:password}}
# For OAuth2 based authentication, we require the following 4 key values stored in the secret
# Follow atlassian instructions at the below link to generate these keys.
# https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/
# If you are using OAuth2 authentication, we also require, write permission to your AWS secret to
# be able to write the renewed tokens back into the secret.
# oauth2:
# client_id: ${{aws_secrets:jira-account-credentials:clientId}}
# client_secret: ${{aws_secrets:jira-account-credentials:clientSecret}}
# access_token: ${{aws_secrets:jira-account-credentials:accessToken}}
# refresh_token: ${{aws_secrets:jira-account-credentials:refreshToken}}
filter:
project:
key:
include:
# This is not project name.
# It is an alphanumeric project key that you can find under project details in Jira.
- "project-key"
- "project-key"
# exclude:
# - "project-key"
# - "project-key"
issue_type:
include:
- "issue-type"
# - "Story"
# - "Bug"
# - "Task"
# exclude:
# - "Epic"
status:
include:
- "ticket-status"
# - "To Do"
# - "In Progress"
# - "Done"
# exclude:
# - "Backlog"
sink:
- opensearch:
# Provide an Amazon OpenSearch Service domain endpoint
hosts: [ "https://search-mydomain-1a2a3a4a5a6a7a8a9a0a9a8a7a.us-east-1.es.amazonaws.com" ]
index: "index_${getMetadata(\"project\")}"
# Ensure adding unique document id which is the unique ticket id in this case
document_id: '${/id}'
aws:
# Provide a Role ARN with access to the domain. This role should have a trust relationship with osis-pipelines.amazonaws.com
sts_role_arn: "arn:aws:iam::123456789012:role/Example-Role"
# Provide the region of the domain.
region: "us-east-1"
# Enable the 'serverless' flag if the sink is an Amazon OpenSearch Serverless collection
serverless: false
# serverless_options:
# Specify a name here to create or update network policy for the serverless collection
# network_policy_name: "network-policy-name"
# Enable the 'distribution_version' setting if the Amazon OpenSearch Service domain is of version Elasticsearch 6.x
# distribution_version: "es6"
# Enable and switch the 'enable_request_compression' flag if the default compression setting is changed in the domain.
# See Amazon OpenSearch Service での HTTP リクエストの圧縮
# enable_request_compression: true/false
# Optional: Enable the S3 DLQ to capture any failed requests in an S3 bucket. Delete this entire block if you don't want a DLQ.
dlq:
s3:
# Provide an S3 bucket
bucket: "your-dlq-bucket-name"
# Provide a key path prefix for the failed requests
# key_path_prefix: "kinesis-pipeline/logs/dlq"
# Provide the region of the bucket.
region: "us-east-1"
# Provide a Role ARN with access to the bucket. This role should have a trust relationship with osis-pipelines.amazonaws.com
sts_role_arn: "arn:aws:iam::123456789012:role/Example-Role"
```
Jira ソースの属性へのキー:
1. **hosts**: Jira クラウドまたはオンプレミス URL。一般的に、`https://your-domain-name.atlassian.net/` のようになります。
1. **acknowledgments**: シンクへのデータの配信を保証します。
1. **authentication**: パイプラインが Jira インスタンスにアクセスする方法について説明します。`Basic` または `OAuth2`を選択し、シー AWS クレット内のキーを参照する対応するキー属性を指定します。
1. **filter**: このセクションでは、Jira データのどの部分を抽出して同期するかを選択するのに役立ちます。
1. **project**: 同期するプロジェクトキーを `include` セクションに一覧表示します。それ以外の場合は、`exclude` セクションで除外するプロジェクトを一覧表示します。任意の時点で包含オプションまたは除外オプションを 1 つだけ指定します。
1. **issue\$1type**: 同期する特定の問題タイプ。ニーズに合った同様のパターン `include` または `exclude` パターンに従います。添付ファイルは元の添付ファイルへのアンカーリンクとして表示されますが、添付ファイルの内容は抽出されないことに注意してください。
1. **status**: データ抽出クエリに適用する特定のステータスフィルター。`include` を指定した場合、これらのステータスのチケットのみが同期されます。`exclude` を指定した場合、除外ステータスがリストされているチケットを除くすべてのチケットが同期されます。
## Confluence コネクタパイプライン設定
事前設定された Atlassian Confluence ブループリントを使用して、このパイプラインを作成できます。詳細については、「[ブループリントの使用](pipeline-blueprint.md)」を参照してください。
```
version: "2"
extension:
aws:
secrets:
confluence-account-credentials:
secret_id: "secret-arn"
region: "secret-region"
sts_role_arn: "arn:aws:iam::123456789012:role/Example-Role"
atlassian-confluence-pipeline:
source:
confluence:
# We currently support only one host URL.
hosts: ["confluence-host-url"]
acknowledgments: true
authentication:
# Provide one of the authentication method to use. Supported methods are 'basic' and 'oauth2'.
# For basic authentication, password is the API key that you generate using your Confluence account
basic:
username: ${{aws_secrets:confluence-account-credentials:confluenceId}}
password: ${{aws_secrets:confluence-account-credentials:confluenceCredential}}
# For OAuth2 based authentication, we require the following 4 key values stored in the secret
# Follow atlassian instructions at the following link to generate these keys:
# https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/
# If you are using OAuth2 authentication, we also require write permission to your AWS secret to
# be able to write the renewed tokens back into the secret.
# oauth2:
# client_id: ${{aws_secrets:confluence-account-credentials:clientId}}
# client_secret: ${{aws_secrets:confluence-account-credentials:clientSecret}}
# access_token: ${{aws_secrets:confluence-account-credentials:accessToken}}
# refresh_token: ${{aws_secrets:confluence-account-credentials:refreshToken}}
filter:
space:
key:
include:
# This is not space name.
# It is a space key that you can find under space details in Confluence.
- "space key"
- "space key"
# exclude:
# - "space key"
# - "space key"
page_type:
include:
- "content type"
# - "page"
# - "blogpost"
# - "comment"
# exclude:
# - "attachment"
sink:
- opensearch:
# Provide an Amazon OpenSearch Service domain endpoint
hosts: [ "https://search-mydomain-1a2a3a4a5a6a7a8a9a0a9a8a7a.us-east-1.es.amazonaws.com" ]
index: "index_${getMetadata(\"space\")}"
# Ensure adding unique document id which is the unique ticket ID in this case.
document_id: '${/id}'
aws:
# Provide the Amazon Resource Name (ARN) for a role with access to the domain. This role should have a trust relationship with osis-pipelines.amazonaws.com.
sts_role_arn: "arn:aws:iam::123456789012:role/Example-Role"
# Provide the Region of the domain.
region: "us-east-1"
# Enable the 'serverless' flag if the sink is an Amazon OpenSearch Serverless collection
serverless: false
# serverless_options:
# Specify a name here to create or update network policy for the serverless collection.
# network_policy_name: "network-policy-name"
# Enable the 'distribution_version' setting if the Amazon OpenSearch Service domain is of version Elasticsearch 6.x
# distribution_version: "es6"
# Enable and switch the 'enable_request_compression' flag if the default compression setting is changed in the domain.
# For more information, see Amazon OpenSearch Service での HTTP リクエストの圧縮.
# enable_request_compression: true/false
# Optional: Enable the S3 DLQ to capture any failed requests in an S3 bucket. Delete this entire block if you don't want a DLQ.
dlq:
s3:
# Provide an S3 bucket
bucket: "your-dlq-bucket-name"
# Provide a key path prefix for the failed requests
# key_path_prefix: "kinesis-pipeline/logs/dlq"
# Provide the Rregion of the bucket.
region: "us-east-1"
# Provide the Amazon Resource Name (ARN) for a role with access to the bucket. This role should have a trust relationship with osis-pipelines.amazonaws.com
sts_role_arn: "arn:aws:iam::123456789012:role/Example-Role"
```
Confluence ソースのキー属性:
1. **hosts**: Confluence クラウドまたはオンプレミス URL。一般的に、`https://your-domain-name.atlassian.net/` のようになります
1. **acknowledgments**: シンクへのデータの配信を保証します。
1. **authentication**: パイプラインが Confluence インスタンスにアクセスする方法について説明します。`Basic` または `OAuth2`を選択し、シー AWS クレット内のキーを参照する対応するキー属性を指定します。
1. **filter**: このセクションでは、Confluence データのどの部分を抽出して同期するかを選択するのに役立ちます。
1. **space**: 同期するスペースキーを `include` セクションに一覧表示します。それ以外の場合は、`exclude` セクションで除外するスペースを一覧表示します。任意の時点で包含オプションまたは除外オプションを 1 つだけ指定します。
1. **page\$1type**: 同期する特定のページタイプ (ページ、ブログ投稿、添付ファイルなど)。ニーズに合った同様のパターン `include` または `exclude` パターンに従います。添付ファイルは元の添付ファイルへのアンカーリンクとして表示されますが、添付ファイルの内容は抽出されないことに注意してください。
## データ整合性
パイプライン YAML で指定されたフィルターに基づいて、選択したプロジェクト (またはスペース) が 1 回抽出され、ターゲットシンクに完全に同期されます。その後、継続的な変更モニタリングは、変更が発生したときに変更をキャプチャし、シンク内のデータを更新します。1 つの例外は、変更モニタリングが `delete` アクションではなく、アクション `create` と `update` アクションのみを同期することです。
## 制限事項
+ ユーザー削除アクションは同期されません。シンクに記録されたデータは、シンクに残ります。ID マッピングがシンク設定で指定されている場合、更新によって既存のコンテンツが新しい変更で上書きされます。
+ 次の API をサポートしていない古いバージョンの Atlassian ソフトウェアを使用するオンプレミスインスタンスは、このソースと互換性がありません。
+ Jira Search API バージョン 3
+ `rest/api/3/search`
+ `rest/api/3/issue`
+ Confluence
+ `wiki/rest/api/content/search`
+ `wiki/rest/api/content`
+ `wiki/rest/api/settings/systemInfo`
## アトラシアンコネクタの CloudWatch のメトリクス
**タイプ: Jira コネクタメトリクス**
| ソース | メトリクス | メトリクスタイプ |
| --- | --- | --- |
| acknowledgementSetSuccesses.count | Counter | 確認が有効になっている場合、このメトリクスは正常に同期されたチケットの数を提供します。 |
| acknowledgementSetFailures.count | Counter | acknowledgments が有効になっている場合、このメトリクスは同期に失敗したチケットの数を提供します。 |
| crawlingTime.avg | Timer | すべての新しい変更をクロールするのにかかった時間。 |
| ticketFetchLatency.avg | Timer | チケットフェッチ API レイテンシーの平均。 |
| ticketFetchLatency.max | Timer | チケットフェッチ API の最大レイテンシー。 |
| ticketsRequested.count | Counter | チケットフェッチリクエストの数。 |
| ticketRequestedFailed.count | Counter | チケットフェッチリクエストの数が失敗しました。 |
| ticketRequestedSuccess.count | Counter | 成功したチケットフェッチリクエストの数。 |
| searchCallLatency.avg | Timer | API コールレイテンシーの平均を検索します。 |
| searchCallLatency.max | Timer | API コールの最大レイテンシーを検索します。 |
| searchResultsFound.count | Counter | 特定の検索呼び出しで見つかった項目の数。 |
| searchRequestFailed.count | Counter | 検索 API コールの失敗数。 |
| authFailures.count | Counter | 認証の失敗数。 |
**タイプ: Confluence コネクタメトリクス**
| ソース | メトリクス | メトリクスタイプ |
| --- | --- | --- |
| acknowledgementSetSuccesses.count | Counter | acknowledgments が有効になっている場合、このメトリクスは正常に同期されたページ数を提供します。 |
| acknowledgementSetFailures.count | Counter | acknowledgments が有効になっている場合、このメトリクスは同期に失敗したページ数を提供します。 |
| crawlingTime.avg | Timer | すべての新しい変更をクロールするのにかかった時間。 |
| pageFetchLatency.avg | Timer | API レイテンシー (平均) を取得するコンテンツ。 |
| pageFetchLatency.max | Timer | API レイテンシー (最大) を取得するコンテンツ。 |
| pagesRequested.count | Counter | コンテンツフェッチ API の呼び出しの数。 |
| pageRequestFailed.count | Counter | コンテンツフェッチ API の失敗したリクエストの数。 |
| pageRequestedSuccess.count | Counter | コンテンツフェッチ API の成功したリクエストの数。 |
| searchCallLatency.avg | Timer | API コールレイテンシーの平均を検索します。 |
| searchCallLatency.max | Timer | API コールの最大レイテンシーを検索します。 |
| searchResultsFound.count | Counter | 特定の検索呼び出しで見つかった項目の数。 |
| searchRequestsFailed.count | Counter | 検索 API コールの失敗数。 |
| authFailures.count | Counter | 認証の失敗数。 |