以下說明如何排解您在設定 Google Cloud Directory Sync (GCDS) 時可能遇到的問題。
設定與配置 | 模擬與同步 | 錯誤 | 使用者和群組 | 聯絡人和日曆 | 規則
試用 Log 分析工具
大多數情況下，這項工具很快就能確認問題癥結所在。
- 以未壓縮檔案或 ZIP 檔案的形式，將追蹤記錄提交至 Google Admin Toolbox Log 分析工具。
- 如需進階記錄分析資料，請將未壓縮檔案提交至 Log 分析工具 2。
進一步瞭解如何啟用追蹤層級記錄功能。
設定與配置
排解使用「設定管理員」時發生的設定問題如果您無法順利執行同步處理作業，請確認「設定管理員」內的設定資訊正確無誤，並記下無法通過的測試有哪些：
- 在「設定管理員」中開啟要用來設定同步處理作業的 XML 檔案。
- 在「LDAP 連線」頁面中按一下 [測試連線]，確認您可連線至 LDAP 伺服器。
- 在「通知」頁面中按一下 [測試通知]，確認您可以傳送測試通知。
- 在「同步處理」頁面中按一下「模擬同步處理」，確認您已填妥所有必填欄位且同步作業已開始執行。
在極少數的情況下，Google Cloud 支援團隊可能會要求您除了在 GCDS 啟用追蹤層級的記錄外，另外啟用完整的 HTTP 記錄。您可以使用完整的 HTTP 記錄查看 GCDS 所提出的 API 請求，以及 Google API 所提供的回應。
重要事項：完整的 HTTP 記錄可能包含高度機密資訊。請務必先移除所有機密資訊 (例如現有的 refresh_token 或 access_token 欄位)，再將記錄傳送給支援團隊。
如何啟用完整的 HTTP 記錄：
- 確認 GCDS 並未與 sync-cmd 或「設定管理員」同時運作。
- 前往 GCDS 安裝資料夾。
-
編輯 jre/lib/logging.properties 檔案。
- 在檔案最後加入以下幾行內容：
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 - 儲存檔案。
- 執行另一項 GCDS 同步處理作業 (記錄設定為「追蹤」)。
系統隨即會在 homedir (Linux) 或設定檔資料夾 (Microsoft Windows) 中建立名為 gcdshttp*.log 的記錄檔。這些檔案相當龐大，因此請一併封存。
- 刪除步驟 4 中所加入的各行內容，以免系統日後建立過大的記錄檔。
接下來請將下列檔案提供給支援小組：
- 使用的 XML 檔案。
- 最近一次同步處理的追蹤層級記錄。
-
同步處理作業產生的 gcdshttp*.log 檔案。
支援團隊可運用這些記錄掌握 Directory API 向 GCDS 所提供的資訊，以及 GCDS 的回應情形。
記錄的要求和回應內文的大小上限皆為 16 KB。如果您看到因超過此上限而遭截斷的記錄項目，請按照下文建議使用 Fiddler。
注意：如要將偵錯 Proxy (例如 Fiddler) 與 GCDS 搭配使用，您必須更新 .vmoptions 檔案，將 GCDS 設為使用 Windows 信任的憑證存放區，然後關閉 CRL 檢查功能。隨後您可以將 Fiddler 設定為 GCDS 的 Proxy 伺服器 (通常為通訊埠 8888 上的 127.0.0.1)，連線會由 Fiddler 記錄。如果您在 Linux 上使用 GCDS，就無法使用 Windows 信任的憑證存放區，因此必須將 Fiddler 的根憑證匯入 GCDS 的 Java 信任儲存庫。詳情請參閱「匯入伺服器憑證」。
如要開啟儲存於其他電腦中的 XML 檔案，或以其他使用者的身分在同一台電腦上開啟 XML 檔案，請參閱「使用設定檔處理作業」的操作說明。
如果 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 位址。或者，也可以向您的郵件管理員取得正確的郵件資訊。
如果您使用指令列執行同步處理作業，但同步處理作業並未開始，請檢查您是否已使用指令列中的 -o 或 --oneinstance 引數。
如果您使用上述任一引數，GCDS 會建立與 XML 設定檔相關聯的 LOCK (.lock) 檔案。此外，如果在同一伺服器上發現其他 LOCK 檔案，GCDS 就不會執行同步作業，以免同時執行多個 GCDS 執行個體。
如果沒有其他正在執行的 GCDS 執行個體，請檢查伺服器上是否有其他的 LOCK 檔案。請手動刪除檔案，然後再次執行同步作業。
舉例來說，如果您的同步處理作業不完整，例如無法同步處理群組的所有成員，則 Directory API 可能有問題。如要確認問題是否與 API (而非 GCDS 產品) 有關，請手動呼叫 Directory API 並查看結果。如要手動呼叫 API，請從下列 2 個方法擇一使用。
方法 1：使用 API 參考資料頁面
- 前往 Admin SDK API 參考資料總覽。
- 按一下左側的「Directory API」，然後在「REST 資源」部分前往要查詢的 REST 資源。
- 在右側按一下您想嘗試的方法，然後點選「試試看」。
如果 API 參考資料頁面未顯示「試試看」，請前往「方法 2：使用 OAuth 2.0 Playground」。
- 輸入您用來授權 GCDS 的管理員憑證。
詳情請參閱「定義您的 Google 網域設定」。
- 請詳閱相關資訊，確保 API 如預期回應。
方法 2：使用 OAuth 2.0 Playground
- 開啟 OAuth 2.0 Playground。
- 選擇下列其中一種做法：
- 從清單中選取範圍。
- 從 API 參考資料頁面的「Authorization scopes」清單中複製範圍。接著，在「Input your own scopes」欄位中貼上範圍。
- 按一下「Authorize APIs」。
- 輸入您用來授權 GCDS 的管理員憑證。
詳情請參閱「定義您的 Google 網域設定」。
- 這時請按一下「Exchange authorization code for tokens」。
如果程序成功，系統會將您重新導向至「步驟 3：設定對 API 的要求」。
- 填寫必要資訊。
提示：您可以在 API 方法參考資料網頁找到大部分資訊。
- 按一下「Send the request」。
- 請詳閱相關資訊，確保 API 如預期回應。
錯誤
導致 EntityDoesNotExist/EntityExists (實體不存在/實體存在) 錯誤或衝突發生的原因為何？在 XML 設定檔中設定「useDynamicMaxCacheLifetime」選項，藉此將 GCDS 設為最慢每 8 天快取資料一次，並且對中小型資料集提高清除快取的頻率，以降低快取資料過時或與新資料發生衝突的機率。根據預設，3.2.1 以上版本的 GCDS 設定會自動啟用 [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 最多會將 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 網域設定中，啟用「Replace domain names in LDAP email addresses」(取代 LDAP 電子郵件地址的網域名稱)，讓您的群組名稱屬性符合 Google 端群組名稱。
- 在「群組搜尋規則」中指定群組名稱後置字元，藉此將網域名稱新增到群組名稱。
請確認您已在「LDAP 設定」部分的伺服器類型欄位中，選取了「MS Active Directory」。
如果 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 查詢：設定搜尋規則時，請按一下「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 日曆會無法顯示主要工作地點。
如果您遇到這個問題，請確認地點類型和區域屬性皆已設為「desk」。
規則
為何搜尋規則找不到任何結果？如果搜尋結果發生問題，請確認以下事項：
- 規則的範圍。您可能需要將範圍設為子樹狀結構。
- 您使用的搜尋規則正確無誤。
- 使用的屬性存在且可見。
您的 LDAP 查詢。請確認 LDAP 伺服器上的查詢是否使用 GCDS 中設定的管理員使用者名稱。
詳情請參閱「使用 LDAP 搜尋規則同步處理資料」。
可能是因為您使用的字型過大，導致螢幕無法正常顯示某些內容。字型過大時，對話方塊就無法正常運作。請變更字型大小，或是直接編輯 XML 檔案。
相關主題
Google、Google Workspace 與相關符號和標誌均為 Google LLC 的商標。所有其他公司名稱和產品名稱則為相關公司的商標。
