排解 GCDS 常見問題

排解使用「設定管理員」時出現的設定問題

如果無法順利執行同步處理作業，請確認「設定管理員」內的設定資訊正確無誤，並記下無法通過的測試有哪些：

1. 在「設定管理員」中開啟要用來設定同步處理作業的 XML 檔案。
2. 在「LDAP 連線」頁面中按一下「測試連線」，確認您可連線至 LDAP 伺服器。
3. 在「通知」頁面中按一下「測試通知」，確認您可以傳送測試通知。
4. 在「同步處理」頁面中按一下「模擬同步處理」，確認您已填妥所有必填欄位且同步作業已開始執行。

如何針對 API 要求啟用完整的 HTTP 記錄？

在極少數的情況下，支援團隊可能會要求您除了在 GCDS 啟用追蹤層級的記錄外，另外啟用完整的 HTTP 記錄。您可以使用完整的 HTTP 記錄查看 GCDS 所提出的 API 請求，以及 Google API 所提供的回應。

重要事項：完整的 HTTP 記錄可能包含高度機密資訊。請務必先移除所有機密資訊 (例如現有的 refresh_token 或 access_token 欄位)，再將記錄傳送給支援團隊。

如何啟用完整的 HTTP 記錄：

1. 確認 GCDS 並未與 sync-cmd 或「設定管理員」同時運作。
2. 前往 GCDS 安裝資料夾。

3. 編輯 jre/lib/logging.properties 檔案。

4. 在檔案最後加入以下幾行內容：

   java.util.logging.FileHandler.pattern = %h/gcdshttp%u.%g.log
   java.util.logging.FileHandler.limit = 5000000
   java.util.logging.FileHandler.count = 100
   java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
   handlers = java.util.logging.FileHandler
   com.google.api.client.http.level = CONFIG
   
   com.google.gdata.client.http.HttpGDataRequest.level = ALL
   sun.net.www.protocol.http.HttpURLConnection.level = ALL

5. 儲存檔案。
6. 執行另一項 GCDS 同步處理作業 (記錄設定為「追蹤」)。

   系統隨即會在 homedir (Linux) 或設定檔資料夾 (Microsoft Windows) 中建立名為 gcdshttp*.log 的記錄檔。這些檔案相當龐大，因此請一併封存。

7. 刪除步驟 4 中所加入的各行內容，以免系統日後建立過大的記錄檔。
8. 將下列檔案提供給支援團隊：
   • XML 檔案
   • 追蹤層級記錄和最近一次同步處理的 gcdshttp*.log 檔案

提示：如要為新類別啟用記錄功能，請以 class.fqdn.level = ALL 形式附加一行，不必複製整個設定區塊。

使用偵錯 Proxy

記錄的要求和回應內文的大小上限皆為 16 KB。如果您看到因超過此上限而遭截斷的記錄項目，請使用偵錯 Proxy，例如 Fiddler。

如要啟用 Fiddler，請按照下列步驟操作：

1. 前往 GCDS 安裝路徑，例如 C:\Program Files\Google Cloud Directory Sync。
2. 在 .vmoptions 檔案 (例如 config-manager.vmoptions 或 sync-cmd.vmoptions) 中新增下列標記，即可關閉憑證撤銷清單檢查功能：

   -Dcom.sun.security.enableCRLDP=false

   -Dcom.sun.net.ssl.checkRevocation=false

重新啟動 GCDS，變更才會生效。

1. 在 Google 網域設定的 Proxy 設定中，將 Fiddler 設為 Proxy。在主機名稱欄位中，新增本機 IP 位址 127.0.0.1。預設通訊埠為 8888，但您可以開啟 Fiddler，依序前往「Options」>「Connections」，然後查看「Fiddler Classiclistens on port」欄位中的值，確認通訊埠。

如果您在 Linux 上使用 GCDS，就無法使用 Windows 信任的憑證存放區，因此必須將 Fiddler 的根憑證匯入 GCDS 的 Java 信任儲存庫。如要進一步瞭解這些步驟，請參閱「排解憑證相關問題」。

設定 SMTP 轉發主機時發生問題

如果您在設定通知的 SMTP 轉發主機時遇到問題，請嘗試以下疑難排解步驟。

連線失敗且顯示不明的 SMTP 主機訊息

1. 開啟命令提示字元。
2. 如要查看 SMTP 伺服器設定的主機名稱是否解析為 IP 位址，請輸入下列指令：

   nslookup smtp-host-name.com

連線失敗且無法連線到 SMTP 主機郵件

請檢查執行 GCDS 的伺服器是否可連線至 SMTP 主機。

1. 如要檢查連線，請在 Windows 指令列或終端機輸入下列指令：

   telnet smtp.gmail.com 587

2. 如果主機無法連線，請檢查 SMTP 伺服器的輸入防火牆規則，和 GCDS 伺服器的輸出防火牆規則。
3. 確認在 SMTP 通訊埠上有允許的流量。

記錄中顯示「無法將通訊端轉換為 TLS」錯誤

關閉憑證撤銷清單 (CRL) 檢查功能。詳情請參閱「GCDS 如何檢查憑證撤銷清單」。

如何開啟儲存於其他電腦中的 XML 檔案，或以其他使用者的身分開啟 XML 檔案？

如要開啟儲存於其他電腦中的 XML 檔案，或以其他使用者的身分在同一台電腦上開啟 XML 檔案，請參閱「使用設定檔處理作業」的操作說明。

如何從 LDAP 目錄匯出資料？

如果 GCDS 追蹤層級記錄中的 LDAP 資料與預期在 LDAP 伺服器上讀取的內容不相符 (例如找不到使用者或屬性的值不正確)，請以 LDIF 格式從 LDAP 目錄匯出資料，讓支援團隊能夠將資料與 GCDS 記錄中的 LDAP 資料進行比較。

匯出資料時，請使用 LDAP 查詢工具 (例如 ldapsearch (Linux) 或 ldifde (Windows)，並模擬 GCDS 執行時的情況：

• 使用與 GCDS 相同的連線設定。
• 使用執行 GCDS 的同一部電腦執行查詢工具。
• 使用進行 GCDS LDAP 驗證時所用的使用者名稱。

範例

GCDS 記錄不會顯示使用者的 mail 屬性，且 GCDS 搜尋規則設定如下：

• 基準 DN：ou=Ireland,dc=altostrat,dc=com
• 範圍：子樹狀結構
• 搜尋篩選器：(&(objectCategory=person)(objectClass=user))
• 伺服器：dc01.altostrat.com
• 通訊埠：636
• 通訊協定：LDAP+SSL
• 驗證使用者 DN：cn=GCDS,ou=Users,dc=altostrat,dc=com

請使用下列指令：

• Linux： ldapsearch -v -b "ou=Ireland,dc=altostrat,dc=com" -s sub -h dc01.altostrat.com -p 636 -x -Z -D "cn=GCDS,ou=Users,dc=altostrat,dc=com" "(&(objectCategory=person)(objectClass=user))" mail givenname uniqueidentifier sn > out.ldif (您可能需要視系統修改指令)。
• Windows： ldifde -f out.ldif -s dc01.altostrat.com -v -t 636 -d "ou=Ireland,dc=altostrat,dc=com" -r "(&(objectCategory=person)(objectClass=user))" -p SubTree -l mail,givenname,uniqueidentifier,sn -a "cn=GCDS,ou=Users,dc=altostrat,dc=com" PASSWORD (將 PASSWORD 替換為 GCDS 中設定的 LDAP 使用者密碼)。

如果輸出結果 (out.ldif) 不含受影響使用者的 mail 屬性，則表示 LDAP 基礎架構發生問題。原因可能與您存取 LDAP 的使用者權限有關 (例如 OpenLDAP 和 Active Directory 都允許設定屬性層級權限)。此外，如果您使用的是全域目錄通訊埠 (例如 3268 或 3269)，系統可能不會將該屬性複製到全域目錄。

如果輸出內容包含受影響使用者的 mail 屬性，請向 Google Workspace 支援團隊提供下列詳細資訊：

• out.ldif 檔案
• 執行指令所用命令提示字元或終端機視窗的螢幕截圖
  (請務必先移除密碼)。
• GCDS 追蹤層級記錄

我需要通知伺服器來執行模擬同步處理嗎？

如要執行模擬同步處理，您必須具備可傳送郵件的伺服器。如果 GCDS 是在郵件伺服器上執行，您可以使用 127.0.0.1 做為郵件伺服器的 IP 位址。或者，也可以向您的郵件管理員取得正確的郵件資訊。

為什麼 GCDS 無法透過指令列執行同步處理？

如果您使用指令列執行同步處理作業，但同步處理作業並未開始，請檢查您是否已使用指令列中的 -o 或 --oneinstance 引數。

如果您使用上述任一引數，GCDS 會建立與 XML 設定檔相關聯的 LOCK (.lock) 檔案。此外，如果在同一伺服器上發現其他 LOCK 檔案，GCDS 就不會執行同步作業，以免同時執行多個 GCDS 執行個體。

如果沒有其他正在執行的 GCDS 執行個體，請檢查伺服器上是否有其他的 LOCK 檔案。請手動刪除檔案，然後再次執行同步作業。

我的同步處理作業未完成，原因在於 API 問題嗎？

舉例來說，如果您的同步處理作業不完整，例如無法同步處理群組的所有成員，則 Directory API 可能有問題。如要確認問題是否與 API (而非 GCDS 產品) 有關，請手動呼叫 Directory API 並查看結果。如要手動呼叫 API，請從下列 2 個方法擇一使用。

方法 1：使用 API 參考資料頁面

1. 請參閱「Admin SDK API 參考資料總覽」。
2. 按一下左側的「Directory API」，然後在「REST 資源」部分前往要查詢的 REST 資源。
3. 在右側按一下您想嘗試的方法，然後點選「試試看」。

   如果 API 參考資料頁面未顯示「試試看」，請前往「方法 2：使用 OAuth 2.0 Playground」。

4. 輸入您用來授權 GCDS 的管理員憑證。

   詳情請參閱「定義您的 Google 網域設定」。

5. 請詳閱相關資訊，確保 API 如預期回應。

方法 2：使用 OAuth 2.0 Playground

1. 開啟 OAuth 2.0 Playground。
2. 選擇下列任一選項：
   • 從清單中選取範圍。
   • 從 API 參考資料頁面的「Authorization scopes」清單中複製範圍。接著，在「Input your own scopes」欄位中貼上範圍。
3. 按一下「Authorize APIs」。
4. 輸入您用來授權 GCDS 的管理員憑證。

   詳情請參閱「定義您的 Google 網域設定」。

5. 按一下「Exchange authorization code for tokens」。

   如果程序成功，系統會將您重新導向至「步驟 3：設定對 API 的要求」。

6. 填寫必要資訊。

   提示：您可以在 API 方法參考資料網頁找到大部分資訊。

7. 按一下「傳送要求」。
8. 請詳閱相關資訊，確保 API 如預期回應。

導致 EntityDoesNotExist/EntityExists (實體不存在/實體存在) 錯誤或衝突發生的原因為何？

在 XML 設定檔中設定「useDynamicMaxCacheLifetime」useDynamicMaxCacheLifetime選項，藉此將 GCDS 設為最慢每 8 天快取資料一次，並且對中小型資料集提高清除快取的頻率，以降低快取資料過時或與新資料發生衝突的機率。根據預設，3.2.1 以上版本的 GCDS 設定會自動啟用 [useDynamicMaxCacheLifetime]useDynamicMaxCacheLifetime 選項。

注意：如果發生這類錯誤，通常是因為直接在 Google 網域進行修改。使用 GCDS 進行同步處理時，請避免直接對 Google 網域進行變更。請在 LDAP 目錄中變更使用者、群組和其他實體，然後再透過 GCDS 將這些變更同步到 Google 網域。

如何修正記憶體相關錯誤？

當系統顯示記憶體相關錯誤訊息時，您必須增加 Java 虛擬機器的堆積大小，方法是編輯 GCDS 安裝目錄中的 sync-cmd.vmoptions 和 config-manager.vmoptions 檔案，相關條目如下所示：

• -Xmx1000m (針對堆積大小配置的記憶體最大值)
• -Xms64m (針對堆積大小配置的記憶體最小值)

您必須編輯 sync-cmd.vmoptions 和 config-manager.vmoptions 兩個檔案，讓系統將變更同時套用到 sync-cmd 和「設定管理員」版本。

編輯 -Xmx 參數可增加記憶體容量。在數字之後的「m」代表記憶體的容量是以 MB 計算。記憶體的正確容量視 GCDS 伺服器有多少可用記憶體，以及 GCDS 執行同步處理作業需要多少記憶體來決定。您可能需要經過數次修改，才能設定出正確的大小。如要進一步瞭解執行 GCDS 所需的可用 RAM 容量，請參閱「GCDS 系統需求」。

為何快取關閉後，GCDS 一直傳回錯誤？

這可能是設定上的問題，例如排除規則設定錯誤。這類設定錯誤可能會被 GCDS 快取隱藏。

GCDS 最多會將 Google 服務 (例如 Google Workspace 或 Cloud Identity) 的資料快取保留 8 天，也可能更快清除快取 (取決於快取資料大小)。不過，如果快取沒有清除，最多可能需要 8 天才會顯示更新。

舉例來說，您同步處理了 LDAP 資料，並在 Google 服務 (例如 Google Workspace 或 Cloud Identity) 建立了一個新群組，隨後又建立了一項排除規則，將該群組排除在後續的同步處理作業之外。如果這項排除規則因設定錯誤而無法執行，但 Google 服務中依然存在針對快取資料和這個群組執行後續同步處理的要求，那麼再次執行同步處理作業並清除快取時，這項錯誤設定就會導致這個群組從 Google 服務中遭到移除。

如何手動清除快取：

• 透過設定管理員執行同步處理作業，並選取在執行過程中清除快取的選項。
• 透過指令執行同步處理，並使用引數 -f 強制清除快取。
• 修改 XML 設定檔，將 maxCacheLifetime 值設為 0。

重要事項：強制清除快取可能會大幅增加同步處理時間。

為什麼 GCDS 正嘗試建立已存在的 Google 使用者？

如果系統顯示「409: Entity existing」的錯誤訊息，表示 GCDS 正嘗試建立已存在的 Google 使用者。如果後續進行同步作業時沒有出現錯誤，可能是因為 GCDS 快取已經過期，您就可以放心忽略這則錯誤。

如果每次執行同步作業或是每隔幾天就會發生這個問題，最可能的原因如下：

• Google 使用者排除規則過於廣泛：規則會比對出部分已經在 LDAP 目錄中的 Google 使用者。
• 查詢範圍太小：查詢結果會遺漏部分已經在 LDAP 目錄中的 Google 使用者。

這兩種情況都可能導致 GCDS 忽略已存在的 Google 使用者。如果這些使用者存在於 LDAP 使用者搜尋規則的結果中，GCDS 會嘗試在您的 Google 帳戶中建立這些使用者。

如要解決這個問題，請調整排除規則或搜尋查詢。此外，如果您想讓 GCDS 完全忽略 LDAP 目錄中的使用者，請調整 LDAP 使用者搜尋規則，或建立 LDAP 使用者排除規則。詳情請參閱「運用排除規則和查詢略過資料」。

為什麼部分使用者無法以群組成員的身分同步處理？

如要忽略任何使用者搜尋規則的結果，逕行同步處理群組成員，GCDS 會根據預設啟用 INDEPENDENT_GROUP_SYNC。如果您使用成員參照屬性來同步處理群組，GCDS 將嘗試解析 LDAP 目錄中所有使用者的電子郵件地址，而不受任何使用者搜尋規則影響。

如果只要根據使用者搜尋規則的結果來同步處理群組成員，請將 INDEPENDENT_GROUP_SYNC 從設定 XML 檔案中移除。GCDS：

• 運用使用者搜尋規則的結果來解析群組成員
• 僅以群組成員的身分同步處理「使用者同步處理作業」中的使用者
• 執行使用者搜尋規則，即使您已在「一般設定」中關閉使用者帳戶同步處理功能也一樣。

  不過，如果符合資格的使用者也屬於群組成員，則系統會以群組成員 (而非使用者) 的身分將結果同步處理至 Google。

一般來說，這並非執行同步的理想方式，特別是當您同步處理共用聯絡人，且聯絡人中包含群組成員的時候，更是如此。在這種情況下，系統不會將聯絡人以群組成員的身分同步處理。

為什麼系統在每次同步處理後都會重新建立部分使用者或群組？

設定為群組名稱屬性的 LDAP 屬性並未包含完整的電子郵件地址時，就會發生這項問題。如要解決這項問題，請檢查您的群組搜尋規則，確認 GCDS 使用完整的電子郵件地址做為群組名稱。您可以使用下列其中一種做法：

• 將群組名稱屬性設定為不同的 LDAP 屬性，為每一個群組指定完整的電子郵件地址，例如郵件。
• 在 Google 網域設定中，啟用「取代 LDAP 電子郵件地址的網域名稱」，讓您的群組名稱屬性符合 Google 端群組名稱。
• 在「群組搜尋規則」中指定群組名稱後置字元，藉此將網域名稱新增到群組名稱。

在 Active Directory 中，成員人數超過 1,500 位的群組無法順利同步處理

請確認您已在「LDAP 設定」部分的伺服器類型欄位中，選取了「MS Active Directory」。

如何使用「取代 LDAP 電子郵件地址的網域名稱」功能？

如果 LDAP 目錄中的電子郵件地址位於 Google 網域外的其他網域，則可使用此選項 (在 XML 檔案中顯示為 SUPPRESS_DOMAIN)。啟用此選項時，GCDS 會將網域部分的資訊從所有讀取到的電子郵件地址中移除。

所有處理程序都會在沒有網域名稱的情況下完成。使用根據電子郵件地址執行的排除規則時，您只需在排除規則中考量電子郵件地址的本機部分。

舉例來說，如果您關閉「Replace domain names in LDAP email addresses」(取代 LDAP 電子郵件地址的網域名稱)，在建立「完全比對」排除規則時，您必須輸入 luka@example.com 做為要比對的使用者電子郵件地址。如果您已啟用「Replace domain names in LDAP email addresses」(取代 LDAP 電子郵件地址的網域名稱)，則請使用 luka。系統會在比對前移除 @example.com 部分，因此無法比對 luka@example.com。

我可以將靜態群組和動態群組納入巢狀結構嗎？

使用 GCDS 佈建群組時，您無法將動態群組納入靜態群組的巢狀包裹中，也無法將靜態群組納入動態群組的巢狀包裹。根據 GCDS 的規則，使用者必須分別查詢靜態群組和動態群組，但巢狀結構中的所有群組都須屬於同一個查詢項目。

您可以設法將動態群組當成靜態群組進行實作，例如設定系統自動執行工作，定期查詢所有動態群組，藉此在目錄中建立靜態群組。這樣一來，GCDS 就可以使用從動態群組中建立的靜態群組進行佈建，而非佈建動態群組。

為什麼我的 LDAP 查詢傳回非預期的結果？

LDAP 查詢的結果取決於「設定管理員」設定和 LDAP 伺服器。如果 LDAP 搜尋規則傳回非預期的結果，請參閱下列疑難排解提示。請確認：

• 在「設定管理員」中正確設定 LDAP 查詢：設定搜尋規則時，請按一下「Test LDAP Query」(測試 LDAP 查詢) 進行確認。詳情請參閱「使用 LDAP 搜尋規則同步處理資料」。
• 多個查詢不會互相衝突：請確認您尚未設定會變更查詢結果的搜尋或排除規則。
• LDAP 伺服器的授權使用者具有足夠的權限：請確定您用於驗證 LDAP 伺服器的管理員可使用同一伺服器上的指令列。接著，嘗試在 LDAP 伺服器上查詢並驗證結果。

發生錯誤，導致無法建立群組

系統可能會顯示「Group ... could not created」錯誤訊息。在 GCDS 記錄中會顯示「Not Authorized to access this resource/api」(您沒有使用這個資源/API 的權限) 。

如要排解問題，請確認包含使用者和群組電子郵件地址網域的 Active Directory (AD) 屬性，與超級管理員帳戶使用的網域是否相符。

與 GCDS 同步處理後，為什麼我的網域目錄會出現重複的聯絡人？

這個問題的常見原因是同步處理共用聯絡人時未正確建立搜尋規則。

您可與 GCDS 同步處理的 2 種相關物件包括：

• 使用者個人資料：包含其他資料 (例如電話號碼或地址等) 的 Google 網域內使用者。您只能同步處理您網域內使用者的個人資料。
• 共用聯絡人：您網域內使用者需要聯絡的外部聯絡人。

如要解決這個問題，請修正共用聯絡人搜尋規則，排除您網域中的使用者。下次同步處理時，GCDS 將會嘗試刪除重複的聯絡人。在修正規則後首次同步處理時，您可能需要調整共用聯絡人刪除限制。

為什麼部分使用者無法在 Google 日曆中看到主要工作地點？

在某些情況下，當使用者排定或籌備會議時，Google 日曆會無法顯示主要工作地點。

如果遇到這個問題，請確認地點類型和區域屬性皆已設為「desk」。

為何搜尋規則沒有找到任何結果？

如果搜尋結果發生問題，請確認以下事項：

• 規則的範圍。您可能需要將範圍設為子樹狀結構。
• 您使用的搜尋規則正確無誤。
• 使用的屬性存在且可見。

您的 LDAP 查詢。請確認 LDAP 伺服器上的查詢是否使用 GCDS 中設定的管理員使用者名稱。

詳情請參閱「使用 LDAP 搜尋規則同步處理資料」。

例外規則建立完成後，為什麼系統沒有顯示確認按鈕？

可能是因為您使用的字型過大，導致螢幕無法正常顯示某些內容。字型過大時，對話方塊就無法正常運作。請變更字型大小，或是直接編輯 XML 檔案。