本頁面由 Cloud Translation API 翻譯而成。

Jira Cloud 設定

本頁說明如何設定及設定第三方設定，然後再建立 Jira Cloud 資料儲存庫。

設定驗證和權限

您需要在 Atlassian 管理員帳戶中心設定驗證和權限。這項步驟至關重要，因為連接器需要存取及同步處理資料。Jira Cloud 連接器支援多種驗證方法，例如 OAuth 用戶端憑證或 API 權杖。

建立 OAuth 2.0 應用程式

如要建立 OAuth 2.0 應用程式進行驗證，請按照下列步驟在 Atlassian 開發人員控制台中設定應用程式，並取得必要的用戶端 ID 和用戶端密鑰。

驗證 Jira 組織管理員存取權

如要驗證 Jira 組織管理員存取權，請按照下列步驟操作：

以使用者憑證登入 Atlassian。
選取「Jira」應用程式。
按一下「設定」。

如果「Jira settings」下方顯示「System」選項，表示您擁有「Jira 組織管理員」存取權，否則請要求 Jira 組織管理員授予存取權。

建立 OAuth 2.0 應用程式

如要建立 OAuth 2.0 應用程式，請按照下列步驟操作：

登入 Atlassian 開發人員控制台。
點按個人資料圖示，然後選取「Developer console」(開發人員控制台)。
在「Console」(控制台) 頁面中，按一下「Create」(建立)，然後選取「OAuth 2.0 Integration」(OAuth 2.0 整合作業)。
在應用程式建立頁面中，執行下列操作：
1. 輸入應用程式名稱。
2. 勾選核取方塊，同意 Atlassian 的開發人員條款。
3. 點選「建立」。
在應用程式頁面中，執行下列操作：
1. 按一下導覽選單中的「授權」。
2. 在「Authorization type」(授權類型) 表格中找到「OAuth 2.0 (3LO)」，然後點按旁邊的「Add」(新增)。
在「Callback URL」(回呼網址) 欄位中，輸入 https://vertexaisearch.cloud.google.com/console/oauth/jira_oauth.html。
按一下 [儲存變更]。

取得用戶端 ID 和用戶端密鑰

按照下列步驟操作，取得用戶端 ID 和用戶端密鑰：

在應用程式頁面中，按一下導覽選單中的「發布」。
在「發布」頁面中，執行下列操作：
1. 在「發布控制選項」部分，選取「編輯」。
2. 在「發布狀態」部分，選取「共用」可編輯其他欄位。
3. 在下列必填欄位中輸入資訊：
  1. 在「Vendor」(供應商) 中輸入 Google。
  2. 在「Privacy policy」(隱私權政策) 中輸入 https://policies.google.com。
  3. 在「Does your app store personal data?」(您的應用程式是否會儲存個人資料？) 中，選取「Yes」(是)。
  4. 選取「I confirm that I've implemented the personal data reporting API」(我確認已導入 Personal data reporting API) 核取方塊。詳情請參閱「Personal data reporting API」。
4. 按一下 [儲存變更]。
在應用程式頁面中，執行下列操作：
1. 按一下導覽選單中的「設定」。
2. 在設定頁面中，複製「Client ID」(用戶端 ID) 和「Client secret」(用戶端密鑰)。

取得執行個體 ID 和執行個體網址

取得執行個體 ID：
1. 開啟新分頁並複製執行個體網址，然後在該網址後方附加 /_edge/tenant_info，例如：https://YOUR_INSTANCE.atlassian.net/_edge/tenant_info。
2. 開啟連結並找到 cloudId 值，cloudId 即為執行個體 ID。
取得執行個體網址：
1. 前往 atlassian.net，然後使用「管理員」帳戶登入。
2. 選取您要同步處理的應用程式，例如同步處理第一個應用程式。
3. 找到執行個體網址 (網址列中的子網域)。

授予管理員角色

按照下列步驟操作，在 Google Cloud 控制台授予 Jira「管理員」Discovery Engine 編輯者角色：

前往 Google Cloud 控制台的「Gemini Enterprise」頁面。
前往「IAM」IAM。

前往「IAM」(身分與存取權管理) 頁面
找出具有 Jira「管理員」存取權的使用者帳戶，然後點選「Edit」(編輯) 圖示。
授予「管理員」Discovery Engine 編輯者角色。

按照下列步驟操作，授予使用者 Atlassian「管理員」角色：

使用「組織管理員」帳戶登入 Atlassian。
按一下選單圖示，然後選取您的組織，或者您也可以前往 admin.atlassian.com。
在「Admin」(管理) 頁面中，點按產品並選取「Manage users」(管理使用者) 按鈕。

管理使用者
點按「User management」(使用者管理) 底下的「Groups」(群組)。
在「Groups」(群組) 頁面中：
1. 按一下 [建立群組]。
2. 輸入群組名稱。
建立群組

這個群組會獲得連接器所需的權限。新加入這個群組的使用者會繼承這些權限。連接器也會使用這個群組進行驗證及擷取文件。

在「群組」頁面中，點按「新增產品」。
將「Jira」的角色設為「User access admin」(使用者存取權管理員)。
將「Jira administration」(Jira 管理) 的角色設為「Product admin」(產品管理員)。

Jira 使用者存取權管理員
點選「授予存取權」。
點按「Add group members」(新增群組成員) 並新增使用者帳戶或群組成員，連接器會使用這兩項資訊來驗證及存取必要資源。

新增群組成員

管理使用者瀏覽權限

如要讓 Atlassian 帳戶中的所有人都能看到使用者的電子郵件地址，請按照下列步驟操作：

登入 Atlassian 開發人員控制台。
點按個人資料圖示，然後選取「Developer console」(開發人員控制台)。
依序點按使用者個人資料圖示和「Manage Account」(管理帳戶)。

管理帳戶
前往「Profile and visibility」(個人資料和瀏覽權限) 分頁。

個人資料和瀏覽權限
前往「Contact」(聯絡人) 區段，將「Who can see this」(誰可以查看這項資訊) 設為「Anyone」(任何人)。

聯絡人

如要讓 Jira 中的所有人都能看到使用者的電子郵件地址，請按照下列步驟操作：

以您的使用者憑證登入 Atlassian。
選取 Jira 應用程式。
依序點選「Settings」(設定) >「System」(系統)。
在左窗格中選取「General Configuration」(一般設定)。
點按「Edit Settings」(編輯設定)。
在「User email visibility」(使用者電子郵件瀏覽權限) 部分，選取「Public」(公開)。

選取電子郵件瀏覽權限
按一下「Update」。

設定應用程式範圍下限

如要執行定義的動作，您需要在 Atlassian 平台中，為 Jira Cloud 連接器設定下列權限。

在應用程式頁面中，點按「Permissions」(權限)。
找到「Jira API」並點按「Add」(新增)。

注意： 新增 Jira API 後，「Configure」(設定) 按鈕可能需要一段時間才會顯示。如果沒有立即顯示，請嘗試重新整理頁面或稍候幾秒。
按一下 [設定]。
前往「Classic scopes」(傳統範圍) 分頁。
點按「Edit scopes」(編輯範圍)，然後從下表中選取符合需求的傳統範圍：

連線模式	權限	目的
聯合搜尋和動作	`read:jira-user`、`read:jira-work`	必須使用這項權限，才能即時擷取及顯示搜尋結果和使用者詳細資料。
聯合搜尋和動作	`write:jira-work`	允許助理修改工作項目 (例如更新問題欄位)，以及管理留言或問題。
僅限聯盟搜尋	`read:jira-user`、`read:jira-work`	必須具備這項權限，才能搜尋及查看問題、專案和使用者設定檔。
資料擷取和動作	`read:jira-work`	如要廣泛檢索及索引工作項目資料，就必須提供這項權限。
資料擷取和動作	`write:jira-work`	必須在擷取環境中對工作項目執行寫入動作 (建立、更新、留言)。
資料擷取	`read:jira-work`	必須檢索 Jira 內容並建立索引，才能提供搜尋功能。

確認已選取所有範圍，然後按一下「儲存」。
前往「Granular scopes」(精細範圍) 分頁。
點按「Edit scopes」(編輯範圍)，然後從下表選取所需精細範圍：

連線模式	權限	目的
聯合搜尋和動作	`write:comment:jira`	讓助理直接透過搜尋介面發布新留言或回覆。
聯合搜尋和動作	`write:issue:jira`	建立新問題或對現有問題進行重大編輯時，必須具備這項權限。
資料擷取和動作	`read:user:jira`、`read:group:jira`、`read:avatar:jira`	同步處理使用者/群組中繼資料及顯示使用者設定檔時，必須提供這項資訊。
	`read:issue-security-level:jira`、`read:issue-security-scheme:jira`	存取控管的關鍵，可確保擷取的資料遵守 Jira 的安全界線。
	`read:audit-log:jira`	用於追蹤變更及執行增量同步，確保擷取的資料為最新狀態。
	`write:comment:jira`	使用助理在問題中新增留言時，必須提供留言。
	`write:issue:jira`	可建立或修改問題。
資料擷取	`read:user:jira`、`read:group:jira`、`read:avatar:jira`	檢索 Jira 內容和使用者關係並建立索引時，必須使用此權限。
	`read:issue-security-level:jira`、`read:issue-security-scheme:jira`	必須對應權限，確保只有授權使用者可以搜尋擷取的資料。
	`read:audit-log:jira`	同步引擎必須使用這項資訊，才能判斷哪些項目已更新或刪除。

確認已選取所有範圍，然後按一下「儲存」。

安裝 User Identity Accessor

按照下列步驟操作，在 Jira Cloud 網站上安裝 User Identity Accessor for Jira Cloud 應用程式：

前往 Atlassian 開發人員控制台。
檢查「Read Email Address」(讀取電子郵件地址) 和「App Storage scope」(應用程式儲存空間範圍) 權限，然後點按「Get app」(取得應用程式)。

檢查權限並取得應用程式
在「Select a site to install this app on」清單中，選取要安裝應用程式的 Jira 網站。這個清單只會顯示您具有「管理員」存取權的網站。

注意： 您必須是至少一個 Jira 網站的「管理員」，才能安裝應用程式。
點按「Install」(安裝) 來完成應用程式安裝程序。

設定 User Identity Accessor

安裝 User Identity Accessor for Jira Cloud 應用程式後，請設定 API 金鑰，供外部系統 (例如 Jira Cloud 連接器) 安全地呼叫應用程式的網頁觸發條件，以擷取電子郵件。

前往設定頁面

如要存取 User Identity Accessor for Jira Cloud 應用程式的設定頁面，請執行下列步驟：

在 Jira Cloud 執行個體中，點按導覽選單中的「Setting」(設定) ⚙️ 圖示。
從選單中選取「Apps」(應用程式)。
在「Apps administration」(應用程式管理) 頁面的「Manage apps」(管理應用程式) 清單中，找到應用程式「User Identity Accessor for Jira Cloud」。
點按「Configure」(設定) 或與應用程式相關聯的連結，Jira Cloud 會開啟應用程式的專屬設定頁面。

設定 User Identity Accessor for Jira Cloud 應用程式

設定 API 金鑰

如要在設定頁面設定 API 金鑰，請按照下列步驟操作：

在「API Key Configuration」(API 金鑰設定) 部分指定密鑰，驗證傳送至應用程式網頁觸發條件的要求。您可以使用下列任一方法驗證要求：
- 輸入自己的金鑰：在「API Key」(API 金鑰) 欄位中，輸入或貼上自己專用的高強度 API 金鑰。金鑰的字元數必須至少為 20 至 30 個字元，並混合使用大寫與小寫英文字母、數字和符號。
  
  輸入自己的金鑰
- 產生金鑰：點按「Generate New Key」(產生新金鑰) 按鈕，系統會在欄位中產生並顯示隨機的高強度金鑰。
  
  產生金鑰
  
  注意：請立即複製欄位中顯示的 API 金鑰。基於安全考量，儲存或離開頁面後，您可能無法再次查看完整金鑰；如果遺失，請設定或產生一組新金鑰。
點按「Save API Key」(儲存 API 金鑰)。畫面上會顯示一則成功訊息，確認金鑰已安全儲存。

備註：本節中產生或建立的 API 金鑰，會在設定連接器期間，做為「Advanced Options」(進階選項) 部分中「Jira Identity Sync Forge Client Secret」(Jira Identity Sync Forge 用戶端密鑰) 欄位的值。

測試應用程式設定

從外部系統傳送要求，確認使用者電子郵件地址是否順利傳回，藉此驗證 User Identity Accessor for Jira Cloud 是否正確設定。

取得網頁觸發條件網址

在「Apps administration」(應用程式管理) 頁面中找到「Webtrigger URL」(網頁觸發條件網址) 區段，當中會顯示 Jira 網站和這個應用程式安裝作業專用的網址：
- 外部系統必須呼叫這個網址，才能要求擷取使用者電子郵件地址。
- 網址範例：https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/WEBTRIGGER_ID，其中 YOUR_INSTANCE_ID 是 Jira Cloud 執行個體 ID，WEBTRIGGER_ID 則是為應用程式產生的網頁觸發條件端點專屬 ID。
點按「Copy URL」(複製網址) 按鈕，或複製整個網址。

設定外部系統

設定外部系統，此外部系統需要使用在上一個步驟中取得的 API 金鑰和網頁觸發條件網址，擷取 Jira 使用者電子郵件地址。
端點網址：您複製的網頁觸發條件網址。
HTTP 方法：POST
必要標頭：
- Content-Type：application/json
- X-Api-Key：YOUR_API_KEY
  
  將 YOUR_API_KEY 替換為您在設定 API 金鑰一節中設定或產生的 API 金鑰。

cURL 指令範例

下方示範如何呼叫 User Identity Accessor for Jira Cloud 網頁觸發條件，以接收帳戶 ID 陣列並傳回電子郵件地址。

curl --location --request POST 'https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/ENDPOINT_PATH' \
--header 'X-Api-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
   "accountIds": [
       "ACCOUNT_ID_1",
       "ACCOUNT_ID_2"
   ]
}'

取代：

YOUR_INSTANCE_ID 替換成您的 Jira Cloud 執行個體 ID
將 ENDPOINT_PATH 替換成 API 端點路徑
將 YOUR_API_KEY 替換成您在設定 API 金鑰一節中設定或產生的 API 金鑰
將 ACCOUNT_ID 替換成您要指定的 Atlassian 帳戶 ID

預期的回覆

[{"accountId":"ACCOUNT_ID_1","emailAddress":"EMAIL_ADDRESS_1"},
 {"accountId":"ACCOUNT_ID_2","emailAddress":"EMAIL_ADDRESS_2"}]

取代：

將 ACCOUNT_ID_X 替換成實際的 Atlassian 帳戶 ID
將 USER_EMAIL_X 替換成 API 呼叫傳回的使用者電子郵件地址

實作安全性最佳做法

遵循以下建議，有助於確認 API 金鑰的安全性：

在 Jira Cloud 連接器的設定中安全地儲存 API 金鑰。
確認與 Webhook 網址的所有通訊都是透過 HTTPS 進行，這是 User Identity Accessor for Jira Cloud 網頁觸發條件的預設值。

User Identity Accessor for Jira Cloud 相關支援

Google 提供 User Identity Accessor for Jira Cloud 應用程式的支援方案，其中包括維護和定期更新服務，可確保應用程式隨時為最新狀態。如果遇到任何問題，或對應用程式功能有疑問，請與 Google Cloud 支援團隊聯絡。詳情請參閱「取得 Cloud Customer Care 服務」。

Jira Cloud 設定 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

設定驗證和權限

建立 OAuth 2.0 應用程式

驗證 Jira 組織管理員存取權

建立 OAuth 2.0 應用程式

取得用戶端 ID 和用戶端密鑰

取得執行個體 ID 和執行個體網址

授予管理員角色

管理使用者瀏覽權限

設定應用程式範圍下限

安裝 User Identity Accessor

設定 User Identity Accessor

前往設定頁面

設定 API 金鑰

測試應用程式設定

取得網頁觸發條件網址

設定外部系統

cURL 指令範例

預期的回覆

實作安全性最佳做法

User Identity Accessor for Jira Cloud 相關支援

Jira Cloud 設定