對應 ACL

為確保只有具備項目存取權的使用者才能在搜尋結果中查看該項目，您應使用企業存放區中的存取控制清單 (ACL) 為項目建立索引。您必須模擬存放區的 ACL，並在索引存放區中的項目時納入這些 ACL。Content Connector SDK 提供豐富的 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 的使用者。ACL 類別中還有其他幾個用於建構 Principal 物件的靜態方法。

ACL 繼承

ACL 繼承是指針對特定項目和使用者，根據項目的 ACL 和繼承鏈結的 ACL 組合結果所授予的授權。用於做出授權決定的規則取決於存放區和項目的屬性。

設定繼承

每個項目都可以有直接允許的主體和直接拒絕的主體，可使用 setReaders() 和 setDeniedReaders() 方法指定。直接允許的使用者是指在 ACL 中識別的使用者，可讓他們直接存取特定項目。直接拒絕的使用者是指在 ACL 中被識別為無法存取特定項目的使用者。

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

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

繪製項目之間的連結
圖 1. setInheritFrom() 方法。

這些存取控制項如圖 1 所示：

  • 使用者 1 是項目 A 的直接許可實體。
  • 使用者 2 是項目 B 的直接許可實體。
  • 項目 B 會繼承項目 A 的 ACL。

根據存取控管，存取規則如下：

  • 使用者 1 不必明確指定為項目 B 的使用者，才能成為項目 B 的間接許可使用者；因為使用者 1 已列為項目 A 的直接許可使用者，而項目 B 會從項目 A 繼承 ACL，因此存取權會繼承。
  • 使用者 2 不是項目 A 的間接許可使用者。

設定繼承類型

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

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

  • CHILD_OVERRIDE：將繼承類型設為 CHILD_OVERRIDE，強制子項 ACL 在與繼承父項 ACL 發生衝突時優先使用。因此，如果父項的 ACL 拒絕使用者以讀取者身分存取，只要使用者以讀取者身分存取子項，仍可存取該項。相反地，即使父項的 ACL 授予使用者存取權，如果使用者是子項的讀取權限遭拒，仍無法存取。

  • PARENT_OVERRIDE：將繼承類型設為 PARENT_OVERRIDE，即可在子項 ACL 與父項 ACL 發生衝突時，強制以父項 ACL 為優先。因此，如果子項的 ACL 拒絕使用者以讀取者身分存取，只要使用者以讀取者身分存取父項，仍可存取該項。相反地，即使子項的 ACL 授予使用者存取權，如果使用者是父項的讀取權遭拒，仍無法存取。

評估 ACL 繼承鏈結時，評估順序可能會影響授權決定的結果。Cloud Search 會為 ACL 繼承鏈結提供葉子到根的評估順序。具體來說，鏈結的 ACL 決定會從評估子項及其父項開始，並可一直進展到根父項。

舉例來說，如果子資料夾屬於 CHILD_OVERRIDE 繼承類型，且使用者有權存取子資料夾，Drive 就不需要評估父資料夾。不過，如果子項有 PARENT_OVERRIDE 或 BOTH_PERMIT，Drive 會繼續評估上層鏈結的繼承。

隔離和刪除項目

為項目建立索引時，您可以使用 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。