對應 ACL

為確保只有具備項目存取權的使用者能看到搜尋結果的項目，建議您使用企業存放區的存取控制清單 (ACL) 為項目建立索引。您必須建立存放區的 ACL 模型，並在為存放區中的項目建立索引時加入這些 ACL。內容連接器 SDK 提供一套豐富的 ACL 方法，足以建立大多數存放區的 ACL。

注意： 內容連接器 SDK 支援單一網域 ACL，但不支援跨網域 ACL。您無法對機構外的任何使用者和群組授予存取權。凡是參照貴機構外使用者或群組的 ACL 都不會有任何作用。

建立 ACL

建立 ACL 的程序分為兩個步驟：

1. 在 ACL 類別中使用靜態方法建立 Principal。
2. 使用 Acl.Builder 類別來使用主體建構 ACL。

本文件的其餘部分說明建立模型和建立 ACL 需要瞭解的一些概念，例如繼承和包含政策。

使用外部 ID 建立主體

Google Cloud Search 要求使用者和群組必須解析為 Google 電子郵件地址。為存放區項目建立索引時，內容連接器可能沒有這些電子郵件地址。不過，Content Connector SDK 可讓您使用任何外部 ID (此 ID 向使用者或群組授予存放區項目的存取權)，而非電子郵件地址來為項目建立索引。使用 getUserPrincipal() 方法或 getGroupPrincpal() 方法，建立包含外部 ID 的主體。用於建構 Principal 物件的 ACL 類別還提供其他幾個靜態方法。

注意： 使用者必須讓外部 ID 與使用者 Google 帳戶保持同步，才會在搜尋結果中看到項目。使用識別資訊提供者將這些外部使用者或群組 ID 同步處理至 Google 電子郵件地址。如要進一步瞭解識別資訊連接器，請參閱「建立識別資訊連接器」。

警告： 將項目的身分重新對應至其他身分後，您必須重新為項目建立索引，新身分才能保留新身分。詳情請參閱重新對應身分。

ACL 繼承

ACL 繼承是指特定項目和特定使用者的授權，取決於該項目的 ACL 及其繼承鏈結的 ACL 的結果。用於做出授權決策的規則取決於存放區和項目的屬性。

設定繼承

每個項目都可以包含直接允許的主體和直接遭拒的主體，使用 setReaders() 和 setDeniedReaders() 方法加以指定。直接允許的主體是在 ACL 中識別的使用者，能夠直接存取特定項目。直接遭拒的主體是在 ACL 中識別出無法存取特定項目的使用者。

項目也可以使用 setInheritFrom() 方法繼承間接允許的主體和間接遭拒的主體。間接允許的主體是指透過 ACL 繼承而擁有特定項目的間接存取權的使用者。間接拒絕主體是指透過 ACL 繼承而拒絕存取特定項目的使用者。

注意： 如果您使用 setInheritFrom() 方法設定繼承類型，就必須使用 setInheritanceType() 方法設定繼承類型。如要進一步瞭解繼承類型，請參閱「設定繼承類型」一文。

圖 1 顯示如何使用 setInheritFrom() 方法繼承允許間接和間接遭拒的主體。

圖 1. setInheritFrom() 方法。

這些存取權控管如圖 1 所示：

• 使用者 1 是商品 A 的直接主體。
• 使用者 2 是項目 B 的直接主體。
• 項目 B 會繼承項目 A 的 ACL。

根據存取權控管設定，存取規則為：

• 使用者 1 不需要明確指定為項目 B 的間接允許的主體；由於使用者 1 列為項目的直接允許主體，而項目 B 繼承了項目 A 的 ACL，因此該使用者 1 不需要明確指定為項目 B 的主體。
• 使用者 2 並非允許間接套用至項目 A 的主體。

設定繼承類型

如果您使用 setInheritFrom() 方法設定繼承類型，就必須使用 setInheritanceType() 方法設定繼承類型。繼承類型可決定子項 ACL 與父項 ACL 結合的方式。Acl.InheritanceType 會實作三種繼承類型：

• BOTH_PERMIT - 只有在子項項目的 ACL 和父項的沿用項目 ACL 都允許使用者存取該項目時，才將沿用類型設為 BOTH_PERMIT，以授予使用者該項目的存取權。

• CHILD_OVERRIDE - 將沿用類型設為 CHILD_OVERRIDE，強制在子項項目的 ACL 發生衝突時，優先於繼承父項項目的 ACL。因此，如果父項項目的 ACL 拒絕使用者做為拒絕讀取者的存取者，則即使他們以讀取者的身分存取子項項目，則使用者仍具有存取權。反之，如果使用者是子項遭拒的讀取者，即使父項項目的 ACL 將存取權授予使用者，則無法存取該名使用者。

• PARENT_OVERRIDE - 將繼承類型設為 PARENT_OVERRIDE，強制父項項目的 ACL 在子項項目的 ACL 發生衝突時優先。因此，如果子項項目的 ACL 拒絕以拒絕讀取者的身分存取使用者，則即使他們以讀取者的身分存取該父項項目，使用者仍具有存取權。反之，如果子項項目的 ACL 授予使用者存取權，即便使用者是父項項目的讀取遭拒，使用者也無法存取該父項項目。

在評估 ACL 繼承鏈結時，評估順序可能會變更授權決策的結果。Cloud Search 可為 ACL 繼承鏈結提供分葉到根層級的評估順序。具體來說，鏈結的 ACL 決策需要從對子項父項的評估開始，然後一路到根父項。

舉例來說，如果子項具有 CHILD_OVERRIDE 繼承類型，而使用者可以存取該子項，則雲端硬碟就無須評估父項。但是，如果子項擁有 PARENT_OVERRIDE 或 BOTH_PERMIT，則雲端硬碟會繼續評估鏈結的繼承情況。

包含和刪除項目

為項目建立索引時，您可以使用 IndexingItemBuilder 類別的 setContainer() 方法，將項目標示為容器。容器/與關係關係會建立項目的實體階層，並確保項目正確刪除。刪除容器時，包含的項目也會一併刪除。

隔離關係與 ACL 繼承規則完全無關。舉例來說，檔案系統中的檔案可以存放於資料夾內，以供刪除，但繼承其他資料夾的 ACL。刪除資料夾並不會刪除繼承其 ACL 的項目，除非這些項目亦位於資料夾的包含階層中。

這些存取權控管如圖 2 所示：

• 使用者 1 是商品 A 的直接主體。
• 使用者 2 是項目 B 的直接主體。
• 使用者 3 是項目 C 的直接主體。
• 項目 C 會繼承項目 A 的 ACL。
• 商品 B 將項目 A 命名為容器。
• 項目 C 將項目 B 命名為容器。

根據存取權控管設定，存取規則為：

• 間接存取是使用 setInheritFrom() 方法。因此，使用者 1 可以存取項目 C，因為項目 C 會繼承項目 A 的 ACL。
• 間接存取「不」來自項目 B 包含的項目 C。 因此，使用者 2 無法存取項目 C。

圖 2.使用中的 setInheritFrom() 方法。

分隔 ACL 繼承與涵蓋階層的方式可讓您建立許多不同的現有結構的模型。

成功刪除項目後：

• 凡是包含遭刪除項目的項目，都無法搜尋，並已安排從 Google 的資料來源刪除。
• 凡是使用 setInheritFrom() 方法指定刪除項目的項目都無法搜尋。

如果資源已使用 setInheritFrom() 方法刪除已刪除的項目，但沒有使用 setContainer() 的容器集，或者其內含階層不含任何已刪除項目，該項目及其資料會保留在 Google 的資料來源中。您必須負責刪除這個項目。

圖 3 範例說明商品階層的刪除作業運作方式。

圖 3. 刪除項目和 ACL 繼承。

這些存取權控管如圖 3 所示：

• 使用者 1 是商品 A 的直接主體。
• 使用者 2 是項目 D 的直接主體。
• 項目 D 和項目 E 都會沿用項目 A 的 ACL。
• 項目 D 將項目 A 命名為其容器。
• 項目 A 和 E 是根層級項目，因為這些項目沒有容器項目。

透過容器參照刪除。刪除項目 A 後：

• setInheritFrom() 參照的所有子係都會失去所有使用者的存取權。
• 所有使用者皆無法存取項目 A。
• 項目 D 會以隱含方式刪除。所有使用者皆無法存取項目 D。
• 項目 E 不會刪除，因為刪除作業只會透過容器參照階層串聯。
• 無法連上 E 項目，且所有使用者無法搜尋項目 E。