開始使用 Git 整合

本文章將引導您在 Microsoft Fabric 的 Git 整合工具中完成下列基本工作：

• 連接到 Git 存放庫
• 提交變更
• 從 Git 更新
• 中斷與 Git 的連線

建議您先閱讀 Git 整合的概觀 ，再開始。

必要條件

若要將 Git 與 Microsoft Fabric 工作區整合，需要先為 Fabric 和 Git 設定下列必要條件。

Fabric 先決條件

若要存取 Git 整合功能，您需要 Fabric 容量。 需要 Fabric 容量才能使用所有受支援的 Fabric 元件。 如果您還沒有免費試用， 請註冊免費試用。 已經有 Power BI Premium 容量的客戶可以使用該容量，但請記住 ，某些 Power BI SKU 只支援 Power BI 專案。

此外，必須從管理入口網站啟用下列 租用戶開關 ：

• 使用者可以建立 Fabric 元件
• 用戶可以同步工作區項目與其 Git 存放庫
• 建立工作區 （只有在您想要分支至新的工作區時。
• 使用者可以同步處理工作區專案與 GitHub 存放庫：僅適用於 GitHub 使用者

視 貴組織的設定而定，租用戶系統管理員、容量管理員或工作區管理員可以啟用這些交換器。

Git 必要條件

Azure DevOps 和 GitHub 目前支援 Git 整合。 若要將 Git 整合與 Fabric 工作區搭配使用，Azure DevOps 或 GitHub 中需要滿足下列必備條件：

Azure DevOps 限制

• 註冊給同一 Fabric 使用者的 Active Azure DevOps 帳號（即使 Azure DevOps 組織位於與 Fabric 租戶不同的租戶中，仍然支援）。 建立免費帳戶。
• 存取現有儲存庫。

GitHub 限制

• 作用中的 GitHub 帳戶。 建立 GitHub 帳戶。

• 下列其中一個個人存取令牌：

  • 在存放庫許可權下具有內容讀取和寫入許可權的細部令牌（建議使用）：

    

    若要搭配 GitHub Enterprise 使用此令牌，請遵循 這些指示。

  • 建立已啟用存放庫範圍的 GitHub 傳統權杖 ：

    

將工作區連線至 Git 存放庫

連線至 Git 存放庫

只有工作區管理員可以將工作區連線到存放庫，但一旦連線，任何具有 許可權 的任何人都可以在工作區中工作。 如果您不是管理員，請向管理員尋求連線方面的協助。 若要將工作區連線至 Azure 或 GitHub 存放庫，請遵循下列步驟：

1. 登入 Fabric 並瀏覽至您想要連線的工作區。

2. 前往 [工作區設定]

   

3. 選擇 Git 整合。

4. 選取 Git 提供者。 目前支援 Azure DevOps 和 GitHub。

Azure DevOps Connect

如果您選取 [Azure DevOps]，請選取 [ 連線 ] 以自動登入已註冊至 Microsoft Entra 使用者登入 Fabric 的 Azure Repos 帳戶。

如果您已使用不同的帳戶從 Fabric 登入 Azure，請從清單中選取您的帳戶，然後選取 [連線]。

如果您是第一次從 Fabric 登入，或您想要新增帳戶，請選取 [ 新增帳戶]。

如果是第一次連線，您需要授權您的使用者。 提供下列資訊：

• 顯示名稱 - 每個使用者都必須是唯一的
• Azure DevOps URL - Azure DevOps 存放庫的 URL。 URL 必須是格式 https://dev.azure.com/{organization}/{project}/_git/{repository} 或 https://{organization}.visualstudio.com/{project}/_git/{repo}。
• 驗證 - 您可以使用 OAuth2 或 服務主體進行驗證。 欲了解更多資訊，請參閱 Azure DevOps - Git Integration with service principal

登入之後，請選取 [ 連線 ] 以允許 Fabric 存取您的帳戶

GitHub Connect

如果您選取 GitHub，則必須登入 GitHub 帳戶。 如果您已登入 GitHub，請從清單中選取您的帳戶，然後選取 [連線]。

如果您是第一次從 Fabric 登入，或您想要新增帳戶，請選取 [ 新增帳戶]。

如果這是您第一次連接，您需要 授權 您的 GitHub 帳號。 提供下列資訊：

• 顯示名稱 - 每個 GitHub 使用者都必須是唯一的
• 個人存取令牌 - 您的傳統或精細的個人存取令牌
• 存放庫 URL （選擇性） - 如果您未輸入 URL，您可以連線到您有權存取的任何存放庫。 如果您輸入網址，則只能連線到該存放庫。

登入之後，選取 [ 連線 ] 以允許 Fabric 存取您的 GitHub 帳戶。

連線到工作區

如果工作區已連線到 Azure DevOps/GitHub，請遵循 連線到共用工作區的指示。

Azure DevOps 分支連線

1. 從下拉式功能表中指定您要連線之分支的下列詳細資料：

   • 組織
   • 專案
   • Git 存放庫。
   • 分支 (使用下拉式功能表選取現有分支，或選取[+ 新增分支]以建立新的分支。您一次只能連線到一個分支。)
   • 資料夾 （輸入現有資料夾的名稱，或輸入名稱以建立新資料夾。如果您將資料夾名稱保留空白，則會在根資料夾中建立內容。您一次只能連線到一個資料夾。

GitHub 分支連線

1. 從下拉式功能表中指定您要連線之分支的下列詳細資料：

   • 存放庫 URL。 如果您使用範圍權杖連線到 GitHub，則 URL 會自動填入，您只能連線至該資料庫。
   • 分支 (使用下拉式功能表選取現有分支，或選取[+ 新增分支]以建立新的分支。您一次只能連線到一個分支。)
   • 資料夾 （輸入現有資料夾的名稱，或輸入名稱以建立新資料夾。如果您將資料夾名稱保留空白，則會在根資料夾中建立內容。您一次只能連線到一個資料夾。

選取 [連線和同步]。

在初始同步處理期間，如果工作區或 Git 分支為空，則會將內容從非空位置拷貝到空位置。 如果工作區和 Git 分支均有內容，系統會詢問同步應遵循的方向。 如需此初始同步處理的詳細資訊，請參閱 連線和同步處理。

連線之後，工作區會顯示原始檔控制的相關信息，可讓用戶檢視已連線的分支、分支中每個項目的狀態，以及上次同步的時間。

若要讓工作區與 Git 分支保持同步，請提交您在工作區中所做的 任何變更 至 Git 分支，並在任何人建立新的提交至 Git 分支時 更新您的工作區。

將變更提交至 git

成功連線到 Git 資料夾之後，請如往常一樣編輯工作區。 您儲存的任何變更只會儲存在工作區中。 準備就緒之後，您可以將變更認可至 Git 分支，也可以復原變更並還原為先前的狀態。

深入了解 提交。

提交至 Git

若要將變更認可至 Git 分支，請遵循下列步驟：

1. 前往工作區。

2. 選取 [原始檔控制] 圖示。 此圖示會顯示未認可的變更數目。

3. 從 版本控制 面板中選取 變更。 清單隨即出現，其中包含您變更的所有專案，以及指出專案是否為 新的 、 已 修改、 衝突 、 相同變更 或刪除 的圖示 。

4. 選取您要提交的項目。 若要選取所有項目，請選取頂端方塊。

5. 在框中新增註解。 如果您未新增註解，系統會自動新增預設訊息。

6. 選擇 認可。

   

提交變更後，已提交的變更項目會從清單中移除，工作區會指向已同步的新提交。

成功完成認可之後，所選取的項目的狀態會從 [未認可] 變更為 [已同步]。

復原儲存的變更

將變更儲存至工作區之後，如果您決定不想將這些變更認可至 git，您可以復原變更，並將這些專案還原為先前的狀態。 若要復原變更，請按照下列步驟執行：

1. 前往工作區。

2. 選取 [原始檔控制] 按鈕。 此按鈕也會顯示未認可的變更的數目。

3. 從原始碼控制面板選取變更。 清單隨即出現，其中包含您變更的所有專案，以及指出變更的專案是否為 新的 、 已 修改、 衝突 或刪除 的圖示 。

4. 選取您想要復原的變更。

5. 在 [我瞭解工作區專案可能已刪除且無法還原 ] 方塊中勾選，然後選取 [ 復原]。

   

6. 再次選取 復原 以確認。 您看到的對話方塊可能會有所不同，具體取決於是否偵測到將要刪除的項目。 第一個螢幕截圖顯示沒有刪除。 第二個，如果偵測到刪除。

   

   

工作區中已選取的項目會還原為工作區上次同步時的狀態。

重要

如果您刪除項目，然後復原變更，則會建立新的項目，且部分中繼資料可能會遺失。 例如，敏感度標籤不會保留且應該重設，且項目的擁有者會設定為目前使用者。

還原已新增的項目會永久刪除該項目。

從 Git 更新工作區

每當有人提交新的變更到連結的 Git 分支時，相關工作區中就會顯示通知。 使用 [原始檔] 控制面板 來提取最新的變更、合併或還原到工作區並更新實時專案。 對資料夾的變更也會進行更新。 閱讀更多關於 更新。

若要更新工作區，請按照下列步驟執行：

1. 前往工作區。
2. 選取 [原始檔控制] 圖示。
3. 從 [來源] 控制面板選取 [ 更新 ]。 隨即出現一個清單，其中包含自上次更新以來分支中已變更的所有項目。
4. 選擇 全部更新。

5. 在確認對話方塊中，選取 [更新]。

更新成功後，會移除清單，而工作區將指向同步至的新工作區。

成功完成更新之後，項目的狀態會變更為 [已同步]。

中斷工作區與 Git 的連線

只有工作區管理員可以中斷工作區與 Git 存放庫的連線。 如果您不是管理員，請向管理員尋求中斷連線方面的協助。 如果您是管理員，並且想要中斷存放庫的連線，請按照下列步驟執行：

1. 前往 [工作區設定]
2. 選取 Git 整合功能。
3. 選擇 斷開工作區
4. 再次選取 [中斷連線] 以確認。

權限

您可以對工作區採取的動作取決於您在工作區和 Git 存放庫中擁有的權限。 如需許可權的詳細討論，請參閱 許可權。

考量與限制

Git 整合的常見限制

• Fabric 中的 驗證方法 至少必須和 Git 的驗證方法一樣強。 例如，如果 Git 需要多重要素驗證，Fabric 也需要多重要素驗證。
• 目前不支援連線至 Analysis Services 的 Power BI 資料集。
• 如果您在某個工件中使用工作區身分識別並將其提交至 Git，則只能在連線至相同身分識別的工作區中更新它（返回到一個網狀架構的工作區）。 請小心，因為這也會影響分支輸出之類的功能。
• 不支援子模組。
• 不支援主權雲端服務。
• 如果你的工作區有數百個項目，可以考慮將其拆分成較小的工件集合。 每組應該放置在獨立的工作空間中，並鏈接到不同的 Git 分支，或連接到在不同資料夾中組織的單一分支。

Azure DevOps 限制

• 如果已啟用 啟用IP條件式存取原則驗證 ，則不支援 Azure DevOps。
• 如果工作區和 Git 存放庫位於兩個不同的地理區域，租用戶系統管理員必須啟用 跨地理位置匯出。
• 如果您的組織已設定 條件式存取，請確定 Power BI服務 已設定相同的 條件 ，以便驗證如預期般運作。
• 以下是適用的提交大小限制：
  • 使用 Azure DevOps 連接器搭配 Service Principal，使用 25 MB。
  • 125 MB，使用預設的單一登入（SSO）Microsoft Entra ID 帳號及 Azure DevOps 連接器，並使用 User Principal。

GitHub 限制

• 僅支援 GitHub 的雲端版本。 不提供對本地端的支援。
• GitHub 無法強制執行 跨地理位置驗證。
• 一次提交的檔案總大小限制為 50 MB。 因此，如果您有多個項目需要提交，有時可能需要將它們分成幾個獨立的提交紀錄。 如需提交檔案的詳細資訊，請參閱我們的 疑難解答指南。

GitHub Enterprise 限制

不支援某些 GitHub Enterprise 版本和設定。 例如：

• 具有數據駐留的 GitHub Enterprise Cloud (ghe.com)
• 即使該伺服器公開可存取，GitHub Enterprise Server 使用自定義網域依然不受支援。
• 架設於私人網路上的 Github Enterprise Server
• IP 允許清單

Azure DevOps 到 GitHub Enterprise 遷移考量

如果您的團隊使用 Fabric Git 整合，並正在評估從 Azure DevOps 遷移到 GitHub Enterprise，建議執行驗證測試以確保 Git 整合功能不受影響。 Fabric Git 整合依賴底層的 Git 提供者 API，這些 API 在 Azure DevOps 與 GitHub Enterprise 之間的能力與限制有所不同，如上所述。

工作區限制

• 只有工作區管理員可以管理 Git 存放庫 的連線，例如連線、中斷連線或新增分支。
  連線之後，具有 許可權 的任何人都可以在工作區中工作。
• 已安裝範本應用程式的工作區無法連線到 Git。
• MyWorkspace 無法連線到 Git 提供者。

分支和資料夾限制

• 分支名稱長度上限為 244 個字元。
• 檔案名稱的完整路徑長度上限為 250 個字元。 較長的名稱會失敗。
• 檔案大小上限為 25 MB。
• 資料夾結構最多可達到10個層級深。
• 不建議在使用 Git 整合部署報表/數據集後，從服務下載為 .pbix ，因為結果不可靠。 我們建議使用PowerBI Desktop將報表/數據集下載為 .pbix。
• 如果項目的顯示名稱具有下列任何特性，Git 資料夾會重新命名為邏輯識別碼 （Guid） 並輸入：
  • 字元數超過 256 個
  • 結尾為。或空白
  • 包含任何禁止字元，如目錄名稱限制中所述
• 當您將具有資料夾的工作區連線到 Git 時，如果該 資料夾結構 不同，則必須將變更提交到 Git 存放庫。

目錄名稱限制

• 線上至 Git 存放庫的目錄名稱具有下列命名限制：

  • 目錄名稱不能以空格或標籤開頭或結尾。
  • 目錄名稱不能包含下列任何字元：“/：<>\*|

• 專案資料夾（包含專案檔案的資料夾）不能包含下列任何字元： “：<>\*？|。 如果您將資料夾重新命名為包含這些字元之一的名稱，則 Git 無法連線或同步處理工作區，並發生錯誤。

分支限制

• 分支需要 許可權數據表中所列的許可權。
• 必須有可用的容量才能執行此動作。
• 所有 工作區 和 分支命名限制 都會在分支至新的工作區時套用。
• 新的工作區中僅提供 Git 支援的專案 。
• 相關的分支清單僅顯示您有權檢視的分支和工作區。
• 必須啟用 Git 整合。
• 擴展分支時，會建立新的分支，並且不會複製原始分支中的設定。 調整任何設定或定義，以確保新符合貴組織的原則。
• 擴展到現有工作區時：
  • 目標工作區必須支援 Git 連線。
  • 用戶必須是目標工作區的管理員。
  • 目標工作區必須具有容量。
  • 工作區不能有範本應用程式。
• 請注意，當您分支至工作區時，未儲存至 Git 的任何項目都會遺失。 建議您在分支之前提交任何您想要保留的項目。

同步與提交限制

• 你一次只能同步一個方向。 無法同時提交和更新。
• 不支援敏感度標籤，並且可能會停用匯出具有敏感度標籤的項目。 若要提交應具有但目前沒有敏感度標籤的專案，請向您的系統管理員尋求 協助。
• 適用於 有限的項目。 資料夾中不受支援的項目會略過。
• 不允許複製名稱。 即使 Power BI 允許重複名稱，更新、認可或復原動作也會失敗。
• 不支援 B2B。
• 衝突解決 是在 Git 中部分完成的。
• 在 認可 Git 程式期間，Fabric 服務會刪除不屬於專案定義之 專案資料夾內的 檔案。 不會刪除不在項目資料夾中的非相關檔案。
• 提交變更之後，您可能會注意到項目有一些您自己未做的非預期變更。 這些變更在語意上無關緊要，且可能存在多個原因。 例如：
  • 手動變更項目定義檔案。 這些變更有效，但可能不同於透過編輯器完成的變更。 例如，如果您在 Git 中重新命名語意模型的欄位，並將此變更匯入工作區，當您下一次提交語意模型的變更時，bim 檔案將會被註冊為已變更，且修改過的欄位會被推至陣列的末端columns。 這是因為產生 bim 檔案的 AS 引擎會將重新命名的數據行推送至陣列結尾。 這項變更不會影響項目的運作方式。
  • 提交一個使用 CRLF 換行符的檔案。 服務使用 LF （換行字元） 換行符。 如果您在 Git 存放庫中有使用 CRLF 換行符的檔案，當您從服務提交這些檔案時，這些檔案會被改為 LF。 例如，如果您在桌面中開啟報表，請使用CRLF儲存項目檔 （.pbip） 並將其上傳至 Git。
• 使用增強式重新整理 API 重新整理語意模型，會在每次重新整理之後產生 Git 差異。

相關內容

• 瞭解 Git 整合程式
• 管理 Git 分支
• Git 整合最佳做法