本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 文件層級存取控制
<a name="confluence-kb-acl"></a>

Confluence Cloud 知識庫可選擇性支援文件層級存取控制。啟用時，Amazon Quick 會在每個網路爬取期間同步 Confluence 的存取控制清單 (ACLs)，並在查詢時驗證每個使用者的許可。使用者只會看到他們獲授權在 Confluence 中存取之文件的答案。

## 運作方式
<a name="confluence-kb-acl-how-it-works"></a>

當使用者查詢使用 Confluence 知識庫並啟用 ACL 管理的 Amazon Quick 代理程式時，系統會分兩個階段強制執行存取控制：

1. **擷取前篩選** – Amazon Quick 會對向量索引執行語意搜尋，以尋找最相關的文件段落。系統會套用上次爬蟲期間從 Confluence 同步的存取控制清單。這會產生一組初步的候選文件。

1. **即時驗證** – 系統會檢查使用者目前在 Confluence 中的存取權，以即時驗證候選文件。只有使用者目前獲授權存取的文件才會出現在回應中。

這種兩階段方法提供文件層級的存取控制，即使 Confluence 許可在同步之間變更，也能保持最新狀態。

Amazon Quick 會編目下列 Confluence ACL 資源：
+ **空間** – 根據預設，空間許可會套用至空間中的所有文件。
+ **頁面** – 頁面可以限制為特定使用者和群組。巢狀頁面會從父頁面繼承限制，並且可以有自己的限制。
+ **部落格** – 部落格文章可以限制為空間中的特定使用者和群組。
+ **附件** – 連接至頁面或部落格文章的檔案會繼承其父文件的存取控制。

## 啟用 ACL 管理
<a name="confluence-kb-acl-enable"></a>

您可以在其他設定步驟中的知識庫建立期間**設定** ACL 管理。選取**使用 ACLs控制文件存取**核取方塊以啟用它。此選項需要您在**身分驗證方法**步驟期間提供的 Atlassian 管理員登入資料。如果沒有管理員登入資料，則會停用 ACL 選項。

**重要**  
您無法在建立知識庫後變更 ACL 管理。如果您需要變更此設定，您必須建立新的知識庫。

Atlassian 管理員登入資料可讓 Amazon Quick 從 Confluence 執行個體存取所有使用者和群組資訊，無論個別電子郵件可見性設定為何。如需從您的 Atlassian 組織取得管理員登入資料的步驟，請參閱 [取得 Atlassian 管理員登入資料](#confluence-kb-atlassian-admin-credentials)。如需知識庫設定步驟，請參閱 [驗證您的帳戶](confluence-knowledge-base.md#confluence-kb-setup-auth)。

如需 ACL 最佳實務的詳細資訊，請參閱 [在知識庫中管理 ACLs最佳實務](acl-best-practices-kb.md)。

## 即時存取驗證
<a name="confluence-kb-acl-realtime"></a>

當使用者提交的查詢涉及來自啟用 ACL 的 Confluence 知識庫的內容時，Amazon Quick 會即時驗證使用者的存取權：

1. 使用者在快速聊天助理中提出問題。

1. 如果答案涉及啟用 ACL 知識庫的 Confluence 內容， 會快速提示使用者登入 Confluence。

1. 使用者使用 Confluence 電子郵件和密碼登入，並接受授權對話方塊。

1. Quick 使用使用者的登入資料，根據 Confluence API 即時驗證每個候選文件的存取權。

1. 回應中只會顯示使用者目前在 Confluence 中可存取的文件。

登入是一次性步驟。登入後，在使用者工作階段過期之前，不會再次提示使用者。

**注意**  
如果即時許可驗證失敗 （例如，如果 Confluence API 暫時無法使用），使用者會看到錯誤訊息，提示他們重試。Amazon Quick 不會回到快取的許可 — 即時驗證是必要的，以確保存取控制的準確性。

## 取得 Atlassian 管理員登入資料
<a name="confluence-kb-atlassian-admin-credentials"></a>

若要在 Confluence 知識庫設定期間提供 Atlassian 管理員登入資料，您的 Atlassian 組織管理員必須完成下列步驟。

### 取得您的 API 金鑰和組織 ID
<a name="confluence-kb-admin-api-key"></a>

1. 使用管理員許可登入 [Atlassian 管理員入口網站](https://admin.atlassian.com/)。

1. 開啟您組織的 Administration 應用程式。URL 看起來應該如下：`https://admin.atlassian.com/o/{{ORGANIZATION-UUID}}/overview`。

1. 從 URL 複製**組織 ID**。

1. 選擇**設定**，然後選擇 **API 金鑰**。

1. 選擇**建立 API 金鑰**。

1. 選取 API 金鑰的下列範圍：
   + `read:directories:admin`
   + `read:workspaces:admin`

1. 複製並儲存**組織 ID** 與 **API 金鑰**。
**注意**  
API 金鑰過期。請監控其有效期限，並在金鑰到期前更新資料來源憑證。

### 取得您的 Directory ID
<a name="confluence-kb-admin-directory-id"></a>

使用 Atlassian Admin Workspace API 擷取您的目錄 ID。

1. 執行下列命令，將 {{ORGANIZATION-ID}} 取代為您的組織 ID，並將 {{API-KEY}} 取代為您的 API 金鑰：

   ```
   curl --request POST \
     --url 'https://api.atlassian.com/admin/v2/orgs/{{ORGANIZATION-ID}}/workspaces' \
     --header 'Authorization: Bearer {{API-KEY}}' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
       "query": {
         "field": {
           "name": "attributes.type",
           "values": ["confluence"]
         }
       },
       "limit": 20
     }'
   ```

   此查詢只會篩選 Confluence 工作區的結果，因此您不需要分頁所有工作區類型。

1. 在 API 回應中尋找與您的 Confluence 雲端版執行個體相符的 workspace 項目。確認工作區名稱與您的執行個體相符。

1. 從 `attributes`區段複製 `directory`值。這是您的**目錄 ID**。

如需 Atlassian 管理員 API 範圍的詳細資訊，請參閱 [Atlassian API 範圍文件](https://developer.atlassian.com/cloud/admin/scopes/)。如需 API 詳細資訊，請參閱 [Atlassian Admin Workspace API 參考](https://developer.atlassian.com/cloud/admin/organization/rest/api-group-workspaces/#api-group-workspaces)。

## 限制
<a name="confluence-kb-acl-limitations"></a>
+ **需要 Atlassian 管理員登入**資料 – 文件層級存取控制需要 Atlassian 管理員登入資料，這些登入資料必須在知識庫設定期間提供。您無法在沒有管理員登入資料的情況下啟用 ACLs，也無法在建立知識庫後新增管理員登入資料。
+ **即時驗證是強制性**的 – Amazon Quick 一律會在查詢時間對啟用 ACL 的知識庫執行即時許可檢查。如果 Confluence API 無法使用，涉及 ACL 保護內容的查詢會傳回錯誤，而不是返回快取的許可。

如需一般 ACL 限制和最佳實務，包括 ACL 永久性、研究相容性和電子郵件地址管理，請參閱 [在知識庫中管理 ACLs最佳實務](acl-best-practices-kb.md)。

## 後續步驟
<a name="confluence-kb-acl-next-steps"></a>

若要驗證文件層級存取控制並疑難排解許可問題，請參閱 [檢查文件存取 (ACL 驗證）](sync-reports-observability.md#sync-reports-acl-verification)。如需設定 Confluence 知識庫整合的資訊，請參閱 [設定知識庫整合](confluence-knowledge-base.md#confluence-kb-setup)。