本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 搭配 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 索引保持up-to-date且全面。
整合提供靈活的篩選選項，可讓您選擇性地從特定空間或頁面類型匯入內容，根據組織的需求量身打造同步內容。外掛程式同時支援基本 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)
+ [適用於 Atlassian 連接器的 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)，以存放上一個步驟中建立的登入資料。遵循程序進行下列選擇：
+ 針對**機密類型**，選擇**其他類型的機密**。
+ 對於**鍵/值對**，根據您選取的授權類型建立下列對：
------
#### [ 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 Resource Name (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. **主機**：您的 Jira 雲端或內部部署 URL。一般而言，它看起來像 `https://{{your-domain-name}}.atlassian.net/`。
1. **確認：**保證將資料交付至目的地。
1. **身分驗證**：描述您希望管道如何存取 Jira 執行個體。選擇 `Basic`或 ，`OAuth2`並指定參考 AWS 秘密中金鑰的對應金鑰屬性。
1. **篩選條件**：本節可協助您選取要擷取和同步的 Jira 資料部分。
1. **專案**：在 `include`區段中列出您要同步的專案金鑰。否則，請在 `exclude`區段下列出您要排除的專案。在任何指定時間僅提供其中一個包含或排除選項。
1. **issue\_type**：您要同步的特定問題類型。遵循符合您需求的類似 `include`或 `exclude` 模式。請注意，附件會顯示為原始附件的錨點連結，但不會擷取附件內容。
1. **狀態**：您想要套用至資料擷取查詢的特定狀態篩選條件。如果您指定 `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. **主機**：您的 Confluence 雲端或內部部署 URL。一般而言，它看起來像 `https://{{your-domain-name}}.atlassian.net/`
1. **確認：**保證將資料交付至目的地。
1. **身分驗證**：描述您希望管道如何存取 Confluence 執行個體。選擇 `Basic`或 ，`OAuth2`並指定參考 AWS 秘密中金鑰的對應金鑰屬性。
1. **篩選條件**：本節可協助您選取要擷取和同步 Confluence 資料的哪個部分。
1. **space**：列出您要在 `include`區段中同步的空間鍵。否則，請在 `exclude`區段下列出您要排除的空格。在任何指定時間僅提供其中一個包含或排除選項。
1. **page\_type**：您想要同步的特定頁面類型 （例如頁面、部落格文章或附件）。遵循符合您需求的類似 `include`或 `exclude` 模式。請注意，附件會顯示為原始附件的錨點連結，但不會擷取附件內容。
## 資料一致性
根據管道 YAML 中指定的篩選條件，選取的專案 （或空格） 將擷取一次，並完全同步到目標目的地。然後，持續變更監控會在變更發生時擷取變更，並更新目的地中的資料。其中一個例外是變更監控只會同步 `create`和 `update`動作，而不是 `delete`動作。
## 限制
+ 使用者刪除動作不會同步。記錄在接收器中的資料會保留在接收器中。如果在接收器設定中指定 ID 映射，更新會以新的變更覆寫現有內容。
+ 使用舊版 Atlassian 軟體不支援下列 APIs 的現場部署執行個體與此來源不相容：
+ 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`
## 適用於 Atlassian 連接器的 CloudWatch 指標
**類型：Jira 連接器指標**
| 來源 | 指標 | 指標類型 |
| --- | --- | --- |
| acknowledgementSetSuccesses.count | 計數器 | 如果啟用確認，此指標會提供已成功同步的票證數量。 |
| acknowledgementSetFailures.count | 計數器 | 如果啟用確認，此指標會提供無法同步的票證數量。 |
| crawlingTime.avg | Timer | 爬取所有新變更所需的時間。 |
| ticketFetchLatency.avg | Timer | 票證擷取 API 延遲平均值。 |
| ticketFetchLatency.max | Timer | 票證擷取 API 延遲上限。 |
| ticketsRequested.count | 計數器 | 提出的票證擷取請求數量。 |
| ticketRequestedFailed.count | 計數器 | 票證擷取請求數目失敗。 |
| ticketRequestedSuccess.count | 計數器 | 票證擷取請求成功的數量。 |
| searchCallLatency.avg | Timer | 搜尋 API 呼叫延遲平均值。 |
| searchCallLatency.max | Timer | 搜尋 API 呼叫延遲上限。 |
| searchResultsFound.count | 計數器 | 在指定的搜尋呼叫中找到的項目數量。 |
| searchRequestFailed.count | 計數器 | 搜尋 API 呼叫失敗計數。 |
| authFailures.count | 計數器 | 身分驗證失敗計數。 |
**類型：Confluence 連接器指標**
| 來源 | 指標 | 指標類型 |
| --- | --- | --- |
| acknowledgementSetSuccesses.count | 計數器 | 如果啟用確認，此指標會提供已成功同步的頁面數。 |
| acknowledgementSetFailures.count | 計數器 | 如果啟用確認，此指標會提供無法同步的頁面數。 |
| crawlingTime.avg | Timer | 爬取所有新變更所需的時間。 |
| pageFetchLatency.avg | Timer | 內容擷取 API 延遲 （平均值）。 |
| pageFetchLatency.max | Timer | 內容擷取 API 延遲 （上限）。 |
| pagesRequested.count | 計數器 | 擷取 API 的內容叫用次數。 |
| pageRequestFailed.count | 計數器 | 內容擷取 API 的失敗請求數量。 |
| pageRequestedSuccess.count | 計數器 | 內容擷取 API 的成功請求數量。 |
| searchCallLatency.avg | Timer | 搜尋 API 呼叫延遲平均值。 |
| searchCallLatency.max | Timer | 搜尋 API 呼叫延遲上限。 |
| searchResultsFound.count | 計數器 | 在指定的搜尋呼叫中找到的項目數量。 |
| searchRequestsFailed.count | 計數器 | 搜尋 API 呼叫失敗計數。 |
| authFailures.count | 計數器 | 身分驗證失敗計數。 |